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 V         


        

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.