Rust 技巧篇 ｜ 用 `#【doc】` 属性宏改善你的文

发表于

编辑： 张汉东

说明： 本文是在原文基础上的梳理，也引入了其他内容。

属性宏的新特性介绍

从 Rust 1.54 开始，属性宏增加了类函数宏的支持。

类函数的宏可以是基于macro_rules！的声明宏，也可以是像macro！(...)那样被调用的过程宏。这对于文档注释相当有好处。如果你的项目的 README 是一个很好的文档注释，你可以使用include_str!来直接纳入其内容。以前，各种变通方法允许类似的功能，但从1.54开始，这就更符合人体工程学了。

1
rust复制代码#![doc = include_str!("README.md")]

如果你看过一些 Rust 开源项目，你应该在 lib.rs 中看到过一大堆文档注释吧？这些注释太长，导致真正的代码被挤到到最下面。有了这个功能，就可以解决这类问题了。

1
2
3
4
5
6
7
8
rust复制代码macro_rules! make_function {
    ($name:ident, $value:expr) => {
        // 这里使用 concat! 和 stringify! 构建文档注释
        #[doc = concat!("The `", stringify!($name), "` example.")]
        ///
        /// # Example
        ///
        ///
#[doc = concat!(
    "assert_eq!(", module_path!(), "::", stringify!($name), "(), ",
    stringify!($value), ");")
]
/// 
1
2
3
4
5
6
7
        pub fn $name() -> i32 {
            $value
        }
    };
}

make_function! {func_name, 123}

也可以像这样，在属性中嵌入宏调用来构建文档注释。可以对比下展开后的代码：

1
2
3
4
5
rust复制代码///The `func_name` example.
///
/// # Example
///
///

///assert_eq!(doc_attr::func_name(), 123);
/// 

1
2
3
pub fn func_name() -> i32 {
    123
}

这样的话，文档也可以复用了。当然你也可以扩展出其他用法。

其他用法

在 国外社区朋友的这篇文章中，他列举了一些应用场合。

用文档测试扩展测试能力

Rust 的文档测试相当灵活，假如你写了一些函数或者宏，你想确保它在输入某个值的时候不能编译。使用单元测试比较麻烦，但是用文档测试就很方便了。

1
2
3
rust复制代码/// ```compile_fail
#[doc = include_str!("compile_fail.rs")]
///

mod doc_test {}

1
2
3
4
5

你可以把相关测试放到 `complile_fail.rs` 中，然后使用 文档注释将其包括进来，这样在 cargo 执行测试的时候就可以进行测试了。而且对于 Rust 代码整体增加了可读性和可维护性。同样，你也可以检查 panic 等。


我们也不希望这种注释出现在最终用户的文档中，或者是编译文件中，所以需要使用 `cfg(doctest)` 来将其隐藏：

rust复制代码#[cfg(doctest)]
/// 

1
2
#[doc = include_str!("compile_fail.rs")]
///

mod doc_test {}



**本文转载自:** [掘金](https://juejin.cn/post/7007616186229719047)

*[开发者博客 – 和开发相关的 这里全都有](https://dev.newban.cn/)*
0%