From 0138d87f8f1b9f9614e439deb14cbaabad6d104c Mon Sep 17 00:00:00 2001
From: Tim Chevalier <chevalier@alum.wellesley.edu>
Date: Wed, 12 Dec 2012 16:22:30 -0800
Subject: [PATCH] Document pub use foo::* in the reference manual

r=brson

Closes #3788
---
 doc/rust.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/rust.md b/doc/rust.md
index 7a88086e0dd..a17e3dcd230 100644
--- a/doc/rust.md
+++ b/doc/rust.md
@@ -847,10 +847,25 @@ fn main() {
 
 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 public `use` declaration can therefore be used to _redirect_ some public name to a different target definition,
 even a definition with a private canonical path, inside a different module.
 If a sequence of such redirections form a cycle or cannot be unambiguously resolved, they represent a compile-time error.
 
+An example of re-exporting:
+~~~~
+mod quux {
+    mod foo {
+        pub fn bar() { }
+        pub fn baz() { }
+    }
+    
+    pub use foo::*;
+}
+~~~~
+
+In this example, the module `quux` re-exports all of the public names defined in `foo`.
+
 ### Functions
 
 A _function item_ defines a sequence of [statements](#statements) and an optional final [expression](#expressions), along with a name and a set of parameters.