doc: Document flavorful variations of paths

Closes #4293

diff --git a/src/doc/rust.md b/src/doc/rust.md
index afb21a19965b8b95ca488e679f56068e671f8574..886c95b2c75609314f6b856ef884655a1585dea8 100644 (file)
--- a/src/doc/rust.md
+++ b/src/doc/rust.md
@@ -432,7 +432,7 @@ operators](#binary-operator-expressions), or [keywords](#keywords).
 ## Paths
 
 ~~~~ {.notrust .ebnf .gram}
-expr_path : ident [ "::" expr_path_tail ] + ;
+expr_path : [ "::" ] ident [ "::" expr_path_tail ] + ;
 expr_path_tail : '<' type_expr [ ',' type_expr ] + '>'
                | expr_path ;
 
@@ -475,6 +475,51 @@ let x = id::<int>(10);         // Type arguments used in a call expression
 # }
 ~~~~
 
+Paths can be denoted with various leading qualifiers to change the meaning of
+how it is resolved:
+
+* Paths starting with `::` are considered to be global paths where the
+  components of the path start being resolved from the crate root. Each
+  identifier in the path must resolve to an item.
+
+  ```rust
+  mod a {
+      pub fn foo() {}
+  }
+  mod b {
+      pub fn foo() {
+          ::a::foo(); // call a's foo function
+      }
+  }
+  # fn main() {}
+  ```
+
+* Paths starting with the keyword `super` begin resolution relative to the
+  parent module. Each further identifier must resolve to an item
+
+  ```rust
+  mod a {
+      pub fn foo() {}
+  }
+  mod b {
+      pub fn foo() {
+          super::a::foo(); // call a's foo function
+      }
+  }
+  # fn main() {}
+  ```
+
+* Paths starting with the keyword `self` begin resolution relative to the
+  current module. Each further identifier must resolve to an item.
+
+  ```rust
+  fn foo() {}
+  fn bar() {
+      self::foo();
+  }
+  # fn main() {}
+  ```
+
 # Syntax extensions
 
 A number of minor features of Rust are not central enough to have their own