rust-lang / rust-lang/reference

Document the privacy rules for re-exports

Open
#1,558 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-visibility
Dominant language
Rust
Stars
1.6k
Forks
607
PR merge metrics
PR metrics pending

Description

The following program is rejected:

mod sub {
    fn prv() {}
    pub use prv as renamed;
}

The restrictions which cause this rejection were introduced in rfc136.

I don't think the Reference currently states these restrictions explicitly anywhere.

The current text in visibility-and-privacy.md gives the following basic rules:

Rust allows item accesses in two cases:

  1. If an item is public, then it can be accessed externally from some module m if you can access all the item's ancestor modules from m. You can also potentially be able to name the item through re-exports. See below.
  2. If an item is private, it may be accessed by the current module and its descendants.

Then under "Re-exporting and Visibility" it says:

Rust allows publicly re-exporting items through a pub use directive. Because this is a public directive, this allows the item to be used in the current module through the rules above. It essentially allows public access into the re-exported item.

I think this is most naturally read as saying that the example above is accepted, and that renamed can then be used outside sub. In any case it can't be read as saying that the example's use statement itself is rejected.

There's also the following text in use-declarations.md:

A public use declaration can therefore redirect some public name to a different target definition: even a definition with a private canonical path, inside a different module

I think this indirectly implies the existence of the restrictions.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read visibility-and-privacy.md and use-declarations.md, then compare their re-export wording with RFC 136 and the rejected example in this issue. Update the Reference so the restrictions on publicly re-exporting private items are stated explicitly and the example's rejection is unambiguous.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.