Is there a way to hide a macro pattern from docs?

Question

As of Rust 1.6.0, the generated documentation hides the implementation of each macro pattern:

Is there a way to hide some of the patterns from the Cargo-generated docs?

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

Phlegmy

Answer 1

I guess this is the optimum solution:

/// 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) );
}

This uses a separate hidden macro (which will probably need to be public) but which is not part of the documentation. All the rules that should be hidden will be hidden and the public one will be visible in the public macro which is part of the documentation.

Phlegmy

Note that if a user explicitly imports the macro (#[macro_use(public)] extern crate ...) they'll receive an error and also need to include hidden: #[macro_use(public, hidden)] extern crate.... – Commorant

I wrote an attribute macro to handle this automatically: crates.io/crates/clean-macro-docs – Archibald

Answer 2

One option is to have a dummy macro with only the public arms, and use attributes to choose which one rustdoc sees:

/// 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) };
}

Note: this will only work if you don't use the macro internally.

Archibald