Есть ли способ скрыть шаблон макроса из документации?

Question

Начиная с 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) };
}

Answer 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 макрос, который является частью документации.

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

Примечание: это будет работать, только если вы не используете макрос внутри.