Unresolved import in documentation example

Question

I'm having difficulty fixing an error inside my documentation example for my library. I have the file structure like for my crate bignum

.
|-- Cargo.lock
|-- Cargo.toml
|-- examples
|   |-- dat
|   |   `-- euler_13.dat
|   |-- debug.rs
|   `-- euler_13.rs
|-- README.md
|-- src
|   |-- error.rs
|   |-- inits.rs
|   `-- lib.rs

In my examples, my headers will look something like

// euler_13.rs 
extern crate bignum;
use bignum::inits::Zero;

// ...

This compiles and works great, but now when I'm writing an example inside my documentation at lib.rs, I can't seem to import bignum::inits::Zero

//lib.rs
//...

impl BigNum {

    //...


    /// Constructs a ...
    ///
    /// # Examples
    ///
    /// ```
    /// extern crate bignum;
    /// use bignum::inits::Zero;
    ///
    /// let a = bignum::BigNum::new(Zero::zero());
    /// ```
    ///
    pub fn new(base: BigNum) -> BigNum {
        // ...
    }

When I run cargo test, I receive this error

     Running target/debug/lib-fe3dd7a75a504b04

running 3 tests
test crate_from_u32 ... ok
test create_from_string ... ok
test adding_no_carry ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured

   Doc-tests bignum

running 1 test
test new_0 ... FAILED

failures:

---- new_0 stdout ----
    <anon>:3:9: 3:15 error: unresolved import `self::bignum::inits::Zero`. Did you mean `self::self::bignum::inits`?
<anon>:3     use self::bignum::inits::Zero;
                 ^~~~~~
error: aborting due to previous error
thread 'new_0' panicked at 'Box<Any>', /home/rustbuild/src/rust-buildbot/slave/stable-dist-rustc-linux/build/src/libsyntax/diagnostic.rs:192



failures:
    new_0

I've seen this question, but this deals with importing modules from the same file which still require toplevel scope. However here i'm still specifying top level scope with bignum::.

So while importing bignum::inits::Zero works for all of my tests and examples, it doesn't work for my docs. Why is that? I've tried appending self:: in front and receive the same error. If i change the doc examples to

extern crate bignum;

let a = bignum::BigNum::new(bignum::inits::Zero::zero());

it compiles fine however. How can I correctly import my modules?

@Shepmaster so while I think these are different questions, the other answer actually did solve my issue. I think it's because my problem is that in the `# Examples`, `extern create bignum` is implicit, so doing so again will create errors. I submitted an [issue](https://github.com/rust-lang/rust/issues/27301) with a recommendation on changing the error output for this type of error — Syntactic Fructose, Jul 26 '15 at 15:16
Off-topic: is it possible not to remove my comments when I suggest a duplicate? It's very frustrating to author a message only to see it disappeared after a while. This is the [second time](http://stackoverflow.com/questions/31609137/why-are-explicit-lifetimes-needed-in-rust) it happens. — mdup, Jul 26 '15 at 15:29
@mdup AFAIK, if the duplicate suggestion is accepted, that comment that came from the suggestion is auto removed. My only suggestion is to split it into two comments or not use the close link if you are just suggesting. — Shepmaster, Jul 26 '15 at 15:46
@Shepmaster ok, will do that next time. By the way I never used a close vote (not enough rep yet). It would be nice if the comment was restored after the question is unduplicated. — mdup, Jul 26 '15 at 16:18
@mdup if you didn't use the close link to suggest the duplicate, I'm surprised about the behavior. It may be worth asking a question on [meta]. — Shepmaster, Jul 26 '15 at 16:29

Shepmaster · Accepted Answer · 2015-07-26T16:06:58.643

15

I think the problem stems from this useful feature of the doc tests:

rustdoc will automatically add a main() wrapper around your code, and in the right place.

If you apply the rules in the link, you end up compiling code like this:

fn main() {
   extern crate bignum;
   use bignum::inits::Zero;

   let a = bignum::BigNum::new(Zero::zero());
}

You would then indeed need to refer to it as self::bignum, as the first error message suggests. Unfortunately, that won't currently work because of Rust issue 23314.

edited Jul 26 '15 at 16:06

answered Jul 26 '15 at 16:02

Shepmaster

388,571
95
1,107
1,366

ah, so that's the explanation behind **why** it doesn't work. – Syntactic Fructose Jul 26 '15 at 16:05

score 4 · Answer 2 · answered Jul 26 '15 at 15:27

So the reason this error is generated boils down to extern crate bignum implicitly being used by the documentation examples, meaning I shouldn't need to explicitly tell the example I'll be using bignum.

This makes sense because at the documentation level, examples show how the functionality of a specific part of your crate should work, so you'll be using bignum regardless. cargo recognizes this and imports bignum for you. What the example should look like is:

//lib.rs
//...

impl BigNum {

    //...


    /// Constructs a ...
    ///
    /// # Examples
    ///
    /// ```
    /// use bignum::inits::Zero;
    ///
    /// let a = bignum::BigNum::new(Zero::zero());
    /// ```
    ///
    pub fn new(base: BigNum) -> BigNum {
        // ...
    }
}

Unresolved import in documentation example

2 Answers2