(Modules) Tracking issue for `crate` as a visibility modifier

[Centril]

This is a sub-tracking issue for the RFC "Clarify and streamline paths and visibility" (rust-lang/rfcs#2126)
dealing with the question of crate as a visibility modifier.

• Implement the RFC
• Adjust documentation (see instructions on forge)
• Stabilization PR (see instructions on forge)

Unresolved questions:

• How do we parse struct Foo(crate ::bar)?

[Centril]

Comments about crate as a visibility modifier:

Parsing ambiguity

• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)

Unnatural / Confusion / Not improvement

• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
  • Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
  • Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
  • Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
  • Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
  • Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
  • Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
  • Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment) (+ heavy handed)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
  • Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment) (+ bikeshed)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)

A good idea

• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)

pub(extern) instead

• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)

Bikeshed

• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)
• Tracking issue for RFC 2126: Clarify and streamline paths and visibility #44660 (comment)

An early preview

• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/15?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/35?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/37?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/50?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/51?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/52?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/53?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/54?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/55?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/56?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/57?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/58?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/60?u=centril
• https://internals.rust-lang.org/t/rust-2018-an-early-preview/7776/62?u=centril

Dedicated thread

• https://internals.rust-lang.org/t/visibility-modifiers-pub-super-vs-super/7838

[Centril]

Personally, I am very much in favor of crate as a visibility modifier and I share @stepancheg's comment here. I think that we should encourage smaller and stricter visibilities and crate does just that.

[lilianmoraru]

I'm personally ok with writing pub(crate), the intent seems very explicit.
The example given by @johnthagen is really painful to see(using crate):

use crate::menu::{Sound, Volume};

crate mod color;

...

/// A type for storing text and an associated color it should
/// be drawn as.
crate struct ColoredText {
    crate color: types::Color,
    crate text: &'static str,
}

crate mod color; especially seems confusing, you definitely need to put a bit of thought on what's happening there.

[rpjohnst]

Some of these examples are very C-static-esque- intuitively related but really surprisingly distinct.

[Centril]

The example due to @johnthagen does not read poorly to me. In fact, it reads naturally and I quite like the symmetry. It is beautiful in a way.

If the readability of:

crate struct ColoredText {
    crate color: types::Color,
    crate text: &'static str,
}

becomes a problem; then an IDE/editor that understands the syntax of Rust can highlight the crate tokens in the different positions with different colors. That should clear up the difference well I think.

[matklad]

crate as visibility modifier is definitely weird: it uses very rust-specific keyword for a thing which is not specific to rust. Kotlin & C# use internal for this.

I'd personally would want to reuse pub for crate-visible, and go for a more screamy syntax for world visible, like pub* or pub!.

[johnthagen]

It's been brought up before, but I think the root issues I see are:

1. crate is a noun. I think pub(crate) is long and odd looking, so I fully support replacing it with something, but it did have the public adjective associated with it, so grammatically it flowed better.
2. crate is now used as the anchor for "this-crate" imports, which means something different than "wherever this is defined, it's also exported visibly from this crate"

// Here `crate` means the root of this crate.
use crate::menu::{Sound, Volume};

// Here, `crate` means: export crate::game::color
// The `crate` is referring to `color`, not the root.
crate mod color;

...

/// A type for storing text and an associated color it should
/// be drawn as.
// Same potential confusion as `crate mod color`
crate struct ColoredText {
    crate color: types::Color,
    crate text: &'static str,
}

Compared to an example, using @matklad's internal from Kotlin/C#.

use crate::menu::{Sound, Volume};

internal mod color;

...

/// A type for storing text and an associated color it should
/// be drawn as.
internal struct ColoredText {
    internal color: types::Color,
    internal text: &'static str,
}

I'm not saying internal is the right keyword (Rust likes it's very short abbreviations, and int is unfortunately full of C/C++/Java confusion), but I personally think that the second example is immediately more readable.

I also think the crate visibility keyword will be confusing to people coming to Rust from other languages. If even many of us involved enough in Rust to comment on these threads are jarred, I'd have to imagine it will trip up people new to Rust as well.

[seanmonstar]

The slightly longer syntax of pub(crate) may not be such a big deal if weren't becoming a warning/error to have pub items that aren't reachable outside the crate. I personally wish that if I had a pub(crate) struct Foo { ... }, that the compiler could realize that all the pub fns in a impl Foo are clearly not reachable, and not bother me about it.

I find it to be just busy work currently in Rust 2015 if I ever mark a type from pub struct Foo to pub(crate) struct Foo, how the compiler then yells in all the places that some other pub fns exist using the suddenly pub(crate) type, when the problem isn't real, because the other type is also pub(crate).

[johnthagen]

I also find @matklad's idea of re-purposing pub as crate-public and using export or something for world-visible exports. But that may be too big a divergence for an edition?

[rpjohnst]

Repurposing pub as crate-public and adding a new visibility for world-public was the proposal before the current version. Such a change to existing semantics was considered too drastic even for an edition, which is why pub is now keeping its current meaning.

What was less discussed and considered, I think, was repurposing pub solely via a lint. Perhaps we could switch the lint from "warn on pub that's not accessible outside the crate" to "warn on pub that is accessible outside the crate," and add a purely optional pub(extern)/export keyword. That is, don't change any semantics, just add a lint-silencing syntax.

I suspect this would be less disruptive, based on the assumption that there are fewer world-public items than crate-public items. It would also preserve the intuitive (though subtly incorrect) meaning of pub as "export from the current module" rather than confronting everyone with visibility's true behavior.