在 macro_rules! 文档中隐藏内部规则

当生成 macro_rules! 宏的文档时，rustdoc 将包括每个规则，包括仅应在您的宏内部调用的内部规则。 clean_docs 属性将隐藏您的内部规则。

示例

#[macro_export]
macro_rules! messy {
    (@impl $e:expr) => {
        format!("{}", $e)
    };
    ($e:expr) => {
        messy!(@impl $e)
    };
}

#[clean_docs]
#[macro_export]
macro_rules! clean {
    (@impl $e:expr) => {
        format!("{}", $e)
    };
    ($e:expr) => {
        clean!(@impl $e)
    };
}

将记录为

macro_rules! messy {
    (@impl $e:expr) => { ... };
    ($e:expr) => { ... };
}

macro_rules! clean {
    ($e:expr) => { ... };
}

它是如何工作的？

上面的 clean! 宏被转换为

#[macro_export]
macro_rules! clean {
    ($e:expr) => {
        $crate::__clean!(@impl $e)
    };
}

#[macro_export]
macro_rules! __clean {
    (@impl $e:expr) => {
        format!("{}", $e)
    };
}

macro_rules! clean {
    (@impl $e:expr) => {
        format!("{}", $e)
    };
    ($e:expr) => {
        clean!(@impl $e)
    };
}

最后一个非 macro_export 宏存在，因为Rust不允许通过绝对路径调用宏展开的宏（即 $crate::__clean）。

解决方案是使用不带绝对路径的本地版本来遮蔽 macro_export 宏。

参数

您可以使用这些可选参数来配置 clean_macro。

#[clean_docs(impl = "#internal", internal = "__internal_mac")]

impl

表示内部规则开头“标志”的字符串。默认为 "@"。

#[clean_docs(impl = "#internal")]
#[macro_export]
macro_rules! mac {
    (#internal $e:expr) => {
        format!("{}", $e)
    };
    ($e:expr) => {
        mac!(#internal $e)
    };
}

internal

表示用于您的宏内部版本的标识符的字符串。默认情况下，clean_docs 将两个下划线 __ 预先添加到主宏的标识符。

#[clean_docs(internal = "__internal_mac")]
#[macro_export]
macro_rules! mac {
    (@impl $e:expr) => {
        format!("{}", $e)
    };
    ($e:expr) => {
        mac!(@impl $e)
    };
}