如何为#[cfg(test)] 后面的模块生成文档？

Question

在 Rust 项目中，有一个模块带有用于支持测试的实用程序，打包在模块 test_utils:

中

#[cfg(test)]
pub mod test_utils;

有没有办法让 cargo doc 也为 test_utils 模块和里面的东西生成文档？

Answer 1

可能有多种生成测试文档的方法，但我认为更简单的方法是使用 cargo rustdoc 生成文档并通过 --cfg test 标志传递：

cargo rustdoc -- --cfg test

Answer 2

我刚刚发现这也有效：

#[cfg(any(test, doc))]
pub mod test_utils;

虽然文档是用正则生成的

cargo doc

Answer 3

我觉得#[cfg(any(test, doc))]可能还不够，会生成没有函数信息的doc。

/// The module should work
#[cfg(any(test, doc))]
pub mod test_utils {

    /// The function about test1
    #[test]
    fn test1() {
        assert!(true);
    }
}

为了记录实用程序以支持测试，也许 [cfg_attr(not(doc), test)] 是必要的。

/// The module should work
#[cfg(any(test, doc))]
pub mod test_utils {

    /// The function about test1
    #[cfg_attr(not(doc), test)]
    fn test1() {
        assert!(true);
    }
}

添加[cfg_attr(not(doc), test)]以上测试用例后：

如何为#[cfg(test)] 后面的模块生成文档？

How to generate documentation for modules that are behind #[cfg(test)]?

testing

rust

documentation

cargo