Add path changes for 2018 edition.

Author: ehuss

src/items/use-declarations.md

@@ -57,6 +57,8 @@ fn main() {
 }
 ```
 
+## `use` Visibility
+
 Like items, `use` declarations are private to the containing module, by
 default. Also like items, a `use` declaration can be public, if qualified by
 the `pub` keyword. Such a `use` declaration serves to _re-export_ a name. A
@@ -82,32 +84,32 @@ mod quux {
 In this example, the module `quux` re-exports two public names defined in
 `foo`.
 
-Also note that the paths contained in `use` items are relative to the crate
-root. So, in the previous example, the `use` refers to `quux::foo::{bar, baz}`,
-and not simply to `foo::{bar, baz}`. This also means that top-level module
-declarations should be at the crate root if direct usage of the declared
-modules within `use` items is desired. It is also possible to use `self` and
-`super` at the beginning of a `use` item to refer to the current and direct
-parent modules respectively. All rules regarding accessing declared modules in
-`use` declarations apply to both module declarations and `extern crate`
-declarations.
+## `use` Paths
+
+Paths in `use` items must start with a crate name or one of the [path
+qualifiers] `crate`, `self`, `super`, or `::`. `crate` refers to the current
+crate. `self` refers to the current module. `super` refers to the parent
+module. `::` can be used to explicitly refer to a crate, requiring an extern
+crate name to follow.
 
 An example of what will and will not work for `use` items:
+<!-- Note: This example works as-is in either 2015 or 2018. -->
 
 ```rust
 # #![allow(unused_imports)]
-use foo::baz::foobaz;    // good: foo is at the root of the crate
+use std::path::{self, Path, PathBuf};  // good: std is a crate name
+use crate::foo::baz::foobaz;    // good: foo is at the root of the crate
 
 mod foo {
 
     mod example {
         pub mod iter {}
     }
 
-    use foo::example::iter; // good: foo is at crate root
-//  use example::iter;      // bad:  example is not at the crate root
+    use crate::foo::example::iter; // good: foo is at crate root
+//  use example::iter;      // bad: relative paths are not allowed without `self`
     use self::baz::foobaz;  // good: self refers to module 'foo'
-    use foo::bar::foobar;   // good: foo is at crate root
+    use crate::foo::bar::foobar;   // good: foo is at crate root
 
     pub mod bar {
         pub fn foobar() { }
@@ -122,6 +124,33 @@ mod foo {
 fn main() {}
 ```
 
+> **Edition Differences**: In the 2015 Edition, `use` paths also allow
+> accessing items in the crate root. Using the example above, the following
+> `use` paths work in 2015 but not 2018:
+>
+> ```rust,ignore
+> use foo::example::iter;
+> use ::foo::baz::foobaz;
+> ```
+>
+> In the 2018 Edition, if an in-scope item has the same name as an external
+> crate, then `use` of that crate name requires a leading `::` to
+> unambiguously select the crate name. This is to retain compatibility with
+> potential future changes. <!-- uniform_paths future-proofing -->
+>
+> ```rust,edition2018
+> // use std::fs; // Error, this is ambiguous.
+> use ::std::fs;  // Imports from the `std` crate, not the module below.
+> use self::std::fs as self_fs;  // Imports the module below.
+>
+> mod std {
+>     pub mod fs {}
+> }
+> # fn main() {}
+> ```
+
+
 [IDENTIFIER]: identifiers.html
 [_SimplePath_]: paths.html#simple-paths
 [_Visibility_]: visibility-and-privacy.html
+[path qualifiers]: paths.html#path-qualifiers

src/paths.md

@@ -22,7 +22,7 @@ x::y::z;
 > &nbsp;&nbsp; `::`<sup>?</sup> _SimplePathSegment_ (`::` _SimplePathSegment_)<sup>\*</sup>
 >
 > _SimplePathSegment_ :\
-> &nbsp;&nbsp; [IDENTIFIER] | `super` | `self` | `$crate`
+> &nbsp;&nbsp; [IDENTIFIER] | `super` | `self` | `crate` | `$crate`
 
 Simple paths are used in [visibility] markers, [attributes], [macros], and [`use`] items.
 Examples:
@@ -45,7 +45,7 @@ mod m {
 > &nbsp;&nbsp; _PathIdentSegment_ (`::` _GenericArgs_)<sup>?</sup>
 >
 > _PathIdentSegment_ :\
-> &nbsp;&nbsp; [IDENTIFIER] | `super` | `self` | `Self` | `$crate`
+> &nbsp;&nbsp; [IDENTIFIER] | `super` | `self` | `Self` | `crate` | `$crate`
 >
 > _GenericArgs_ :\
 > &nbsp;&nbsp; &nbsp;&nbsp; `<` `>`\
@@ -152,6 +152,12 @@ Paths starting with `::` are considered to be global paths where the segments of
 start being resolved from the crate root. Each identifier in the path must resolve to an
 item.
 
+> **Edition Differences**: In the 2015 Edition, the crate root contains a variety of
+> different items, including external crates, default crates such as `std` and `core`, and
+> items in the top level of the crate (including `use` imports).
+>
+> Beginning with the 2018 Edition, paths starting with `::` can only reference crates.
+
 ```rust
 mod a {
     pub fn foo() {}
@@ -166,8 +172,8 @@ mod b {
 
 ### `self`
 
-`self` resolves the path relative to the current module. When referring to an item, `self`
-can only be used as the first segment, without a preceding `::`.
+`self` resolves the path relative to the current module. `self` can only be used as the
+first segment, without a preceding `::`.
 
 ```rust
 fn foo() {}
@@ -236,13 +242,27 @@ mod a {
 # fn main() {}
 ```
 
+### `crate`
+
+`crate` resolves the path relative to the current crate. `crate` can only be used as the
+first segment, without a preceding `::`.
+
+```rust
+fn foo() {}
+mod a {
+    fn bar() {
+        crate::foo();
+    }
+}
+# fn main() {}
+```
+
 ### `$crate`
 
 `$crate` is only used within [macro transcribers], and can only be used as the first
-segment, without a preceding `::`. When a macro is imported from a crate named `foo`,
-`$crate` will expand to `::foo`. When a macro is used in the same crate where it is
-defined, `$crate` will expand to nothing. This allows you to reliably refer to items in
-the crate where the macro is defined.
+segment, without a preceding `::`. `$crate` will expand to a path to access items from the
+top level of the crate where the macro is defined, regardless of which crate the macro is
+invoked.
 
 ```rust
 pub fn increment(x: u32) -> u32 {