Error using local modules when testing documentation

Question

I play with a small drawer to generate 2D noise. The following 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 the load test , I get the following error:

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

& anon>: error 3: 9: 3:16: unauthorized import my_math::Vec2 . Perhaps extern crate my_math ?

<anon>: 3 use my_math :: Vec2;

I also tried other forms of the use statement in the doc comment, including use my_math::*; and use self::my_math::*; . If I completely delete the line, I get a Vec2 undefined error message.

What is the right way to do this?

Answer 1

You must specify the top level name of your mailbox (call it mylib):

 use mylib::my_math::Vec2; 

The rationale is that your doc example should be used as a client by the client of your library. If you put yourself in their place, they will bring your library (usually with a load, but that doesn't matter), and then put extern crate mylib in their topple lib.rs/main.rs. Then, in order to use parts of your library, they will need to provide the full name for their children to use.

And this is exactly what you should do in your comment checked by rustdoc.

In addition, I think it's worth mentioning the relevant part of the book, Rust, Documentation as Tests , which explains some minor changes that apply to code fragments of the document. One of them:

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