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

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 {
        ...
    }
}

然而，当我运行cargo test时，出现以下错误：

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

<anon>:3:9: 3:16 错误：未解决的导入my_math :: Vec2。也许是缺少extern crate my_math？

<anon>:3 use my_math::Vec2;

我还尝试了注释中其他形式的use语句，包括use my_math :: *;和use self :: my_math :: *;。如果我完全删除此行，则会出现Vec2未定义的错误。

正确的方法是什么？

- heyx3

Answer 1

你需要指定你的包的顶层名称（我们称之为mylib）：

use mylib::my_math::Vec2;

理由是你的文档示例必须可以被库的客户直接使用。如果换做是他们，他们会获取你的库（通常通过cargo获取，但这并不重要），然后在他们的toplevel lib.rs/main.rs中放置一个extern crate mylib。然后，为了使用你库的部分内容，他们必须指定完全限定名称以使用其子项。

这正是你在rustdoc-tested注释中必须要做的事情。

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

如果示例不包含extern crate，则将插入extern crate <mycrate>;。

- mdup

---

谢谢，问题已解决！ - heyx3