1 files changed, 56 insertions, 0 deletions
diff --git a/src/doc/rust-by-example/src/mod/super.md b/src/doc/rust-by-example/src/mod/super.md
new file mode 100644
index 000000000..038d4b127
--- /dev/null
+++ b/src/doc/rust-by-example/src/mod/super.md
@@ -0,0 +1,56 @@
+# `super` and `self`
+
+The `super` and `self` keywords can be used in the path to remove ambiguity
+when accessing items and to prevent unnecessary hardcoding of paths.
+
+```rust,editable
+fn function() {
+    println!("called `function()`");
+}
+
+mod cool {
+    pub fn function() {
+        println!("called `cool::function()`");
+    }
+}
+
+mod my {
+    fn function() {
+        println!("called `my::function()`");
+    }
+    
+    mod cool {
+        pub fn function() {
+            println!("called `my::cool::function()`");
+        }
+    }
+    
+    pub fn indirect_call() {
+        // Let's access all the functions named `function` from this scope!
+        print!("called `my::indirect_call()`, that\n> ");
+        
+        // The `self` keyword refers to the current module scope - in this case `my`.
+        // Calling `self::function()` and calling `function()` directly both give
+        // the same result, because they refer to the same function.
+        self::function();
+        function();
+        
+        // We can also use `self` to access another module inside `my`:
+        self::cool::function();
+        
+        // The `super` keyword refers to the parent scope (outside the `my` module).
+        super::function();
+        
+        // This will bind to the `cool::function` in the *crate* scope.
+        // In this case the crate scope is the outermost scope.
+        {
+            use crate::cool::function as root_function;
+            root_function();
+        }
+    }
+}
+
+fn main() {
+    my::indirect_call();
+}
+```