Document usage of `extern crate` declaration in doctests

[contradictioned]

When a doctest like this is written:

///
/// ```
/// extern crate mylib;
/// use mylib::something;
/// ...
/// ```

running the tests will produce an error like:

unresolved import `mylib::something`. Did you mean `self::mylib`? [E0432]

since the test code is wrapped inside a fn main() for execution.

This is imho not clear in this algorithm description https://doc.rust-lang.org/stable/book/documentation.html

[jFransham]

This seems like a bug somewhere in rustc/cargo, rather than a problem with the docs, because

///```
///extern crate mylib;
///mylib::foo('bar');
///```

works fine, but (as was mentioned here)

///```
///extern crate mylib;
///use mylib::foo;
///foo('bar');
///```

does not. This seems like wrong behaviour. Also, the suggested

///```
///extern crate mylib;
///use self::mylib::foo;
///foo('bar');
///```

does not work either, I don't know if there is an RFC or issue open about attempting to resolve the names suggested under Did you mean ...? and only showing them if they exist.

EDIT: as mentioned below, this is not a bug with rustc or cargo, it's just that there is no way to refer to the current function scope in a use statement if you import a crate into it.

[durka]

@jFransham it's not wrong but it is very misleading. The key is that if fn main() { does not appear in the doc test, then rustdoc encloses the entire test in a main function. This, coupled with the fact that extern crate does not really work inside a function, produces the bad situation in which we find ourselves.

[steveklabnik]

Right, it's the 'entire' part that's confusing. I myself find it to be so and I wrote the sentence!

[durka]

It would be nice if rustdoc used similar heuristics to playbot, where stuff like extern crates and crate attributes get hoisted out of the generated main function.

[jFransham]

Why is extern crate even allowed inside of functions? That seems like a horrible misfeature.

[steveklabnik]

It's similar to anything else that brings a name into scope, you can do it in whatever scope you'd like.

[durka]

I guess the "real" problem is that use has no way to refer to a function/expression scope. self:: doesn't work, making the "did you mean" note less than helpful.