doc: a few minor style fixes

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