有没有办法从文档中隐藏宏模式？答案

【问题标题】：Is there a way to hide a macro pattern from docs?有没有办法从文档中隐藏宏模式？
【发布时间】：2016-06-02 22:36:14
【问题描述】：

从 Rust 1.6.0 开始，生成的文档隐藏了每个宏模式的实现：

有没有办法从 Cargo 生成的文档中隐藏一些模式？

macro_rules! mc {
    // hide this entire pattern
    (@impl, $arg:expr) => { 42 + $arg };
    // but not this one
    ($arg:expr) => { mc!(@impl, $arg) };
}

【问题讨论】：

标签： macros rust rust-cargo rustdoc

【解决方案1】：

我猜这是最佳解决方案：

/// Not meant to be called directly
#[doc(hidden)]
#[macro_export]
macro_rules! hidden {
    ( $hidden_rule1:expr ) => { ... };
    ( $hidden_rule2:expr ) => { ... };
    ...
}

#[macro_export]
macro_rules! public {
    ( $public:expr ) => ( hidden!($public) );
}

这使用了一个单独的 hidden 宏（可能需要公开），但这不是文档的一部分。所有应该隐藏的规则都将被隐藏，而公共规则将在文档中的 public 宏中可见。

【讨论】：

请注意，如果用户显式导入宏 (#[macro_use(public)] extern crate ...)，他们将收到错误消息并且还需要包含 hidden:#[macro_use(public, hidden)] extern crate...。
我写了一个属性宏来自动处理这个问题：crates.io/crates/clean-macro-docs

【解决方案2】：

一种选择是有一个只有公共手臂的虚拟宏，并使用属性来选择 rustdoc 看到的：

/// Do a thing
///
/// ```
/// # extern crate my_crate;
/// # use my_crate::mc;
/// assert_eq!(mc!(58), 100);
/// ```
#[cfg(doc)]
#[macro_export]
macro_rules! mc {
    ($arg:expr) => { ... };
}

#[cfg(not(doc))]
#[macro_export]
macro_rules! mc {
    (@impl, $arg:expr) => { 42 + $arg };
    ($arg:expr) => { mc!(@impl, $arg) };
}

注意：这仅在您不在内部使用宏时才有效。

【讨论】：