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 #4361 (comment)).

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.

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 {

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;

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,22 +23,22 @@
 //!
 //! ## 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
 //!
 //! The [`Rc`](rc/index.html) type is a non-threadsafe reference-counted pointer
 //! 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

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