Rust宏调用如何添加使用文档注释 解决unused_doc_comments警告

警告触发原因 #

/// 格式的文档注释本质是 #[doc = "注释内容"] 的语法糖，直接写在宏调用外侧时，该属性会附着在宏调用表达式本身，而宏调用不属于rustdoc的文档生成对象，因此会触发未使用文档注释的警告，注释也无法关联到宏生成的目标项上。

原代码的两个问题 #

1. 宏展开时，捕获的元属性被应用到了模块内的THE_ANSWER常量上，而非用户预期的生成模块本身
2. 文档注释写在宏调用外侧，没有作为参数传入宏的捕获列表，无法被宏纳入展开内容

正确实现代码 #

调整宏定义 #

将捕获的元属性移动到生成模块的声明前，使文档注释关联到模块：

macro_rules! foo {
    (
        $(#[$outer:meta])*
        $name:ident
    ) => {
        // 元属性应用于生成的模块
        $(#[$outer])*
        pub mod $name {
            pub const THE_ANSWER: i32 = 42;
        }
    }
}

调整宏调用方式 #

将文档注释写入宏调用的括号内，作为参数传入宏：

foo!(
    /// doc for macro created module
    bar
);

fn main() {
    println!("{}", bar::THE_ANSWER);
}

扩展用法：同时为模块和内部常量加文档 #

可以扩展宏的捕获规则，分别接收模块和常量的属性：

macro_rules! foo {
    (
        $(#[$mod_attr:meta])*
        $name:ident
        $(#[$const_attr:meta])*
    ) => {
        $(#[$mod_attr])*
        pub mod $name {
            $(#[$const_attr])*
            pub const THE_ANSWER: i32 = 42;
        }
    }
}

// 调用示例
foo!(
    /// bar模块的文档
    bar
    /// THE_ANSWER常量的文档，值固定为42
);

内容的提问来源于stack exchange，提问作者Eloff