testing - Error using local modules in documentation tests

Question

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?

Answer 1

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.