More accurate wording in the reference with regards to privacy

[golddranks]

Lately there has been some discussion about the module system and privacy. While reading this discussion, I remembered a case which is described in the reference this way:

A crate needs a global available "helper module" to itself, but it doesn't want to expose the helper module as a public API. To accomplish this, the root of the crate's hierarchy would have a private module which then internally has a "public API". Because the entire crate is a descendant of the root, then the entire local crate can access this private module through the second case.

However, the "general rules" stated above this example are slightly incongruous with this:

If an item is public, then it can be used externally through any of its public ancestors.

This isn't wrong, but nothing is said about the case where an item is public, and it has a private ancestor!

I made a short example here: https://play.rust-lang.org/?gist=5aeca813685bf1f8de0e581f259c5bdc&version=stable&backtrace=0
Here, hello() and inner_inner::hello_hello() are public, an can be used from the sibling items of its private ancestor module, because even if the module is private, it's accessible.

So the real rule (as exemplified by the example) seems not to be about the publicity, but accessibility. This is why I changed the wording to the following:

If an item is public, then it can be used externally through any of its
accessible ancestors (either by anyone that has an access to an ancestor
in the case of a chain of public ancestors,
or by the siblings of a private ancestor, in the case of a chain of public
ancestors terminating into a private ancestor).

r? @steveklabnik

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[petrochenkov]

I puzzled over this paragraph for a good minute and still don't understand what it wants to convey to the reader.

The point of these paragraphs 1 and 2 is that a private item can be used everywhere inside of its module, but not outside it, even through reexports, and pub item may be used everywhere where we can name it either directly or through reexports/aliases.
This rule applies to modules in the same way as to everything else, and the facts about "chains of public ancestors" and "siblings of a private ancestor" are some obscure consequences of this general idea (which are also incorrect in presence of reexports).

[golddranks]

I might have expressed the consequences unclearly, but my point that the paragraphs 1 and 2 don't cover every case stands. The paragraph 1 incorrectly suggests that a public item is only usable through public ancestors, but it is usable through nameable (either public, or private but local) ancestors.

[golddranks]

fn hello() is a public item. It is contained in module inner which is private. The module inner is contained within module module. hello is usable from module, but this is not directly evident from the specified rules, because they mention only "public ancestors", but here the ancestor of hello – inner – is private. I know the intent of the rules, but that could be spelled out better.

[golddranks]

If you or someone else have better ideas about the wording, I'd appreciate better suggestions.

[petrochenkov]

I think the sentence you added is better worded as something like "you can directly name the item from some module m if you can name all the item's parent modules from m" plus "you can potentially name the pub item indirectly through reexports from any other modules", but it still may be more useful to describe the intent of the rules instead.
(Removing the incorrect paragraph 1 is desirable in any case.)

[golddranks]

Rebased and reworded. Thanks, @petrochenkov

[golddranks]

In the end, I didn't use the suggested term "name", but "access", because the term "naming" as the basis of access wasn't used in the existing text, and changing that would be a more drastic change.

[bors]

☔ The latest upstream changes (presumably #40213) made this pull request unmergeable. Please resolve the merge conflicts.

[steveklabnik]

Whoops, sorry about this, @golddranks ! I didn't realize there was an outstanding PR to the reference. Can you send this into https://github.com/rust-lang-nursery/reference please? Thanks!

[golddranks]

Done!