有什么方法可以构建包含测试文档字符串的 Rust 文档吗？

Question

我们的测试方法将测试文档作为文档输出中的第一个 class 对象。具体来说，它定义了每个行为测试所测试的规范。

运行 cargo doc 在具有适当记录的测试的项目上，从测试文档字符串派生的文档方式不会产生太多，我看不到任何明显的制作方法在输出中包含测试文档字符串。

示例模块如下：

/// This function does some important stuff
pub fn working_fn() -> bool {
    true
}

#[cfg(test)]
mod tests {
    //! This is some important set of tests
    //!

    use super::*;

    /// The function should work
    #[test]
    fn it_works() {
        assert!(working_fn());
    }
}

我得到 public working_fn 的文档输出，但没有 tests 模块的文档输出。我明白另一个复杂的问题是测试是私有的，理想情况下我能够在不记录其他私有对象的情况下记录私有测试。

Answer 1

您可以引入一个新的功能标志，该标志可用于专门处理用于文档目的的测试。

将功能添加到您的 Cargo.toml:

[features]
dox = []

在您的代码中使用功能标志。

如果测试运行或提供了功能标志，则编译 tests 模块。
如果未提供功能标志，则仅标记 #[test] 功能。 #[test] 属性自动隐含 #[cfg(test)]，因此我们必须跳过它以允许该函数存在。

/// This function does some important stuff
pub fn working_fn() -> bool {
    true
}

#[cfg(any(test, feature = "dox"))]
mod tests {
    //! This is some important set of tests
    //!
    use super::*;

    /// The function should work
    #[cfg_attr(not(feature = "dox"), test)]
    fn it_works() {
        assert!(working_fn());
    }
}

构建文档

cargo doc --document-private-items --features=dox

密切关注 #[cfg(rustdoc)]，这将允许您删除对自己的功能标志的需要，但目前不稳定。

另请参阅：

ideally I'd be able to document private tests without also documenting other private objects

您可以进行测试 pub 或 pub(crate)。

如果那不是一个选项，我认为这将比它的价值更令人讨厌。我知道的直接解决方案是按照有条件地进行测试 pub 或不进行测试。

有什么方法可以构建包含测试文档字符串的 Rust 文档吗？

Is there some way to build Rust documentation that includes the test documentation strings?

unit-testing

testing

rust

bdd

rust-cargo