unit-testing - 有没有某种方法可以构建包含测试文档字符串的 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());
    }
}

我获得了公共(public) working_fn 的文档输出，但没有获得 tests 模块的文档输出。我意识到一个额外的复杂性是测试是私有(private)的，理想情况下我能够记录私有(private)测试而无需记录其他私有(private)对象。

Answer 1

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

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

[features]
dox = []

在代码中使用功能标志。

1. 如果测试正在运行或提供了功能标志，则编译测试模块。
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`?

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

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

如果这不是一个选择，我认为这会比它的值(value)更烦人。我知道的直接解决方案是遵循 How do I change a function's qualifiers via conditional compilation?有条件地进行测试 pub 或不进行测试。