Improve use_decl resolution docs.

[brandonson]

A (very small) improvement to use_decl docs, which will hopefully improve understanding of how resolution works and where [extern] mod declarations should go to make them visible to use declarations.

[huonw]

I don't think this is correct (or, at least is unclear), e.g. all the imports in

use foo::bar::baz;mod foo {useself::bar::baz;use foo::bar::qux;pubmod bar {pubfnbaz(){}pubfnqux(){}}
...
}
...

are perfectly valid.

[brandonson]

If I understood you correctly, you were referring to module bar not being at the top level and still being usable within a use declaration. Changed some wording to make it clearer that only top-level modules need be at the top level of the crate for usage in use declarations.

If I'm wrong with module declarations let me know. Most of my difficulties have been with extern mods so I've got a better understanding of extern modules than regular modules.

Also I've never actually seen self used in an import before, not sure if/how that should be mentioned.

[huonw]

If I understood you correctly, you were referring to module bar not being at the top level and still being usable within a use declaration

Yes; any module in the module hierarchy can appear in a use declaration, as long as you've got the full path to it (or use self or super to abbreviate it/avoid privacy issues).

---

Unfortunately, I still don't think this is correct, since the following is fine:

mod foo {externmod extra;useself::extra::ringbuf;}fnmain(){}

I think the "correct" documentation would be to mention self (and super) and make a special mention of extern mod (possibly even with a few examples) since this comes up so much.

self and super make the import no longer from the crate root: use self::... imports with the path starting from the current module, use super::... imports with the path starting from the direct parent of the current module.

[brandonson]

Added an example. With any luck I've managed to get close now. Not entirely sure about "top-level module declarations should be at the crate root if direct usage of the declared modules within use items is desired", but I can't think of a clearer description at the moment.

[huonw]

s/bar/extra/. And I think you should make sure this compiles when the bad ones are removed: specifically; you'll probably need pub on mod bar and fn foobar()). In fact, the bad one should be commented out (but still in the code) so that this passes the documentation tests (you'll also need fn main() {} somewhere for this to pass too).

(Also, a space after // is Rust convention.)

[brandonson]

Example compiles properly now. There's certainly more odd behaviour in use declarations that could be documented. I ran into some just from certain things being 're-exported' from module foo in some of my examples. However, I think for now this should be enough to clarify things (assuming nothing else is incorrect).

[alexcrichton]

Can you add a good example for using extra inside of foo as well?

[alexcrichton]

The clarifications look good to me now. Could you squash all the commits into one as well?

[brandonson]

Brackets and foo::extra::list example added and commits have been squashed.

[brandonson]

Managed to screw up my forked repo enough that I deleted and re-forked without thinking about what would happen to this. I'll just go ahead and make a new PR since afaik there's no way to recover this one. Sorry for any confusion that comes out of this.