auto merge of #16241 : P1start/rust/doc-fixes, r=alexcrichton

For crates `alloc`–`collections`. This is mostly just updating a few function/method descriptions to use the indicative style. 

cc #4361; I’ve sort of assumed that the third-person indicative style has been decided on, but I could update this to use the imperative style if that’s preferred, or even update this to remove all function-style-related changes. (I think that standardising on one thing, even if it’s not the ‘best’ option, is still better than having no standard at all.) The indicative style seems to be more common in the Rust standard library at the moment, especially in the newer modules (e.g. `collections::vec`), more popular in the discussion about it, and also more popular amongst other languages (see https://github.com/rust-lang/rust/issues/4361#issuecomment-33470215).

6 files changed, 180 insertions, 178 deletions

diff --git a/src/liballoc/arc.rs b/src/liballoc/arc.rs
index 1d6714430a8..0d9e4f0a1c2 100644
--- a/src/liballoc/arc.rs
+++ b/src/liballoc/arc.rs
@@ -77,7 +77,7 @@ struct ArcInner<T> {
 }
 
 impl<T: Sync + Send> Arc<T> {
-    /// Create an atomically reference counted wrapper.
+    /// Creates an atomically reference counted wrapper.
     #[inline]
     #[stable]
     pub fn new(data: T) -> Arc<T> {
@@ -101,7 +101,7 @@ impl<T: Sync + Send> Arc<T> {
         unsafe { &*self._ptr }
     }
 
-    /// Downgrades a strong pointer to a weak pointer
+    /// Downgrades a strong pointer to a weak pointer.
     ///
     /// Weak pointers will not keep the data alive. Once all strong references
     /// to the underlying data have been dropped, the data itself will be
@@ -224,7 +224,7 @@ impl<T: Sync + Send> Weak<T> {
     ///
     /// This method will fail to upgrade this reference if the strong reference
     /// count has already reached 0, but if there are still other active strong
-    /// references this function will return a new strong reference to the data
+    /// references this function will return a new strong reference to the data.
     pub fn upgrade(&self) -> Option<Arc<T>> {
         // We use a CAS loop to increment the strong count instead of a
         // fetch_add because once the count hits 0 is must never be above 0.
diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs
index 58278d5664e..6a3e1fa2862 100644
--- a/src/liballoc/boxed.rs
+++ b/src/liballoc/boxed.rs
@@ -1,4 +1,4 @@
-// Copyright 2012 The Rust Project Developers. See the COPYRIGHT
+// Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.
 //
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! A unique pointer type
+//! A unique pointer type.
 
 use core::any::{Any, AnyRefExt};
 use core::clone::Clone;
@@ -26,12 +26,14 @@ use core::result::{Ok, Err, Result};
 ///
 /// The following two examples are equivalent:
 ///
-///     use std::boxed::HEAP;
+/// ```rust
+/// use std::boxed::HEAP;
 ///
-///     # struct Bar;
-///     # impl Bar { fn new(_a: int) { } }
-///     let foo = box(HEAP) Bar::new(2);
-///     let foo = box Bar::new(2);
+/// # struct Bar;
+/// # impl Bar { fn new(_a: int) { } }
+/// let foo = box(HEAP) Bar::new(2);
+/// let foo = box Bar::new(2);
+/// ```
 #[lang = "exchange_heap"]
 #[experimental = "may be renamed; uncertain about custom allocator design"]
 pub static HEAP: () = ();
@@ -47,11 +49,11 @@ impl<T: Default> Default for Box<T> {
 
 #[unstable]
 impl<T: Clone> Clone for Box<T> {
-    /// Return a copy of the owned box.
+    /// Returns a copy of the owned box.
     #[inline]
     fn clone(&self) -> Box<T> { box {(**self).clone()} }
 
-    /// Perform copy-assignment from `source` by reusing the existing allocation.
+    /// Performs copy-assignment from `source` by reusing the existing allocation.
     #[inline]
     fn clone_from(&mut self, source: &Box<T>) {
         (**self).clone_from(&(**source));
@@ -86,7 +88,7 @@ impl<T: Ord> Ord for Box<T> {
 }
 impl<T: Eq> Eq for Box<T> {}
 
-/// Extension methods for an owning `Any` trait object
+/// Extension methods for an owning `Any` trait object.
 #[unstable = "post-DST and coherence changes, this will not be a trait but \
               rather a direct `impl` on `Box<Any>`"]
 pub trait BoxAny {
diff --git a/src/liballoc/heap.rs b/src/liballoc/heap.rs
index 3175c516d8e..e2faa3240ed 100644
--- a/src/liballoc/heap.rs
+++ b/src/liballoc/heap.rs
@@ -15,7 +15,7 @@
 #[cfg(not(test))] use core::raw;
 #[cfg(not(test))] use util;
 
-/// Return a pointer to `size` bytes of memory.
+/// Returns a pointer to `size` bytes of memory.
 ///
 /// Behavior is undefined if the requested size is 0 or the alignment is not a
 /// power of 2. The alignment must be no larger than the largest supported page
@@ -25,7 +25,7 @@ pub unsafe fn allocate(size: uint, align: uint) -> *mut u8 {
     imp::allocate(size, align)
 }
 
-/// Extend or shrink the allocation referenced by `ptr` to `size` bytes of
+/// Extends or shrinks the allocation referenced by `ptr` to `size` bytes of
 /// memory.
 ///
 /// Behavior is undefined if the requested size is 0 or the alignment is not a
@@ -41,10 +41,10 @@ pub unsafe fn reallocate(ptr: *mut u8, size: uint, align: uint,
     imp::reallocate(ptr, size, align, old_size)
 }
 
-/// Extend or shrink the allocation referenced by `ptr` to `size` bytes of
+/// Extends or shrinks the allocation referenced by `ptr` to `size` bytes of
 /// memory in-place.
 ///
-/// Return true if successful, otherwise false if the allocation was not
+/// Returns true if successful, otherwise false if the allocation was not
 /// altered.
 ///
 /// Behavior is undefined if the requested size is 0 or the alignment is not a
@@ -60,7 +60,7 @@ pub unsafe fn reallocate_inplace(ptr: *mut u8, size: uint, align: uint,
     imp::reallocate_inplace(ptr, size, align, old_size)
 }
 
-/// Deallocate the memory referenced by `ptr`.
+/// Deallocates the memory referenced by `ptr`.
 ///
 /// The `ptr` parameter must not be null.
 ///
@@ -72,14 +72,14 @@ pub unsafe fn deallocate(ptr: *mut u8, size: uint, align: uint) {
     imp::deallocate(ptr, size, align)
 }
 
-/// Return the usable size of an allocation created with the specified the
+/// Returns the usable size of an allocation created with the specified the
 /// `size` and `align`.
 #[inline]
 pub fn usable_size(size: uint, align: uint) -> uint {
     imp::usable_size(size, align)
 }
 
-/// Print implementation-defined allocator statistics.
+/// Prints implementation-defined allocator statistics.
 ///
 /// These statistics may be inconsistent if other threads use the allocator
 /// during the call.
@@ -88,7 +88,7 @@ pub fn stats_print() {
     imp::stats_print();
 }
 
-// The compiler never calls `exchange_free` on ~ZeroSizeType, so zero-size
+// The compiler never calls `exchange_free` on Box<ZeroSizeType>, so zero-size
 // allocations can point to this `static`. It would be incorrect to use a null
 // pointer, due to enums assuming types like unique pointers are never null.
 pub static mut EMPTY: uint = 12345;
diff --git a/src/liballoc/lib.rs b/src/liballoc/lib.rs
index 7809c17d938..cacb9e28989 100644
--- a/src/liballoc/lib.rs
+++ b/src/liballoc/lib.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Rust's core allocation library
+//! # The Rust core allocation library
 //!
 //! This is the lowest level library through which allocation in Rust can be
 //! performed where the allocation is assumed to succeed. This library will
@@ -23,13 +23,13 @@
 //!
 //! ## Boxed values
 //!
-//! The [`Box`](boxed/index.html) type is the core owned pointer type in rust.
+//! The [`Box`](boxed/index.html) type is the core owned pointer type in Rust.
 //! There can only be one owner of a `Box`, and the owner can decide to mutate
 //! the contents, which live on the heap.
 //!
 //! This type can be sent among tasks efficiently as the size of a `Box` value
-//! is just a pointer. Tree-like data structures are often built on owned
-//! pointers because each node often has only one owner, the parent.
+//! is the same as that of a pointer. Tree-like data structures are often built
+//! with boxes because each node often has only one owner, the parent.
 //!
 //! ## Reference counted pointers
 //!
@@ -37,8 +37,8 @@
 //! type intended for sharing memory within a task. An `Rc` pointer wraps a
 //! type, `T`, and only allows access to `&T`, a shared reference.
 //!
-//! This type is useful when inherited mutability is too constraining for an
-//! application (such as using `Box`), and is often paired with the `Cell` or
+//! This type is useful when inherited mutability (such as using `Box`) is too
+//! constraining for an application, and is often paired with the `Cell` or
 //! `RefCell` types in order to allow mutation.
 //!
 //! ## Atomically reference counted pointers
diff --git a/src/liballoc/libc_heap.rs b/src/liballoc/libc_heap.rs
index 25938ba0d54..e3fa639929f 100644
--- a/src/liballoc/libc_heap.rs
+++ b/src/liballoc/libc_heap.rs
@@ -1,4 +1,4 @@
-// Copyright 2012 The Rust Project Developers. See the COPYRIGHT
+// Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
 // file at the top-level directory of this distribution and at
 // http://rust-lang.org/COPYRIGHT.
 //
@@ -14,7 +14,7 @@
 use libc::{c_void, size_t, free, malloc, realloc};
 use core::ptr::{RawPtr, mut_null};
 
-/// A wrapper around libc::malloc, aborting on out-of-memory
+/// A wrapper around libc::malloc, aborting on out-of-memory.
 #[inline]
 pub unsafe fn malloc_raw(size: uint) -> *mut u8 {
     // `malloc(0)` may allocate, but it may also return a null pointer
@@ -30,7 +30,7 @@ pub unsafe fn malloc_raw(size: uint) -> *mut u8 {
     }
 }
 
-/// A wrapper around libc::realloc, aborting on out-of-memory
+/// A wrapper around libc::realloc, aborting on out-of-memory.
 #[inline]
 pub unsafe fn realloc_raw(ptr: *mut u8, size: uint) -> *mut u8 {
     // `realloc(ptr, 0)` may allocate, but it may also return a null pointer
diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs
index 060f9875bfc..ec19844a24a 100644
--- a/src/liballoc/rc.rs
+++ b/src/liballoc/rc.rs
@@ -8,145 +8,142 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-/*! Task-local reference-counted boxes (`Rc` type)
-
-The `Rc` type provides shared ownership of an immutable value. Destruction is
-deterministic, and will occur as soon as the last owner is gone. It is marked
-as non-sendable because it avoids the overhead of atomic reference counting.
-
-The `downgrade` method can be used to create a non-owning `Weak` pointer to the
-box. A `Weak` pointer can be upgraded to an `Rc` pointer, but will return
-`None` if the value has already been freed.
-
-For example, a tree with parent pointers can be represented by putting the
-nodes behind strong `Rc` pointers, and then storing the parent pointers as
-`Weak` pointers.
-
-
-## Examples
-
-Consider a scenario where a set of Gadgets are owned by a given Owner.  We want
-to have our Gadgets point to their Owner.  We can't do this with unique
-ownership, because more than one gadget may belong to the same Owner.  Rc
-allows us to share an Owner between multiple Gadgets, and have the Owner kept
-alive as long as any Gadget points at it.
-
-```rust
-use std::rc::Rc;
-
-struct Owner {
-    name: String
-    // ...other fields
-}
-
-struct Gadget {
-    id: int,
-    owner: Rc<Owner>
-    // ...other fields
-}
-
-fn main() {
-    // Create a reference counted Owner.
-    let gadget_owner : Rc<Owner> = Rc::new(
-            Owner { name: String::from_str("Gadget Man") }
-    );
-
-    // Create Gadgets belonging to gadget_owner.  To increment the reference
-    // count we clone the Rc object.
-    let gadget1 = Gadget { id: 1, owner: gadget_owner.clone() };
-    let gadget2 = Gadget { id: 2, owner: gadget_owner.clone() };
-
-    drop(gadget_owner);
-
-    // Despite dropping gadget_owner, we're still able to print out the name of
-    // the Owner of the Gadgets. This is because we've only dropped the
-    // reference count object, not the Owner it wraps. As long as there are
-    // other Rc objects pointing at the same Owner, it will stay alive. Notice
-    // that the Rc wrapper around Gadget.owner gets automatically dereferenced
-    // for us.
-    println!("Gadget {} owned by {}", gadget1.id, gadget1.owner.name);
-    println!("Gadget {} owned by {}", gadget2.id, gadget2.owner.name);
-
-    // At the end of the method, gadget1 and gadget2 get destroyed, and with
-    // them the last counted references to our Owner.  Gadget Man now gets
-    // destroyed as well.
-}
-```
-
-If our requirements change, and we also need to be able to traverse from
-Owner->Gadget, we will run into problems: an Rc pointer from Owner->Gadget
-introduces a cycle between the objects.  This means that their reference counts
-can never reach 0, and the objects will stay alive: a memory leak.  In order to
-get around this, we can use `Weak` pointers.  These are reference counted
-pointers that don't keep an object alive if there are no normal `Rc` (or
-*strong*) pointers left.
-
-Rust actually makes it somewhat difficult to produce this loop in the first
-place: in order to end up with two objects that point at each other, one of
-them needs to be mutable.  This is problematic because Rc enforces memory
-safety by only giving out shared references to the object it wraps, and these
-don't allow direct mutation.  We need to wrap the part of the object we wish to
-mutate in a `RefCell`, which provides *interior mutability*: a method to
-achieve mutability through a shared reference.  `RefCell` enforces Rust's
-borrowing rules at runtime.  Read the `Cell` documentation for more details on
-interior mutability.
-
-```rust
-use std::rc::Rc;
-use std::rc::Weak;
-use std::cell::RefCell;
-
-struct Owner {
-    name: String,
-    gadgets: RefCell<Vec<Weak<Gadget>>>
-    // ...other fields
-}
-
-struct Gadget {
-    id: int,
-    owner: Rc<Owner>
-    // ...other fields
-}
-
-fn main() {
-    // Create a reference counted Owner.  Note the fact that we've put the
-    // Owner's vector of Gadgets inside a RefCell so that we can mutate it
-    // through a shared reference.
-    let gadget_owner : Rc<Owner> = Rc::new(
-            Owner {
-                name: "Gadget Man".to_string(),
-                gadgets: RefCell::new(Vec::new())
-            }
-    );
-
-    // Create Gadgets belonging to gadget_owner as before.
-    let gadget1 = Rc::new(Gadget{id: 1, owner: gadget_owner.clone()});
-    let gadget2 = Rc::new(Gadget{id: 2, owner: gadget_owner.clone()});
-
-    // Add the Gadgets to their Owner.  To do this we mutably borrow from
-    // the RefCell holding the Owner's Gadgets.
-    gadget_owner.gadgets.borrow_mut().push(gadget1.clone().downgrade());
-    gadget_owner.gadgets.borrow_mut().push(gadget2.clone().downgrade());
-
-    // Iterate over our Gadgets, printing their details out
-    for gadget_opt in gadget_owner.gadgets.borrow().iter() {
-
-        // gadget_opt is a Weak<Gadget>.  Since weak pointers can't guarantee
-        // that their object is still alive, we need to call upgrade() on them
-        // to turn them into a strong reference.  This returns an Option, which
-        // contains a reference to our object if it still exists.
-        let gadget = gadget_opt.upgrade().unwrap();
-        println!("Gadget {} owned by {}", gadget.id, gadget.owner.name);
-    }
-
-    // At the end of the method, gadget_owner, gadget1 and gadget2 get
-    // destroyed.  There are now no strong (Rc) references to the gadgets.
-    // Once they get destroyed, the Gadgets get destroyed.  This zeroes the
-    // reference count on Gadget Man, so he gets destroyed as well.
-}
-```
-
-*/
+//! Task-local reference-counted boxes (the `Rc` type).
+//!
+//! The `Rc` type provides shared ownership of an immutable value. Destruction is
+//! deterministic, and will occur as soon as the last owner is gone. It is marked
+//! as non-sendable because it avoids the overhead of atomic reference counting.
+//!
+//! The `downgrade` method can be used to create a non-owning `Weak` pointer to the
+//! box. A `Weak` pointer can be upgraded to an `Rc` pointer, but will return
+//! `None` if the value has already been freed.
+//!
+//! For example, a tree with parent pointers can be represented by putting the
+//! nodes behind strong `Rc` pointers, and then storing the parent pointers as
+//! `Weak` pointers.
+//!
+//! # Examples
+//!
+//! Consider a scenario where a set of `Gadget`s are owned by a given `Owner`.
+//! We want to have our `Gadget`s point to their `Owner`. We can't do this with
+//! unique ownership, because more than one gadget may belong to the same
+//! `Owner`. `Rc` allows us to share an `Owner` between multiple `Gadget`s, and
+//! have the `Owner` kept alive as long as any `Gadget` points at it.
+//!
+//! ```rust
+//! use std::rc::Rc;
+//!
+//! struct Owner {
+//!     name: String
+//!     // ...other fields
+//! }
+//!
+//! struct Gadget {
+//!     id: int,
+//!     owner: Rc<Owner>
+//!     // ...other fields
+//! }
+//!
+//! fn main() {
+//!     // Create a reference counted Owner.
+//!     let gadget_owner : Rc<Owner> = Rc::new(
+//!             Owner { name: String::from_str("Gadget Man") }
+//!     );
+//!
+//!     // Create Gadgets belonging to gadget_owner. To increment the reference
+//!     // count we clone the Rc object.
+//!     let gadget1 = Gadget { id: 1, owner: gadget_owner.clone() };
+//!     let gadget2 = Gadget { id: 2, owner: gadget_owner.clone() };
+//!
+//!     drop(gadget_owner);
+//!
+//!     // Despite dropping gadget_owner, we're still able to print out the name of
+//!     // the Owner of the Gadgets. This is because we've only dropped the
+//!     // reference count object, not the Owner it wraps. As long as there are
+//!     // other Rc objects pointing at the same Owner, it will stay alive. Notice
+//!     // that the Rc wrapper around Gadget.owner gets automatically dereferenced
+//!     // for us.
+//!     println!("Gadget {} owned by {}", gadget1.id, gadget1.owner.name);
+//!     println!("Gadget {} owned by {}", gadget2.id, gadget2.owner.name);
+//!
+//!     // At the end of the method, gadget1 and gadget2 get destroyed, and with
+//!     // them the last counted references to our Owner. Gadget Man now gets
+//!     // destroyed as well.
+//! }
+//! ```
+//!
+//! If our requirements change, and we also need to be able to traverse from
+//! Owner → Gadget, we will run into problems: an `Rc` pointer from Owner → Gadget
+//! introduces a cycle between the objects. This means that their reference counts
+//! can never reach 0, and the objects will stay alive: a memory leak. In order to
+//! get around this, we can use `Weak` pointers. These are reference counted
+//! pointers that don't keep an object alive if there are no normal `Rc` (or
+//! *strong*) pointers left.
+//!
+//! Rust actually makes it somewhat difficult to produce this loop in the first
+//! place: in order to end up with two objects that point at each other, one of
+//! them needs to be mutable. This is problematic because `Rc` enforces memory
+//! safety by only giving out shared references to the object it wraps, and these
+//! don't allow direct mutation. We need to wrap the part of the object we wish to
+//! mutate in a `RefCell`, which provides *interior mutability*: a method to
+//! achieve mutability through a shared reference. `RefCell` enforces Rust's
+//! borrowing rules at runtime. Read the `Cell` documentation for more details on
+//! interior mutability.
+//!
+//! ```rust
+//! use std::rc::Rc;
+//! use std::rc::Weak;
+//! use std::cell::RefCell;
+//!
+//! struct Owner {
+//!     name: String,
+//!     gadgets: RefCell<Vec<Weak<Gadget>>>
+//!     // ...other fields
+//! }
+//!
+//! struct Gadget {
+//!     id: int,
+//!     owner: Rc<Owner>
+//!     // ...other fields
+//! }
+//!
+//! fn main() {
+//!     // Create a reference counted Owner. Note the fact that we've put the
+//!     // Owner's vector of Gadgets inside a RefCell so that we can mutate it
+//!     // through a shared reference.
+//!     let gadget_owner : Rc<Owner> = Rc::new(
+//!             Owner {
+//!                 name: "Gadget Man".to_string(),
+//!                 gadgets: RefCell::new(Vec::new())
+//!             }
+//!     );
+//!
+//!     // Create Gadgets belonging to gadget_owner as before.
+//!     let gadget1 = Rc::new(Gadget{id: 1, owner: gadget_owner.clone()});
+//!     let gadget2 = Rc::new(Gadget{id: 2, owner: gadget_owner.clone()});
+//!
+//!     // Add the Gadgets to their Owner. To do this we mutably borrow from
+//!     // the RefCell holding the Owner's Gadgets.
+//!     gadget_owner.gadgets.borrow_mut().push(gadget1.clone().downgrade());
+//!     gadget_owner.gadgets.borrow_mut().push(gadget2.clone().downgrade());
+//!
+//!     // Iterate over our Gadgets, printing their details out
+//!     for gadget_opt in gadget_owner.gadgets.borrow().iter() {
+//!
+//!         // gadget_opt is a Weak<Gadget>. Since weak pointers can't guarantee
+//!         // that their object is still alive, we need to call upgrade() on them
+//!         // to turn them into a strong reference. This returns an Option, which
+//!         // contains a reference to our object if it still exists.
+//!         let gadget = gadget_opt.upgrade().unwrap();
+//!         println!("Gadget {} owned by {}", gadget.id, gadget.owner.name);
+//!     }
+//!
+//!     // At the end of the method, gadget_owner, gadget1 and gadget2 get
+//!     // destroyed. There are now no strong (Rc) references to the gadgets.
+//!     // Once they get destroyed, the Gadgets get destroyed. This zeroes the
+//!     // reference count on Gadget Man, so he gets destroyed as well.
+//! }
+//! ```
 
 #![stable]
 
@@ -171,7 +168,7 @@ struct RcBox<T> {
     weak: Cell<uint>
 }
 
-/// Immutable reference counted pointer type
+/// An immutable reference-counted pointer type.
 #[unsafe_no_drop_flag]
 #[stable]
 pub struct Rc<T> {
@@ -184,7 +181,7 @@ pub struct Rc<T> {
 
 #[stable]
 impl<T> Rc<T> {
-    /// Construct a new reference-counted box
+    /// Constructs a new reference-counted pointer.
     pub fn new(value: T) -> Rc<T> {
         unsafe {
             Rc {
@@ -206,8 +203,8 @@ impl<T> Rc<T> {
 }
 
 impl<T> Rc<T> {
-    /// Downgrade the reference-counted pointer to a weak reference
-    #[experimental = "Weak pointers may not belong in this module."]
+    /// Downgrades the reference-counted pointer to a weak reference.
+    #[experimental = "Weak pointers may not belong in this module"]
     pub fn downgrade(&self) -> Weak<T> {
         self.inc_weak();
         Weak {
@@ -234,7 +231,7 @@ pub fn is_unique<T>(rc: &Rc<T>) -> bool {
 /// If the `Rc` does not have unique ownership, `Err` is returned with the
 /// same `Rc`.
 ///
-/// # Example:
+/// # Example
 ///
 /// ```
 /// use std::rc::{mod, Rc};
@@ -267,7 +264,7 @@ pub fn try_unwrap<T>(rc: Rc<T>) -> Result<T, Rc<T>> {
 ///
 /// Returns `None` if the `Rc` does not have unique ownership.
 ///
-/// # Example:
+/// # Example
 ///
 /// ```
 /// use std::rc::{mod, Rc};
@@ -312,7 +309,7 @@ impl<T: Clone> Rc<T> {
 
 #[experimental = "Deref is experimental."]
 impl<T> Deref<T> for Rc<T> {
-    /// Borrow the value contained in the reference-counted box
+    /// Borrows the value contained in the reference-counted pointer.
     #[inline(always)]
     fn deref(&self) -> &T {
         &self.inner().value
@@ -404,7 +401,7 @@ impl<T: fmt::Show> fmt::Show for Rc<T> {
     }
 }
 
-/// Weak reference to a reference-counted box
+/// A weak reference to a reference-counted pointer.
 #[unsafe_no_drop_flag]
 #[experimental = "Weak pointers may not belong in this module."]
 pub struct Weak<T> {
@@ -417,7 +414,10 @@ pub struct Weak<T> {
 
 #[experimental = "Weak pointers may not belong in this module."]
 impl<T> Weak<T> {
-    /// Upgrade a weak reference to a strong reference
+    /// Upgrades a weak reference to a strong reference.
+    ///
+    /// Returns `None` if there were no strong references and the data was
+    /// destroyed.
     pub fn upgrade(&self) -> Option<Rc<T>> {
         if self.strong() == 0 {
             None