Document extern_crate_item_prelude

Author: ehuss

src/attributes.md

@@ -554,7 +554,7 @@ You can implement `derive` for your own traits through [procedural macros].
 
 [_LiteralExpression_]: expressions/literal-expr.html
 [_SimplePath_]: paths.html#simple-paths
-[`no_implicit_prelude`]: items/modules.html
+[`no_implicit_prelude`]: items/modules.html#prelude-items
 [`no_std`]: crates-and-source-files.html#preludes-and-no_std
 [Doc comments]: comments.html#doc-comments
 [The Rustdoc Book]: ../rustdoc/the-doc-attribute.html

src/items/extern-crates.md

@@ -40,9 +40,17 @@ extern crate hello_world; // hyphen replaced with an underscore
 
 ## Extern Prelude
 
-External crates provided to the compiler are added to the "extern prelude"
-which exposes the crate names into lexical scope of every module without the
-need for specifying `extern crate`.
+External crates imported with `extern crate` in the root module or provided to
+the compiler (as with the `--extern` flag with `rustc`) are added to the
+"extern prelude". Crates in the extern prelude are in scope in the entire
+crate, including inner modules. If renamed as in `extern crate orig_name as
+new_name`, then the symbol `new_name` is added to the prelude.
+
+The `core` crate is always added to the extern prelude. The `std` crate
+is added as long as the [`no_std`] attribute is not specified.
+
+The [`no_implicit_prelude`] attribute can be used on a module to disable
+prelude lookups within that module.
 
 > **Edition Differences**: In the 2015 edition, crates in the extern prelude
 > cannot be referenced via [use declarations], so it is generally standard
@@ -51,11 +59,13 @@ need for specifying `extern crate`.
 > Beginning in the 2018 edition, [use declarations] can reference crates in
 > the extern prelude, so it is considered unidiomatic to use `extern crate`.
 
-> **Note**: Additional crates that ship with `rustc`, such as [`proc_macro`],
-> [`alloc`], and [`test`], currently aren't available in the extern prelude
-> and must be brought into scope with an `extern crate` declaration, even in
-> the 2018 edition. `use` paths must reference the `extern crate` item (such
-> as using [`crate::`] or [`self::`] path prefixes).
+> **Note**: Crates not explicitly named with the `--extern` flag with `rustc`
+> are not included in the extern prelude. This means that additional crates
+> that ship with `rustc`, such as [`proc_macro`], [`alloc`], and [`test`],
+> currently aren't available in the extern prelude and must be brought into
+> scope with an `extern crate` declaration, even in the 2018 edition. `use`
+> paths must reference the `extern crate` item (such as using [`crate::`] or
+> [`self::`] path prefixes).
 >
 > ```rust
 > extern crate proc_macro;
@@ -67,13 +77,10 @@ need for specifying `extern crate`.
 > ```
 
 <!--
-Possible upcoming changes that will change this:
-The `extern_crate_item_prelude` unstable feature allows `extern crate` to
-update the extern prelude in certain situations, see
-https://github.com/rust-lang/rust/pull/54658
-Unstable `--extern proc_macro` flag that would force the crate into the
-extern prelude.
-    https://github.com/rust-lang/rust/pull/54116
+The proc_macro/alloc/test limitation may be lifted if the `--extern`
+flag is stabilized and used. See tracking issue
+https://github.com/rust-lang/rust/issues/57288 and the unstable
+`--extern` flag added in https://github.com/rust-lang/rust/pull/54116.
 -->
 
 ## Underscore Imports
@@ -91,6 +98,8 @@ into the macro-use prelude.
 [`#[macro_use]` attribute]: attributes.html#macro-related-attributes
 [`alloc`]: https://doc.rust-lang.org/alloc/
 [`crate::`]: paths.html#crate
+[`no_implicit_prelude`]: items/modules.html#prelude-items
+[`no_std`]: crates-and-source-files.html#preludes-and-no_std
 [`proc_macro`]: https://doc.rust-lang.org/proc_macro/
 [`self::`]: paths.html#self
 [`test`]: https://doc.rust-lang.org/test/