Merge pull request #132 from Havvy/follow-the-path

Canonical Paths

Author: steveklabnik

src/items/constant-items.md

@@ -6,23 +6,17 @@ wherever they are used, meaning that they are copied directly into the relevant
 context when used. References to the same constant are not necessarily
 guaranteed to refer to the same memory address.
 
-[constant value]: expressions.html#constant-expressions
-
 Constant values must not have destructors, and otherwise permit most forms of
 data. Constants may refer to the address of other constants, in which case the
 address will have elided lifetimes where applicable, otherwise – in most cases
 – defaulting to the `static` lifetime. (See below on [static lifetime
 elision].) The compiler is, however, still at liberty to translate the constant
 many times, so the address referred to may not be stable.
 
-[static lifetime elision]: items/static-items.html#static-lifetime-elision
-
 Constants must be explicitly typed. The type may be any type that doesn't
 implement [`Drop`] and has a `'static` lifetime: any references it contains
 must have `'static` lifetimes.
 
-[`Drop`]: the-drop-trait.html
-
 ```rust
 const BIT1: u32 = 1 << 0;
 const BIT2: u32 = 1 << 1;
@@ -40,3 +34,7 @@ const BITS_N_STRINGS: BitsNStrings<'static> = BitsNStrings {
     mystring: STRING,
 };
 ```
+
+[constant value]: expressions.html#constant-expressions
+[static lifetime elision]: items/static-items.html#static-lifetime-elision
+[`Drop`]: the-drop-trait.html

src/paths.md

@@ -5,29 +5,18 @@ a namespace qualifier (`::`). If a path consists of only one component, it may
 refer to either an [item] or a [variable] in a local control
 scope. If a path has multiple components, it refers to an item.
 
-[item]: items.html
-[variable]: variables.html
-
-Every item has a _canonical path_ within its crate, but the path naming an item
-is only meaningful within a given crate. There is no global namespace across
-crates; an item's canonical path merely identifies it within the crate.
-
 Two examples of simple paths consisting of only identifier components:
 
 ```rust,ignore
 x;
 x::y::z;
 ```
 
-Path components are usually [identifiers], but they may
-also include angle-bracket-enclosed lists of type arguments. In
-[expression] context, the type argument list is given
-after a `::` namespace qualifier in order to disambiguate it from a
-relational expression involving the less-than symbol (`<`). In type
-expression context, the final namespace qualifier is omitted.
-
-[identifiers]: identifiers.html
-[expression]: expressions.html
+Path components are usually [identifiers], but they may also include
+angle-bracket-enclosed lists of type arguments. In [expression] context, the
+type argument list is given after a `::` namespace qualifier in order to
+disambiguate it from a relational expression involving the less-than symbol
+(`<`). In type expression context, the final namespace qualifier is omitted.
 
 Two examples of paths with type arguments:
 
@@ -103,3 +92,79 @@ mod a {
 }
 # fn main() {}
 ```
+
+## Canonical paths
+
+Items defined in a module or implementation have a *canonical path* that
+corresponds to where within its crate it is defined. All other paths to these
+items are aliases. The canonical path is defined as a *path prefix* appended by
+the path component the item itself defines.
+
+[Implementations] and [use declarations] do not have canonical paths, although
+the items that implementations define do have them. Items defined in
+block expressions do not have canonical paths. Items defined in a module that
+does not have a canonical path do not have a canonical path. Associated items
+defined in an implementation that refers to an item without a canonical path,
+e.g. as the implementing type, the trait being implemented, a type parameter or
+bound on a type parameter, do not have canonical paths.
+
+The path prefix for modules is the canonical path to that module. For bare
+implementations, it is the canonical path of the item being implemented
+surrounded by angle (`<>`) brackets. For trait implementations, it is the
+canonical path of the item being implemented followed by `as` followed by the
+canonical path to the trait all surrounded in angle (`<>`) brackets. 
+
+The canonical path is only meaningful within a given crate. There is no global
+namespace across crates; an item's canonical path merely identifies it within
+the crate.
+
+```rust
+// Comments show the canonical path of the item.
+
+mod a { // ::a
+    pub struct Struct; // ::a::Struct
+
+    pub trait Trait { // ::a::Trait
+        fn f(&self); // a::Trait::f
+    }
+
+    impl Trait for Struct {
+        fn f(&self) {} // <::a::Struct as ::a::Trait>::f
+    }
+
+    impl Struct {
+        fn g(&self) {} // <::a::Struct>::g
+    }
+}
+
+mod without { // ::without
+    fn canonicals() { // ::without::canonicals
+        struct OtherStruct; // None
+
+        trait OtherTrait { // None
+            fn g(&self); // None
+        }
+
+        impl OtherTrait for OtherStruct {
+            fn g(&self) {} // None
+        }
+
+        impl OtherTrait for ::a::Struct {
+            fn g(&self) {} // None
+        }
+
+        impl ::a::Trait for OtherStruct {
+            fn f(&self) {} // None
+        }
+    }
+}
+
+# fn main() {}
+```
+[item]: items.html
+[variable]: variables.html
+[identifiers]: identifiers.html
+[expression]: expressions.html
+[implementations]: items/implementations.html
+[modules]: items/modules.html
+[use declarations]: items/use_declarations.html