Skip to content
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

Closed
wants to merge 2 commits into from
Closed

Improve use_decl resolution docs. #8597

wants to merge 2 commits into from

Conversation

brandonson
Copy link
Contributor

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
Copy link
Member

huonw commented Aug 18, 2013

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.

@brandonson
Copy link
Contributor Author

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
Copy link
Member

huonw commented Aug 18, 2013

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 {
    extern mod extra;
    use self::extra::ringbuf;
}

fn main() {}

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
Copy link
Contributor Author

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.

mod foo{
extern mod extra;

use bar::ringbuf; //bad: extra is not at the crate root
Copy link
Member

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.)

@brandonson
Copy link
Contributor Author

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
Copy link
Member

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?

@alexcrichton
Copy link
Member

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

@brandonson
Copy link
Contributor Author

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

@brandonson
Copy link
Contributor Author

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.

@brandonson brandonson closed this Aug 20, 2013
osaut pushed a commit to osaut/rust that referenced this pull request Oct 31, 2013
…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.
flip1995 pushed a commit to flip1995/rust that referenced this pull request Apr 7, 2022
Fix version in changelog

changelog: none
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants