Merge pull request #509 from ehuss/extern_crate_item_prelude

Document extern_crate_item_prelude

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 imported with `extern crate orig_name as
+new_name`, then the symbol `new_name` is instead 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 in the crate root.
+
+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
@@ -52,28 +60,20 @@ need for specifying `extern crate`.
 > 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).
+> [`alloc`], and [`test`], are not automatically included with the `--extern`
+> flag when using Cargo. They must be brought into scope with an `extern
+> crate` declaration, even in the 2018 edition.
 >
 > ```rust
 > extern crate proc_macro;
-> // Cannot reference `proc_macro` directly because it is not in the extern prelude.
-> // use proc_macro::TokenStream;
-> // Instead, you must reference the item in scope from the `extern crate`
-> // declaration.
-> use self::proc_macro::TokenStream;
+> use proc_macro::TokenStream;
 > ```
 
 <!--
-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 +91,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/