在文档测试中使用本地模块时出错

Question

我正在玩一个用于生成 2D 噪声的小板条箱。这是我的“lib.rs”文件的简化片段：

pub mod my_math {
    pub struct Vec2<T> {
        ...
    }
    ...
}
pub mod my_noise {
    use num::Float;
    use std::num::Wrapping;
    use my_math::*;

    /// Gets pseudo-random noise based on a seed vector.
    /// 
    /// # Examples
    /// 
    /// ```
    /// use my_math::Vec2;
    /// 
    /// let v_seed = Vec2::<f32>::new_values(4.134, -23.141);
    /// let noise_val = get_noise_white(&v_seed);
    /// 
    /// assert!(noise_val >= 0.0);
    /// assert!(noise_val <= 1.0);
    /// ```
    pub fn get_noise_white(seed: &Vec2<f32>) -> f32 {
        ...
    }
}

然而，当我运行货物测试时，我得到以下错误：

---- my_noise::get_noise_white_0 stdout ----

<anon>:3:9: 3:16 error: unresolved import my_math::Vec2. Maybe a missing extern crate my_math?

<anon>:3 use my_math::Vec2;

我也在文档注释中尝试了其他形式的use语句，包括use my_math::*;和use self::my_math::*;。如果我完全删除该行，则会收到 Vec2 未定义的错误。

正确的做法是什么？

Answer 1

您必须指定您的 crate 的顶层名称（我们称之为 mylib）：

use mylib::my_math::Vec2;

基本原理是您的文档示例必须可供图书馆的客户按原样使用。如果你设身处地为他们着想，他们会获取你的库（通常是通过 cargo，但这并不重要），然后将 extern crate mylib 放入他们的顶级库中。rs/main.rs。然后，为了使用您的库的某些部分，他们必须指定完全限定名称才能使用其子项。

这正是您在经过 rustdoc 测试的评论中必须要做的。

此外，我认为值得引用 Rust 书的相关部分，Documentation as tests，它解释了对文档代码片段的一些小修改。其中之一是：

If the example does not contain extern crate, then extern crate <mycrate>; is inserted.

在文档测试中使用本地模块时出错

Error using local modules in documentation tests

testing

documentation

module

rust