-
Notifications
You must be signed in to change notification settings - Fork 13k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve use_decl resolution docs. #8597
Conversation
I don't think this is correct (or, at least is unclear), e.g. all the imports in use foo::bar::baz;
mod foo {
use self::bar::baz;
use foo::bar::qux;
pub mod bar {
pub fn baz() {}
pub fn qux() {}
}
...
}
... are perfectly valid. |
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. |
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 Unfortunately, I still don't think this is correct, since the following is fine: mod foo {
extern mod extra;
use self::extra::ringbuf;
}
fn main() {} I think the "correct" documentation would be to mention
|
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 |
mod foo{ | ||
extern mod extra; | ||
|
||
use bar::ringbuf; //bad: extra is not at the crate root |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.)
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). |
mod foo{ | ||
extern mod extra; | ||
|
||
// use extra::*; // bad: extra is not at the crate root |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you add a good
example for using extra
inside of foo
as well?
The clarifications look good to me now. Could you squash all the commits into one as well? |
Brackets and foo::extra::list example added and commits have been squashed. |
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. |
…inger Attempt rust-lang#2 of [this pull request](rust-lang#8597) since my tired mind decided messing up my repo, then deleting and re-forking was a good idea. This is identical to the second last commit in that PR. (The one before I ruined everything.) This is an improvement to use_decl docs, which will hopefully improve understanding of how resolution works and where `extern mod` and module declarations should go to make them visible to use declarations.
Fix version in changelog changelog: none
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.