有没有某种方法可以构建包含测试文档字符串的 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模块的文档输出。我意识到一个额外的复杂性是测试是私有的，理想情况下我能够记录私有测试而无需记录其他私有对象。

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());
    }
}

构建文档

[features]
dox = []

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

也可以看看：

• 是否可以有条件地启用“derive”等属性？

理想情况下，我能够记录私有测试，而无需记录其他私有对象

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

如果这不是一个选择，我认为这会比它的价值更烦人。我知道的直接解决方案是遵循如何通过条件编译更改函数的限定符？pub有条件地进行或不进行测试。