在文档测试中使用本地模块时出错 [英] Error using local modules in documentation tests

问题描述

我正在玩一个小型的箱子来产生二维噪声。以下是我的lib.rs文件的简化片段：

  pub mod my_math {
 pub struct Vec2 < T> {
 ... 
} 
 ... 
} 
 pub mod my_noise {
 use num :: Float; 
使用std :: num :: Wrapping; 
使用my_math :: *; 
 
 ///基于种子向量获取伪随机噪声。 
 /// 
 ///＃示例
 /// 
 ///```
 ///使用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错误：未解决的导入 my_math :: Vec2 。可能是一个缺少的 extern crate my_math ？

< anon>：3使用my_math :: Vec2;

我还尝试在文档评论中使用使用语句的其他形式，包括使用my_math :: *; 和使用self :: my_math :: *; 。如果我完全删除该行，那么我收到一个错误， Vec2 未定义。

正确的方式是什么

解决方案

您必须指定您的箱子的toplevel名称（我们称之为mylib）：

 使用mylib :: my_math :: Vec2; 
  

理由是您的文档示例必须由您的库的客户端按原样使用。如果你把自己放在自己的鞋子里，他们会拿到你的图书馆（通常是货物，但没关系），然后在他们的toplevel lib里放一个$ code> extern crate mylib 。 RS / main.rs。然后，为了使用您的库的部分，他们必须指定完全限定名称才能使用其子级。

这正是您在经过验证的评论中必须做的。

另外，我认为值得引用到Rust书的相关部分，文档作为测试，其中解释了一些适用于文档代码片段的小修改。其中一个是：

如果该示例不包含 extern crate ，那么 extern crate< mycrate> ;; 被插入。

I'm playing around with a small crate for 2D noise generation. Here is a simplified snippet of my "lib.rs" file:

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

However, when I run cargo test, I get the following error:

---- 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;

I have also tried other forms of the use statement in the doc comment, including use my_math::*; and use self::my_math::*;. If I remove the line entirely, then I get an error that Vec2 is undefined.

What is the correct way to do this?

解决方案

You must specify the toplevel name of your crate (let's call it mylib):

use mylib::my_math::Vec2;

The rationale is that your doc example must be usable as-is by a client of your library. If you put yourself in their shoes, they would fetch your library (usually by cargo, but it doesn't matter) and then put an extern crate mylib in their toplevel lib.rs/main.rs. Then, in order to use parts of your library, they would have to specify the fully qualified name in order to use its children.

And that's exactly what you have to do in your rustdoc-tested comment.

Also, I think it's worth quoting to the relevant part of the Rust book, Documentation as tests, which explains some minor modifications applied to doc-code snippets. One of them is:

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

这篇关于在文档测试中使用本地模块时出错的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！