有没有办法构建包含测试文档字符串的 Rust 文档？

Question

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

在具有适当记录的测试的项目上运行 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());
    }
}

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

Answer 1

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

将该功能添加到您的 Cargo.toml：

[features]
dox = []

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

1. 如果测试正在运行，则编译 tests 模块或提供了功能标志。
2. 仅在未提供功能标志时标记#[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)]，这将使您无需使用自己的功能标志，但目前还不稳定。

另见：

• Is it possible to conditionally enable an attribute like `derive`?

理想情况下，我可以在不记录其他私有对象的情况下记录私有测试

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

如果这不是一个选项，我认为这将比它的价值更烦人。我知道的直接解决方案是按照How do I change a function's qualifiers via conditional compilation? 有条件地进行测试pub。