Require documentation by default for libstd

Adds documentation for various things that I understand.
Adds #[allow(missing_doc)] for lots of things that I don't understand.

src/libstd/at_vec.rs

@@ -101,6 +101,9 @@ pub fn build_sized_opt<A>(size: Option<uint>,
 }
 
 // Appending
+
+/// Iterates over the `rhs` vector, copying each element and appending it to the
+/// `lhs`. Afterwards, the `lhs` is then returned for use again.
 #[inline(always)]
 pub fn append<T:Copy>(lhs: @[T], rhs: &const [T]) -> @[T] {
     do build_sized(lhs.len() + rhs.len()) |push| {
@@ -211,6 +214,9 @@ pub unsafe fn set_len<T>(v: @[T], new_len: uint) {
         (**repr).unboxed.fill = new_len * sys::size_of::<T>();
     }
 
+    /**
+     * Pushes a new value onto this vector.
+     */
     #[inline(always)]
     pub unsafe fn push<T>(v: &mut @[T], initval: T) {
         let repr: **VecRepr = transmute_copy(&v);
@@ -223,7 +229,7 @@ pub unsafe fn push<T>(v: &mut @[T], initval: T) {
     }
 
     #[inline(always)] // really pretty please
-    pub unsafe fn push_fast<T>(v: &mut @[T], initval: T) {
+    unsafe fn push_fast<T>(v: &mut @[T], initval: T) {
         let repr: **mut VecRepr = ::cast::transmute(v);
         let fill = (**repr).unboxed.fill;
         (**repr).unboxed.fill += sys::size_of::<T>();
@@ -232,7 +238,7 @@ pub unsafe fn push_fast<T>(v: &mut @[T], initval: T) {
         move_val_init(&mut(*p), initval);
     }
 
-    pub unsafe fn push_slow<T>(v: &mut @[T], initval: T) {
+    unsafe fn push_slow<T>(v: &mut @[T], initval: T) {
         reserve_at_least(&mut *v, v.len() + 1u);
         push_fast(v, initval);
     }

src/libstd/cast.rs

@@ -27,6 +27,7 @@ pub unsafe fn transmute_copy<T, U>(src: &T) -> U {
     dest
 }
 
+/// Casts the value at `src` to U. The two types must have the same length.
 #[cfg(target_word_size = "32", not(stage0))]
 #[inline(always)]
 pub unsafe fn transmute_copy<T, U>(src: &T) -> U {
@@ -37,6 +38,7 @@ pub unsafe fn transmute_copy<T, U>(src: &T) -> U {
     dest
 }
 
+/// Casts the value at `src` to U. The two types must have the same length.
 #[cfg(target_word_size = "64", not(stage0))]
 #[inline(always)]
 pub unsafe fn transmute_copy<T, U>(src: &T) -> U {

src/libstd/cell.rs

@@ -23,6 +23,7 @@
 
 #[mutable]
 #[deriving(Clone, DeepClone, Eq)]
+#[allow(missing_doc)]
 pub struct Cell<T> {
     priv value: Option<T>
 }
@@ -32,6 +33,7 @@ pub fn Cell<T>(value: T) -> Cell<T> {
     Cell { value: Some(value) }
 }
 
+/// Creates a new empty cell with no value inside.
 pub fn empty_cell<T>() -> Cell<T> {
     Cell { value: None }
 }

src/libstd/char.rs

@@ -53,8 +53,12 @@
     Cn  Unassigned              a reserved unassigned code point or a noncharacter
 */
 
+/// Returns whether the specified character is considered a unicode alphabetic
+/// character
 pub fn is_alphabetic(c: char) -> bool   { derived_property::Alphabetic(c) }
+#[allow(missing_doc)]
 pub fn is_XID_start(c: char) -> bool    { derived_property::XID_Start(c) }
+#[allow(missing_doc)]
 pub fn is_XID_continue(c: char) -> bool { derived_property::XID_Continue(c) }
 
 ///
@@ -256,6 +260,7 @@ pub fn len_utf8_bytes(c: char) -> uint {
     )
 }
 
+#[allow(missing_doc)]
 pub trait Char {
     fn is_alphabetic(&self) -> bool;
     fn is_XID_start(&self) -> bool;

src/libstd/clone.rs

@@ -24,6 +24,7 @@ trait for them. For other types copies must be made explicitly,
 
 use core::kinds::Const;
 
+/// A common trait for cloning an object.
 pub trait Clone {
     /// Returns a copy of the value. The contents of owned pointers
     /// are copied to maintain uniqueness, while the contents of
@@ -85,6 +86,8 @@ fn clone(&self) -> $t { *self }
 clone_impl!(bool)
 clone_impl!(char)
 
+/// A trait distinct from `Clone` which represents "deep copies" of things like
+/// managed boxes which would otherwise not be copied.
 pub trait DeepClone {
     /// Return a deep copy of the value. Unlike `Clone`, the contents of shared pointer types
     /// *are* copied. Note that this is currently unimplemented for managed boxes, as

src/libstd/cmp.rs

@@ -20,6 +20,8 @@
 
 */
 
+#[allow(missing_doc)];
+
 /**
 * Trait for values that can be compared for equality and inequality.
 *

src/libstd/comm.rs

@@ -12,6 +12,8 @@
 Message passing
 */
 
+#[allow(missing_doc)];
+
 use cast::{transmute, transmute_mut};
 use container::Container;
 use either::{Either, Left, Right};

src/libstd/condition.rs

@@ -10,6 +10,8 @@
 
 /*! Condition handling */
 
+#[allow(missing_doc)];
+
 use local_data::{local_data_pop, local_data_set};
 use local_data;
 use prelude::*;

src/libstd/container.rs

@@ -12,6 +12,8 @@
 
 use option::Option;
 
+/// A trait to represent the abstract idea of a container. The only concrete
+/// knowledge known is the number of elements contained within.
 pub trait Container {
     /// Return the number of elements in the container
     fn len(&const self) -> uint;
@@ -20,16 +22,19 @@ pub trait Container {
     fn is_empty(&const self) -> bool;
 }
 
+/// A trait to represent mutable containers
 pub trait Mutable: Container {
     /// Clear the container, removing all values.
     fn clear(&mut self);
 }
 
+/// A map is a key-value store where values may be looked up by their keys. This
+/// trait provides basic operations to operate on these stores.
 pub trait Map<K, V>: Mutable {
     /// Return true if the map contains a value for the specified key
     fn contains_key(&self, key: &K) -> bool;
 
-    // Visits all keys and values
+    /// Visits all keys and values
     fn each<'a>(&'a self, f: &fn(&K, &'a V) -> bool) -> bool;
 
     /// Visit all keys
@@ -65,6 +70,9 @@ pub trait Map<K, V>: Mutable {
     fn pop(&mut self, k: &K) -> Option<V>;
 }
 
+/// A set is a group of objects which are each distinct from one another. This
+/// trait represents actions which can be performed on sets to manipulate and
+/// iterate over them.
 pub trait Set<T>: Mutable {
     /// Return true if the set contains a value
     fn contains(&self, value: &T) -> bool;

src/libstd/core.rc

@@ -56,12 +56,15 @@ they contained the following prologue:
 #[license = "MIT/ASL2"];
 #[crate_type = "lib"];
 
+// NOTE: remove these two attributes after the next snapshot
+#[no_core]; // for stage0
+#[allow(unrecognized_lint)]; // otherwise stage0 is seriously ugly
 
 // Don't link to std. We are std.
-#[no_core]; // for stage0
 #[no_std];
 
 #[deny(non_camel_case_types)];
+#[deny(missing_doc)];
 
 // Make core testable by not duplicating lang items. See #2912
 #[cfg(test)] extern mod realstd(name = "std");

src/libstd/from_str.rs

@@ -12,6 +12,10 @@
 
 use option::Option;
 
+/// A trait to abstract the idea of creating a new instance of a type from a
+/// string.
 pub trait FromStr {
+    /// Parses a string `s` to return an optional value of this type. If the
+    /// string is ill-formatted, the None is returned.
     fn from_str(s: &str) -> Option<Self>;
 }

src/libstd/hash.rs

@@ -19,6 +19,8 @@
  * CPRNG like rand::rng.
  */
 
+#[allow(missing_doc)];
+
 use container::Container;
 use old_iter::BaseIter;
 use rt::io::Writer;

src/libstd/hashmap.rs

@@ -34,6 +34,14 @@ struct Bucket<K,V> {
     value: V,
 }
 
+/// A hash map implementation which uses linear probing along with the SipHash
+/// hash function for internal state. This means that the order of all hash maps
+/// is randomized by keying each hash map randomly on creation.
+///
+/// It is required that the keys implement the `Eq` and `Hash` traits, although
+/// this can frequently be achieved by just implementing the `Eq` and
+/// `IterBytes` traits as `Hash` is automatically implemented for types that
+/// implement `IterBytes`.
 pub struct HashMap<K,V> {
     priv k0: u64,
     priv k1: u64,
@@ -53,6 +61,7 @@ fn resize_at(capacity: uint) -> uint {
     ((capacity as float) * 3. / 4.) as uint
 }
 
+/// Creates a new hash map with the specified capacity.
 pub fn linear_map_with_capacity<K:Eq + Hash,V>(
     initial_capacity: uint) -> HashMap<K, V> {
     let mut r = rand::task_rng();
@@ -539,6 +548,9 @@ fn eq(&self, other: &HashMap<K, V>) -> bool {
     fn ne(&self, other: &HashMap<K, V>) -> bool { !self.eq(other) }
 }
 
+/// An implementation of a hash set using the underlying representation of a
+/// HashMap where the value is (). As with the `HashMap` type, a `HashSet`
+/// requires that the elements implement the `Eq` and `Hash` traits.
 pub struct HashSet<T> {
     priv map: HashMap<T, ()>
 }

src/libstd/io.rs

@@ -44,6 +44,8 @@
 
 */
 
+#[allow(missing_doc)];
+
 use result::Result;
 
 use container::Container;

src/libstd/iter.rs

@@ -46,6 +46,7 @@
 use num::{One, Zero};
 use ops::{Add, Mul};
 
+#[allow(missing_doc)]
 pub trait Times {
     fn times(&self, it: &fn() -> bool) -> bool;
 }

src/libstd/iterator.rs

@@ -23,6 +23,9 @@
 use num;
 use prelude::*;
 
+/// An interface for dealing with "external iterators". These types of iterators
+/// can be resumed at any time as all state is stored internally as opposed to
+/// being located on the call stack.
 pub trait Iterator<A> {
     /// Advance the iterator and return the next value. Return `None` when the end is reached.
     fn next(&mut self) -> Option<A>;
@@ -33,26 +36,307 @@ pub trait Iterator<A> {
 ///
 /// In the future these will be default methods instead of a utility trait.
 pub trait IteratorUtil<A> {
+    /// Chan this iterator with another, returning a new iterator which will
+    /// finish iterating over the current iterator, and then it will iterate
+    /// over the other specified iterator.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [0];
+    /// let b = [1];
+    /// let mut it = a.iter().chain(b.iter());
+    /// assert_eq!(it.next().get(), &0);
+    /// assert_eq!(it.next().get(), &1);
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn chain<U: Iterator<A>>(self, other: U) -> ChainIterator<Self, U>;
+
+    /// Creates an iterator which iterates over both this and the specified
+    /// iterators simultaneously, yielding the two elements as pairs. When
+    /// either iterator returns None, all further invocations of next() will
+    /// return None.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [0];
+    /// let b = [1];
+    /// let mut it = a.iter().zip(b.iter());
+    /// assert_eq!(it.next().get(), (&0, &1));
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn zip<B, U: Iterator<B>>(self, other: U) -> ZipIterator<Self, U>;
+
     // FIXME: #5898: should be called map
+    /// Creates a new iterator which will apply the specified function to each
+    /// element returned by the first, yielding the mapped element instead. This
+    /// similar to the `vec::map` function.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2];
+    /// let mut it = a.iter().transform(|&x| 2 * x);
+    /// assert_eq!(it.next().get(), 2);
+    /// assert_eq!(it.next().get(), 4);
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn transform<'r, B>(self, f: &'r fn(A) -> B) -> MapIterator<'r, A, B, Self>;
+
+    /// Creates an iterator which applies the predicate to each element returned
+    /// by this iterator. Only elements which have the predicate evaluate to
+    /// `true` will be yielded.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2];
+    /// let mut it = a.iter().filter(|&x| *x > 1);
+    /// assert_eq!(it.next().get(), &2);
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn filter<'r>(self, predicate: &'r fn(&A) -> bool) -> FilterIterator<'r, A, Self>;
+
+    /// Creates an iterator which both filters and maps elements at the same
+    /// If the specified function returns None, the element is skipped.
+    /// Otherwise the option is unwrapped and the new value is yielded.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2];
+    /// let mut it = a.iter().filter_map(|&x| if x > 1 {Some(2 * x)} else {None});
+    /// assert_eq!(it.next().get(), 4);
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn filter_map<'r,  B>(self, f: &'r fn(A) -> Option<B>) -> FilterMapIterator<'r, A, B, Self>;
+
+    /// Creates an iterator which yields a pair of the value returned by this
+    /// iterator plus the current index of iteration.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [100, 200];
+    /// let mut it = a.iter().enumerate();
+    /// assert_eq!(it.next().get(), (0, &100));
+    /// assert_eq!(it.next().get(), (1, &200));
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn enumerate(self) -> EnumerateIterator<Self>;
+
+    /// Creates an iterator which invokes the predicate on elements until it
+    /// returns true. Once the predicate returns true, all further elements are
+    /// yielded.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 2, 1];
+    /// let mut it = a.iter().skip_while(|&a| *a < 3);
+    /// assert_eq!(it.next().get(), &3);
+    /// assert_eq!(it.next().get(), &2);
+    /// assert_eq!(it.next().get(), &1);
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn skip_while<'r>(self, predicate: &'r fn(&A) -> bool) -> SkipWhileIterator<'r, A, Self>;
+
+    /// Creates an iterator which yields elements so long as the predicate
+    /// returns true. After the predicate returns false for the first time, no
+    /// further elements will be yielded.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 2, 1];
+    /// let mut it = a.iter().take_while(|&a| *a < 3);
+    /// assert_eq!(it.next().get(), &1);
+    /// assert_eq!(it.next().get(), &2);
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn take_while<'r>(self, predicate: &'r fn(&A) -> bool) -> TakeWhileIterator<'r, A, Self>;
+
+    /// Creates an iterator which skips the first `n` elements of this iterator,
+    /// and then it yields all further items.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// let mut it = a.iter().skip(3);
+    /// assert_eq!(it.next().get(), &4);
+    /// assert_eq!(it.next().get(), &5);
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn skip(self, n: uint) -> SkipIterator<Self>;
+
+    /// Creates an iterator which yields the first `n` elements of this
+    /// iterator, and then it will always return None.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// let mut it = a.iter().take(3);
+    /// assert_eq!(it.next().get(), &1);
+    /// assert_eq!(it.next().get(), &2);
+    /// assert_eq!(it.next().get(), &3);
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn take(self, n: uint) -> TakeIterator<Self>;
+
+    /// Creates a new iterator which behaves in a similar fashion to foldl.
+    /// There is a state which is passed between each iteration and can be
+    /// mutated as necessary. The yielded values from the closure are yielded
+    /// from the ScanIterator instance when not None.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// let mut it = a.iter().scan(1, |fac, &x| {
+    ///   *fac = *fac * x;
+    ///   Some(*fac)
+    /// });
+    /// assert_eq!(it.next().get(), 1);
+    /// assert_eq!(it.next().get(), 2);
+    /// assert_eq!(it.next().get(), 6);
+    /// assert_eq!(it.next().get(), 24);
+    /// assert_eq!(it.next().get(), 120);
+    /// assert!(it.next().is_none());
+    /// ~~~
     fn scan<'r, St, B>(self, initial_state: St, f: &'r fn(&mut St, A) -> Option<B>)
         -> ScanIterator<'r, A, B, Self, St>;
+
+    /// An adaptation of an external iterator to the for-loop protocol of rust.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// for Counter::new(0, 10).advance |i| {
+    ///     io::println(fmt!("%d", i));
+    /// }
+    /// ~~~
     fn advance(&mut self, f: &fn(A) -> bool) -> bool;
+
+    /// Loops through the entire iterator, accumulating all of the elements into
+    /// a vector.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// let b = a.iter().transform(|&x| x).to_vec();
+    /// assert!(a == b);
+    /// ~~~
     fn to_vec(&mut self) -> ~[A];
+
+    /// Loops through `n` iterations, returning the `n`th element of the
+    /// iterator.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// let mut it = a.iter();
+    /// assert!(it.nth(2).get() == &3);
+    /// assert!(it.nth(2) == None);
+    /// ~~~
     fn nth(&mut self, n: uint) -> Option<A>;
+
+    /// Loops through the entire iterator, returning the last element of the
+    /// iterator.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// assert!(a.iter().last().get() == &5);
+    /// ~~~
     fn last(&mut self) -> Option<A>;
+
+    /// Performs a fold operation over the entire iterator, returning the
+    /// eventual state at the end of the iteration.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// assert!(a.iter().fold(0, |a, &b| a + b) == 15);
+    /// ~~~
     fn fold<B>(&mut self, start: B, f: &fn(B, A) -> B) -> B;
+
+    /// Counts the number of elements in this iterator.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// let mut it = a.iter();
+    /// assert!(it.count() == 5);
+    /// assert!(it.count() == 0);
+    /// ~~~
     fn count(&mut self) -> uint;
+
+    /// Tests whether the predicate holds true for all elements in the iterator.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// assert!(a.iter().all(|&x| *x > 0));
+    /// assert!(!a.iter().all(|&x| *x > 2));
+    /// ~~~
     fn all(&mut self, f: &fn(&A) -> bool) -> bool;
+
+    /// Tests whether any element of an iterator satisfies the specified
+    /// predicate.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// let mut it = a.iter();
+    /// assert!(it.any(|&x| *x == 3));
+    /// assert!(!it.any(|&x| *x == 3));
+    /// ~~~
     fn any(&mut self, f: &fn(&A) -> bool) -> bool;
 }
 
@@ -186,7 +470,19 @@ fn any(&mut self, f: &fn(&A) -> bool) -> bool {
     }
 }
 
+/// A trait for iterators over elements which can be added together
 pub trait AdditiveIterator<A> {
+    /// Iterates over the entire iterator, summing up all the elements
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// let mut it = a.iter().transform(|&x| x);
+    /// assert!(it.sum() == 15);
+    /// ~~~
     fn sum(&mut self) -> A;
 }
 
@@ -195,7 +491,23 @@ impl<A: Add<A, A> + Zero, T: Iterator<A>> AdditiveIterator<A> for T {
     fn sum(&mut self) -> A { self.fold(Zero::zero::<A>(), |s, x| s + x) }
 }
 
+/// A trait for iterators over elements whose elements can be multiplied
+/// together.
 pub trait MultiplicativeIterator<A> {
+    /// Iterates over the entire iterator, multiplying all the elements
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// fn factorial(n: uint) -> uint {
+    ///     Counter::new(1u, 1).take_while(|&i| i <= n).product()
+    /// }
+    /// assert!(factorial(0) == 1);
+    /// assert!(factorial(1) == 1);
+    /// assert!(factorial(5) == 120);
+    /// ~~~
     fn product(&mut self) -> A;
 }
 
@@ -204,8 +516,31 @@ impl<A: Mul<A, A> + One, T: Iterator<A>> MultiplicativeIterator<A> for T {
     fn product(&mut self) -> A { self.fold(One::one::<A>(), |p, x| p * x) }
 }
 
+/// A trait for iterators over elements which can be compared to one another.
+/// The type of each element must ascribe to the `Ord` trait.
 pub trait OrdIterator<A> {
+    /// Consumes the entire iterator to return the maximum element.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// assert!(a.iter().max().get() == &5);
+    /// ~~~
     fn max(&mut self) -> Option<A>;
+
+    /// Consumes the entire iterator to return the minimum element.
+    ///
+    /// # Example
+    ///
+    /// ~~~ {.rust}
+    /// use std::iterator::*;
+    ///
+    /// let a = [1, 2, 3, 4, 5];
+    /// assert!(a.iter().min().get() == &1);
+    /// ~~~
     fn min(&mut self) -> Option<A>;
 }
 
@@ -231,6 +566,7 @@ fn min(&mut self) -> Option<A> {
     }
 }
 
+/// An iterator which strings two iterators together
 pub struct ChainIterator<T, U> {
     priv a: T,
     priv b: U,
@@ -253,6 +589,7 @@ fn next(&mut self) -> Option<A> {
     }
 }
 
+/// An iterator which iterates two other iterators simultaneously
 pub struct ZipIterator<T, U> {
     priv a: T,
     priv b: U
@@ -268,6 +605,7 @@ fn next(&mut self) -> Option<(A, B)> {
     }
 }
 
+/// An iterator which maps the values of `iter` with `f`
 pub struct MapIterator<'self, A, B, T> {
     priv iter: T,
     priv f: &'self fn(A) -> B
@@ -283,6 +621,7 @@ fn next(&mut self) -> Option<B> {
     }
 }
 
+/// An iterator which filters the elements of `iter` with `predicate`
 pub struct FilterIterator<'self, A, T> {
     priv iter: T,
     priv predicate: &'self fn(&A) -> bool
@@ -302,6 +641,7 @@ fn next(&mut self) -> Option<A> {
     }
 }
 
+/// An iterator which uses `f` to both filter and map elements from `iter`
 pub struct FilterMapIterator<'self, A, B, T> {
     priv iter: T,
     priv f: &'self fn(A) -> Option<B>
@@ -320,6 +660,7 @@ fn next(&mut self) -> Option<B> {
     }
 }
 
+/// An iterator which yields the current count and the element during iteration
 pub struct EnumerateIterator<T> {
     priv iter: T,
     priv count: uint
@@ -339,6 +680,7 @@ fn next(&mut self) -> Option<(uint, A)> {
     }
 }
 
+/// An iterator which rejects elements while `predicate` is true
 pub struct SkipWhileIterator<'self, A, T> {
     priv iter: T,
     priv flag: bool,
@@ -370,6 +712,7 @@ fn next(&mut self) -> Option<A> {
     }
 }
 
+/// An iterator which only accepts elements while `predicate` is true
 pub struct TakeWhileIterator<'self, A, T> {
     priv iter: T,
     priv flag: bool,
@@ -397,6 +740,7 @@ fn next(&mut self) -> Option<A> {
     }
 }
 
+/// An iterator which skips over `n` elements of `iter`
 pub struct SkipIterator<T> {
     priv iter: T,
     priv n: uint
@@ -428,6 +772,7 @@ fn next(&mut self) -> Option<A> {
     }
 }
 
+/// An iterator which only iterates over the first `n` iterations of `iter`.
 pub struct TakeIterator<T> {
     priv iter: T,
     priv n: uint
@@ -446,9 +791,12 @@ fn next(&mut self) -> Option<A> {
     }
 }
 
+/// An iterator to maintain state while iterating another iterator
 pub struct ScanIterator<'self, A, B, T, St> {
     priv iter: T,
     priv f: &'self fn(&mut St, A) -> Option<B>,
+
+    /// The current internal state to be passed to the closure next.
     state: St
 }
 
@@ -459,14 +807,18 @@ fn next(&mut self) -> Option<B> {
     }
 }
 
+/// An iterator which just modifies the contained state throughout iteration.
 pub struct UnfoldrIterator<'self, A, St> {
     priv f: &'self fn(&mut St) -> Option<A>,
+    /// Internal state that will be yielded on the next iteration
     state: St
 }
 
-pub impl<'self, A, St> UnfoldrIterator<'self, A, St> {
+impl<'self, A, St> UnfoldrIterator<'self, A, St> {
+    /// Creates a new iterator with the specified closure as the "iterator
+    /// function" and an initial state to eventually pass to the iterator
     #[inline]
-    fn new(f: &'self fn(&mut St) -> Option<A>, initial_state: St)
+    pub fn new(f: &'self fn(&mut St) -> Option<A>, initial_state: St)
         -> UnfoldrIterator<'self, A, St> {
         UnfoldrIterator {
             f: f,
@@ -482,15 +834,19 @@ fn next(&mut self) -> Option<A> {
     }
 }
 
-/// An infinite iterator starting at `start` and advancing by `step` with each iteration
+/// An infinite iterator starting at `start` and advancing by `step` with each
+/// iteration
 pub struct Counter<A> {
+    /// The current state the counter is at (next value to be yielded)
     state: A,
+    /// The amount that this iterator is stepping by
     step: A
 }
 
-pub impl<A> Counter<A> {
+impl<A> Counter<A> {
+    /// Creates a new counter with the specified start/step
     #[inline(always)]
-    fn new(start: A, step: A) -> Counter<A> {
+    pub fn new(start: A, step: A) -> Counter<A> {
         Counter{state: start, step: step}
     }
 }

src/libstd/kinds.rs

@@ -37,6 +37,8 @@
 
 */
 
+#[allow(missing_doc)];
+
 #[lang="copy"]
 pub trait Copy {
     // Empty.

src/libstd/libc.rs

@@ -64,6 +64,7 @@
 */
 
 #[allow(non_camel_case_types)];
+#[allow(missing_doc)];
 
 // Initial glob-exports mean that all the contents of all the modules
 // wind up exported, if you're interested in writing platform-specific code.

src/libstd/logging.rs

@@ -36,6 +36,7 @@ pub fn console_off() {
 
 #[cfg(not(test))]
 #[lang="log_type"]
+#[allow(missing_doc)]
 pub fn log_type<T>(level: u32, object: &T) {
     use cast;
     use container::Container;

src/libstd/managed.rs

@@ -21,6 +21,7 @@ pub mod raw {
     pub static RC_MANAGED_UNIQUE : uint = (-2) as uint;
     pub static RC_IMMORTAL : uint = 0x77777777;
 
+    #[allow(missing_doc)]
     pub struct BoxHeaderRepr {
         ref_count: uint,
         type_desc: *TyDesc,
@@ -28,6 +29,7 @@ pub struct BoxHeaderRepr {
         next: *BoxRepr,
     }
 
+    #[allow(missing_doc)]
     pub struct BoxRepr {
         header: BoxHeaderRepr,
         data: u8

src/libstd/num/cmath.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#[allow(missing_doc)];
+
 // function names are almost identical to C's libmath, a few have been
 // renamed, grep for "rename:"
 

src/libstd/num/f32.rs

@@ -9,6 +9,7 @@
 // except according to those terms.
 
 //! Operations and constants for `f32`
+#[allow(missing_doc)];
 
 use libc::c_int;
 use num::{Zero, One, strconv};

src/libstd/num/f64.rs

@@ -10,6 +10,8 @@
 
 //! Operations and constants for `f64`
 
+#[allow(missing_doc)];
+
 use libc::c_int;
 use num::{Zero, One, strconv};
 use num::{FPCategory, FPNaN, FPInfinite , FPZero, FPSubnormal, FPNormal};

src/libstd/num/float.rs

@@ -20,6 +20,8 @@
 
 // PORT this must match in width according to architecture
 
+#[allow(missing_doc)];
+
 use f64;
 use libc::c_int;
 use num::{Zero, One, strconv};

src/libstd/num/int_macros.rs

@@ -26,12 +26,17 @@
 pub static min_value: $T = (-1 as $T) << (bits - 1);
 pub static max_value: $T = min_value - 1 as $T;
 
+/// Calculates the sum of two numbers
 #[inline(always)]
 pub fn add(x: $T, y: $T) -> $T { x + y }
+/// Subtracts the second number from the first
 #[inline(always)]
 pub fn sub(x: $T, y: $T) -> $T { x - y }
+/// Multiplies two numbers together
 #[inline(always)]
 pub fn mul(x: $T, y: $T) -> $T { x * y }
+/// Divides the first argument by the second argument (using integer division)
+/// Divides the first argument by the second argument (using integer division)
 #[inline(always)]
 pub fn div(x: $T, y: $T) -> $T { x / y }
 
@@ -58,16 +63,22 @@ pub fn div(x: $T, y: $T) -> $T { x / y }
 #[inline(always)]
 pub fn rem(x: $T, y: $T) -> $T { x % y }
 
+/// Returns true iff `x < y`
 #[inline(always)]
 pub fn lt(x: $T, y: $T) -> bool { x < y }
+/// Returns true iff `x <= y`
 #[inline(always)]
 pub fn le(x: $T, y: $T) -> bool { x <= y }
+/// Returns true iff `x == y`
 #[inline(always)]
 pub fn eq(x: $T, y: $T) -> bool { x == y }
+/// Returns true iff `x != y`
 #[inline(always)]
 pub fn ne(x: $T, y: $T) -> bool { x != y }
+/// Returns true iff `x >= y`
 #[inline(always)]
 pub fn ge(x: $T, y: $T) -> bool { x >= y }
+/// Returns true iff `x > y`
 #[inline(always)]
 pub fn gt(x: $T, y: $T) -> bool { x > y }
 

src/libstd/num/num.rs

@@ -9,6 +9,9 @@
 // except according to those terms.
 
 //! An interface for numeric types
+
+#[allow(missing_doc)];
+
 use cmp::{Eq, ApproxEq, Ord};
 use ops::{Add, Sub, Mul, Div, Rem, Neg};
 use ops::{Not, BitAnd, BitOr, BitXor, Shl, Shr};

src/libstd/num/strconv.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#[allow(missing_doc)];
+
 use container::Container;
 use core::cmp::{Ord, Eq};
 use ops::{Add, Sub, Mul, Div, Rem, Neg};

src/libstd/num/uint_macros.rs

@@ -27,27 +27,39 @@
 pub static min_value: $T = 0 as $T;
 pub static max_value: $T = 0 as $T - 1 as $T;
 
+/// Calculates the sum of two numbers
 #[inline(always)]
 pub fn add(x: $T, y: $T) -> $T { x + y }
+/// Subtracts the second number from the first
 #[inline(always)]
 pub fn sub(x: $T, y: $T) -> $T { x - y }
+/// Multiplies two numbers together
 #[inline(always)]
 pub fn mul(x: $T, y: $T) -> $T { x * y }
+/// Divides the first argument by the second argument (using integer division)
 #[inline(always)]
 pub fn div(x: $T, y: $T) -> $T { x / y }
+/// Calculates the integer remainder when x is divided by y (equivalent to the
+/// '%' operator)
 #[inline(always)]
 pub fn rem(x: $T, y: $T) -> $T { x % y }
 
+/// Returns true iff `x < y`
 #[inline(always)]
 pub fn lt(x: $T, y: $T) -> bool { x < y }
+/// Returns true iff `x <= y`
 #[inline(always)]
 pub fn le(x: $T, y: $T) -> bool { x <= y }
+/// Returns true iff `x == y`
 #[inline(always)]
 pub fn eq(x: $T, y: $T) -> bool { x == y }
+/// Returns true iff `x != y`
 #[inline(always)]
 pub fn ne(x: $T, y: $T) -> bool { x != y }
+/// Returns true iff `x >= y`
 #[inline(always)]
 pub fn ge(x: $T, y: $T) -> bool { x >= y }
+/// Returns true iff `x > y`
 #[inline(always)]
 pub fn gt(x: $T, y: $T) -> bool { x > y }
 

src/libstd/old_iter.rs

@@ -14,6 +14,8 @@
 
 */
 
+#[allow(missing_doc)];
+
 use cmp::{Eq, Ord};
 use kinds::Copy;
 use option::{None, Option, Some};

src/libstd/ops.rs

@@ -10,6 +10,8 @@
 
 //! Traits for the built-in operators
 
+#[allow(missing_doc)];
+
 #[lang="drop"]
 pub trait Drop {
     fn finalize(&self);  // FIXME(#4332): Rename to "drop"? --pcwalton

src/libstd/os.rs

@@ -26,6 +26,8 @@
  * to write OS-ignorant code by default.
  */
 
+#[allow(missing_doc)];
+
 use cast;
 use io;
 use libc;
@@ -45,6 +47,7 @@
 pub use libc::fclose;
 pub use os::consts::*;
 
+/// Delegates to the libc close() function, returning the same return value.
 pub fn close(fd: c_int) -> c_int {
     unsafe {
         libc::close(fd)
@@ -171,6 +174,8 @@ fn with_env_lock<T>(f: &fn() -> T) -> T {
     }
 }
 
+/// Returns a vector of (variable, value) pairs for all the environment
+/// variables of the current process.
 pub fn env() -> ~[(~str,~str)] {
     unsafe {
         #[cfg(windows)]
@@ -236,6 +241,8 @@ fn env_convert(input: ~[~str]) -> ~[(~str, ~str)] {
 }
 
 #[cfg(unix)]
+/// Fetches the environment variable `n` from the current process, returning
+/// None if the variable isn't set.
 pub fn getenv(n: &str) -> Option<~str> {
     unsafe {
         do with_env_lock {
@@ -251,6 +258,8 @@ pub fn getenv(n: &str) -> Option<~str> {
 }
 
 #[cfg(windows)]
+/// Fetches the environment variable `n` from the current process, returning
+/// None if the variable isn't set.
 pub fn getenv(n: &str) -> Option<~str> {
     unsafe {
         do with_env_lock {
@@ -266,6 +275,8 @@ pub fn getenv(n: &str) -> Option<~str> {
 
 
 #[cfg(unix)]
+/// Sets the environment variable `n` to the value `v` for the currently running
+/// process
 pub fn setenv(n: &str, v: &str) {
     unsafe {
         do with_env_lock {
@@ -280,6 +291,8 @@ pub fn setenv(n: &str, v: &str) {
 
 
 #[cfg(windows)]
+/// Sets the environment variable `n` to the value `v` for the currently running
+/// process
 pub fn setenv(n: &str, v: &str) {
     unsafe {
         do with_env_lock {
@@ -422,13 +435,14 @@ fn dup2(src: c_int, dst: c_int) -> c_int {
     }
 }
 
-
+/// Returns the proper dll filename for the given basename of a file.
 pub fn dll_filename(base: &str) -> ~str {
     return str::to_owned(DLL_PREFIX) + str::to_owned(base) +
            str::to_owned(DLL_SUFFIX)
 }
 
-
+/// Optionally returns the filesystem path to the current executable which is
+/// running. If any failure occurs, None is returned.
 pub fn self_exe_path() -> Option<Path> {
 
     #[cfg(target_os = "freebsd")]
@@ -828,6 +842,8 @@ fn rmdir(p: &Path) -> bool {
     }
 }
 
+/// Changes the current working directory to the specified path, returning
+/// whether the change was completed successfully or not.
 pub fn change_dir(p: &Path) -> bool {
     return chdir(p);
 
@@ -981,6 +997,7 @@ fn unlink(p: &Path) -> bool {
 }
 
 #[cfg(unix)]
+/// Returns the platform-specific value of errno
 pub fn errno() -> int {
     #[cfg(target_os = "macos")]
     #[cfg(target_os = "freebsd")]
@@ -1012,6 +1029,7 @@ fn errno_location() -> *c_int {
 }
 
 #[cfg(windows)]
+/// Returns the platform-specific value of errno
 pub fn errno() -> uint {
     use libc::types::os::arch::extra::DWORD;
 
@@ -1211,6 +1229,11 @@ struct OverriddenArgs {
 
 fn overridden_arg_key(_v: @OverriddenArgs) {}
 
+/// Returns the arguments which this program was started with (normally passed
+/// via the command line).
+///
+/// The return value of the function can be changed by invoking the
+/// `os::set_args` function.
 pub fn args() -> ~[~str] {
     unsafe {
         match local_data::local_data_get(overridden_arg_key) {
@@ -1220,6 +1243,9 @@ pub fn args() -> ~[~str] {
     }
 }
 
+/// For the current task, overrides the task-local cache of the arguments this
+/// program had when it started. These new arguments are only available to the
+/// current task via the `os::args` method.
 pub fn set_args(new_args: ~[~str]) {
     unsafe {
         let overridden_args = @OverriddenArgs { val: copy new_args };

src/libstd/path.rs

@@ -14,6 +14,8 @@
 
 */
 
+#[allow(missing_doc)];
+
 use container::Container;
 use cmp::Eq;
 use libc;

src/libstd/pipes.rs

@@ -82,6 +82,8 @@
 
 */
 
+#[allow(missing_doc)];
+
 use container::Container;
 use cast::{forget, transmute, transmute_copy};
 use either::{Either, Left, Right};

src/libstd/ptr.rs

@@ -120,6 +120,12 @@ pub unsafe fn copy_memory<T>(dst: *mut T, src: *const T, count: uint) {
     memmove64(dst as *mut u8, src as *u8, n as u64);
 }
 
+/**
+ * Copies data from one location to another
+ *
+ * Copies `count` elements (not bytes) from `src` to `dst`. The source
+ * and destination may overlap.
+ */
 #[inline(always)]
 #[cfg(target_word_size = "64", not(stage0))]
 pub unsafe fn copy_memory<T>(dst: *mut T, src: *const T, count: uint) {
@@ -135,6 +141,13 @@ pub unsafe fn copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: u
     memmove32(dst as *mut u8, src as *u8, n as u32);
 }
 
+/**
+ * Copies data from one location to another. This uses memcpy instead of memmove
+ * to take advantage of the knowledge that the memory does not overlap.
+ *
+ * Copies `count` elements (not bytes) from `src` to `dst`. The source
+ * and destination may overlap.
+ */
 #[inline(always)]
 #[cfg(target_word_size = "32", not(stage0))]
 pub unsafe fn copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: uint) {
@@ -150,6 +163,13 @@ pub unsafe fn copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: u
     memmove64(dst as *mut u8, src as *u8, n as u64);
 }
 
+/**
+ * Copies data from one location to another. This uses memcpy instead of memmove
+ * to take advantage of the knowledge that the memory does not overlap.
+ *
+ * Copies `count` elements (not bytes) from `src` to `dst`. The source
+ * and destination may overlap.
+ */
 #[inline(always)]
 #[cfg(target_word_size = "64", not(stage0))]
 pub unsafe fn copy_nonoverlapping_memory<T>(dst: *mut T, src: *const T, count: uint) {
@@ -164,6 +184,10 @@ pub unsafe fn set_memory<T>(dst: *mut T, c: int, count: uint) {
     libc_::memset(dst as *mut c_void, c as libc::c_int, n as size_t);
 }
 
+/**
+ * Invokes memset on the specified pointer, setting `count` bytes of memory
+ * starting at `dst` to `c`.
+ */
 #[inline(always)]
 #[cfg(target_word_size = "32", not(stage0))]
 pub unsafe fn set_memory<T>(dst: *mut T, c: u8, count: uint) {
@@ -171,6 +195,10 @@ pub unsafe fn set_memory<T>(dst: *mut T, c: u8, count: uint) {
     memset32(dst, c, count as u32);
 }
 
+/**
+ * Invokes memset on the specified pointer, setting `count` bytes of memory
+ * starting at `dst` to `c`.
+ */
 #[inline(always)]
 #[cfg(target_word_size = "64", not(stage0))]
 pub unsafe fn set_memory<T>(dst: *mut T, c: u8, count: uint) {
@@ -268,6 +296,7 @@ pub unsafe fn array_each<T>(arr: **T, cb: &fn(*T)) {
     array_each_with_len(arr, len, cb);
 }
 
+#[allow(missing_doc)]
 pub trait Ptr<T> {
     fn is_null(&const self) -> bool;
     fn is_not_null(&const self) -> bool;

src/libstd/rand.rs

@@ -58,6 +58,8 @@ fn main () {
 
 /// A type that can be randomly generated using an Rng
 pub trait Rand {
+    /// Generates a random instance of this type using the specified source of
+    /// randomness
     fn rand<R: Rng>(rng: &mut R) -> Self;
 }
 
@@ -256,10 +258,13 @@ pub trait Rng {
 
 /// A value with a particular weight compared to other values
 pub struct Weighted<T> {
+    /// The numerical weight of this item
     weight: uint,
+    /// The actual item which is being weighted
     item: T,
 }
 
+/// Helper functions attached to the Rng type
 pub trait RngUtil {
     /// Return a random value of a Rand type
     fn gen<T:Rand>(&mut self) -> T;

src/libstd/reflect.rs

@@ -14,6 +14,8 @@
 
 */
 
+#[allow(missing_doc)];
+
 use intrinsic::{TyDesc, TyVisitor};
 use intrinsic::Opaque;
 use libc::c_void;

src/libstd/repr.rs

@@ -14,6 +14,8 @@
 
 */
 
+#[allow(missing_doc)];
+
 use cast::transmute;
 use char;
 use intrinsic;

src/libstd/result.rs

@@ -312,6 +312,7 @@ pub fn map_vec<T,U:Copy,V:Copy>(
 }
 
 #[inline(always)]
+#[allow(missing_doc)]
 pub fn map_opt<T,U:Copy,V:Copy>(
     o_t: &Option<T>, op: &fn(&T) -> Result<V,U>) -> Result<Option<V>,U> {
 

src/libstd/stackwalk.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#[allow(missing_doc)];
+
 use cast::transmute;
 use unstable::intrinsics;
 

src/libstd/str.rs

@@ -72,6 +72,16 @@ pub fn from_bytes_with_null<'a>(vv: &'a [u8]) -> &'a str {
     return unsafe { raw::from_bytes_with_null(vv) };
 }
 
+/**
+ * Converts a vector to a string slice without performing any allocations.
+ *
+ * Once the slice has been validated as utf-8, it is transmuted in-place and
+ * returned as a '&str' instead of a '&[u8]'
+ *
+ * # Failure
+ *
+ * Fails if invalid UTF-8
+ */
 pub fn from_bytes_slice<'a>(vector: &'a [u8]) -> &'a str {
     unsafe {
         assert!(is_utf8(vector));
@@ -741,6 +751,18 @@ pub fn each_split_str<'a,'b>(s: &'a str,
     return true;
 }
 
+/**
+ * Splits the string `s` based on `sep`, yielding all splits to the iterator
+ * function provide
+ *
+ * # Example
+ *
+ * ~~~ {.rust}
+ * let mut v = ~[];
+ * for each_split_str(".XXX.YYY.", ".") |subs| { v.push(subs); }
+ * assert!(v == ["XXX", "YYY"]);
+ * ~~~
+ */
 pub fn each_split_str_nonempty<'a,'b>(s: &'a str,
                                       sep: &'b str,
                                       it: &fn(&'a str) -> bool) -> bool {
@@ -823,7 +845,7 @@ pub fn each_word<'a>(s: &'a str, it: &fn(&'a str) -> bool) -> bool {
  *  Fails during iteration if the string contains a non-whitespace
  *  sequence longer than the limit.
  */
-pub fn _each_split_within<'a>(ss: &'a str,
+pub fn each_split_within<'a>(ss: &'a str,
                               lim: uint,
                               it: &fn(&'a str) -> bool) -> bool {
     // Just for fun, let's write this as an state machine:
@@ -886,12 +908,6 @@ enum LengthLimit {
     return cont;
 }
 
-pub fn each_split_within<'a>(ss: &'a str,
-                             lim: uint,
-                             it: &fn(&'a str) -> bool) -> bool {
-    _each_split_within(ss, lim, it)
-}
-
 /**
  * Replace all occurrences of one string with another
  *
@@ -1236,7 +1252,7 @@ pub fn each_char_reverse(s: &str, it: &fn(char) -> bool) -> bool {
     each_chari_reverse(s, |_, c| it(c))
 }
 
-// Iterates over the chars in a string in reverse, with indices
+/// Iterates over the chars in a string in reverse, with indices
 #[inline(always)]
 pub fn each_chari_reverse(s: &str, it: &fn(uint, char) -> bool) -> bool {
     let mut pos = s.len();
@@ -1814,6 +1830,12 @@ pub fn to_utf16(s: &str) -> ~[u16] {
     u
 }
 
+/// Iterates over the utf-16 characters in the specified slice, yielding each
+/// decoded unicode character to the function provided.
+///
+/// # Failures
+///
+/// * Fails on invalid utf-16 data
 pub fn utf16_chars(v: &[u16], f: &fn(char)) {
     let len = v.len();
     let mut i = 0u;
@@ -1838,6 +1860,9 @@ pub fn utf16_chars(v: &[u16], f: &fn(char)) {
     }
 }
 
+/**
+ * Allocates a new string from the utf-16 slice provided
+ */
 pub fn from_utf16(v: &[u16]) -> ~str {
     let mut buf = ~"";
     reserve(&mut buf, v.len());
@@ -1845,6 +1870,10 @@ pub fn from_utf16(v: &[u16]) -> ~str {
     buf
 }
 
+/**
+ * Allocates a new string with the specified capacity. The string returned is
+ * the empty string, but has capacity for much more.
+ */
 pub fn with_capacity(capacity: uint) -> ~str {
     let mut buf = ~"";
     reserve(&mut buf, capacity);
@@ -1990,6 +2019,7 @@ pub fn char_at(s: &str, i: uint) -> char {
     return char_range_at(s, i).ch;
 }
 
+#[allow(missing_doc)]
 pub struct CharRange {
     ch: char,
     next: uint
@@ -2481,6 +2511,7 @@ fn add(&self, rhs: & &'self str) -> ~str {
 #[cfg(test)]
 pub mod traits {}
 
+#[allow(missing_doc)]
 pub trait StrSlice<'self> {
     fn all(&self, it: &fn(char) -> bool) -> bool;
     fn any(&self, it: &fn(char) -> bool) -> bool;
@@ -2715,6 +2746,7 @@ fn char_at_reverse(&self, i: uint) -> char {
     fn to_bytes(&self) -> ~[u8] { to_bytes(*self) }
 }
 
+#[allow(missing_doc)]
 pub trait OwnedStr {
     fn push_str(&mut self, v: &str);
     fn push_char(&mut self, c: char);
@@ -2738,6 +2770,8 @@ fn clone(&self) -> ~str {
     }
 }
 
+/// External iterator for a string's characters. Use with the `std::iterator`
+/// module.
 pub struct StrCharIterator<'self> {
     priv index: uint,
     priv string: &'self str,

src/libstd/sys.rs

@@ -10,6 +10,8 @@
 
 //! Misc low level stuff
 
+#[allow(missing_doc)];
+
 use option::{Some, None};
 use cast;
 use cmp::{Eq, Ord};

src/libstd/task/local_data_priv.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#[allow(missing_doc)];
+
 use cast;
 use cmp::Eq;
 use libc;

src/libstd/task/mod.rs

@@ -33,6 +33,8 @@
  * ~~~
  */
 
+#[allow(missing_doc)];
+
 use prelude::*;
 
 use cast;

src/libstd/to_bytes.rs

@@ -303,7 +303,11 @@ fn iter_bytes(&self, lsb0: bool, f: Cb) -> bool {
     }
 }
 
+/// A trait for converting a value to a list of bytes.
 pub trait ToBytes {
+    /// Converts the current value to a list of bytes. This is equivalent to
+    /// invoking iter_bytes on a type and collecting all yielded values in an
+    /// array
     fn to_bytes(&self, lsb0: bool) -> ~[u8];
 }
 

src/libstd/to_str.rs

@@ -22,13 +22,15 @@
 use cmp::Eq;
 use old_iter::BaseIter;
 
+/// A generic trait for converting a value to a string
 pub trait ToStr {
+    /// Converts the value of `self` to an owned string
     fn to_str(&self) -> ~str;
 }
 
 /// Trait for converting a type to a string, consuming it in the process.
 pub trait ToStrConsume {
-    // Cosume and convert to a string.
+    /// Cosume and convert to a string.
     fn to_str_consume(self) -> ~str;
 }
 

src/libstd/trie.rs

@@ -28,6 +28,7 @@ enum Child<T> {
     Nothing
 }
 
+#[allow(missing_doc)]
 pub struct TrieMap<T> {
     priv root: TrieNode<T>,
     priv length: uint
@@ -172,6 +173,7 @@ fn each_value_reverse(&self, f: &fn(&T) -> bool) -> bool {
     }
 }
 
+#[allow(missing_doc)]
 pub struct TrieSet {
     priv map: TrieMap<()>
 }

src/libstd/tuple.rs

@@ -10,14 +10,20 @@
 
 //! Operations on tuples
 
+#[allow(missing_doc)];
+
 use kinds::Copy;
 use vec;
 
 pub use self::inner::*;
 
+/// Method extensions to pairs where both types satisfy the `Copy` bound
 pub trait CopyableTuple<T, U> {
+    /// Return the first element of self
     fn first(&self) -> T;
+    /// Return the second element of self
     fn second(&self) -> U;
+    /// Return the results of swapping the two elements of self
     fn swap(&self) -> (U, T);
 }
 
@@ -47,8 +53,12 @@ fn swap(&self) -> (U, T) {
     }
 }
 
+/// Method extensions for pairs where the types don't necessarily satisfy the
+/// `Copy` bound
 pub trait ImmutableTuple<T, U> {
+    /// Return a reference to the first element of self
     fn first_ref<'a>(&'a self) -> &'a T;
+    /// Return a reference to the second element of self
     fn second_ref<'a>(&'a self) -> &'a U;
 }
 

src/libstd/unicode.rs

@@ -10,6 +10,8 @@
 
 // The following code was generated by "src/etc/unicode.py"
 
+#[allow(missing_doc)];
+
 pub mod general_category {
 
     fn bsearch_range_table(c: char, r: &'static [(char,char)]) -> bool {

src/libstd/util.rs

@@ -107,13 +107,14 @@ pub unsafe fn replace_ptr<T>(dest: *mut T, mut src: T) -> T {
 
 /// A non-copyable dummy type.
 pub struct NonCopyable {
-    i: (),
+    priv i: (),
 }
 
 impl Drop for NonCopyable {
     fn finalize(&self) { }
 }
 
+/// Creates a dummy non-copyable structure and returns it for use.
 pub fn NonCopyable() -> NonCopyable { NonCopyable { i: () } }
 
 

src/libstd/vec.rs

@@ -129,6 +129,7 @@ pub fn len<T>(v: &const [T]) -> uint {
 }
 
 // A botch to tide us over until core and std are fully demuted.
+#[allow(missing_doc)]
 pub fn uniq_len<T>(v: &const ~[T]) -> uint {
     unsafe {
         let v: &~[T] = transmute(v);
@@ -543,6 +544,22 @@ pub fn remove<T>(v: &mut ~[T], i: uint) -> T {
     v.pop()
 }
 
+/// Consumes all elements, in a vector, moving them out into the / closure
+/// provided. The vector is traversed from the start to the end.
+///
+/// This method does not impose any requirements on the type of the vector being
+/// consumed, but it prevents any usage of the vector after this function is
+/// called.
+///
+/// # Examples
+///
+/// ~~~ {.rust}
+/// let v = ~[~"a", ~"b"];
+/// do vec::consume(v) |i, s| {
+///   // s has type ~str, not &~str
+///   io::println(s + fmt!(" %d", i));
+/// }
+/// ~~~
 pub fn consume<T>(mut v: ~[T], f: &fn(uint, v: T)) {
     unsafe {
         do as_mut_buf(v) |p, ln| {
@@ -561,6 +578,12 @@ pub fn consume<T>(mut v: ~[T], f: &fn(uint, v: T)) {
     }
 }
 
+/// Consumes all elements, in a vector, moving them out into the / closure
+/// provided. The vectors is traversed in reverse order (from end to start).
+///
+/// This method does not impose any requirements on the type of the vector being
+/// consumed, but it prevents any usage of the vector after this function is
+/// called.
 pub fn consume_reverse<T>(mut v: ~[T], f: &fn(uint, v: T)) {
     unsafe {
         do as_mut_buf(v) |p, ln| {
@@ -646,6 +669,16 @@ fn push_slow<T>(v: &mut ~[T], initval: T) {
     unsafe { push_fast(v, initval) }
 }
 
+/// Iterates over the slice `rhs`, copies each element, and then appends it to
+/// the vector provided `v`. The `rhs` vector is traversed in-order.
+///
+/// # Example
+///
+/// ~~~ {.rust}
+/// let mut a = ~[1];
+/// vec::push_all(&mut a, [2, 3, 4]);
+/// assert!(a == ~[1, 2, 3, 4]);
+/// ~~~
 #[inline(always)]
 pub fn push_all<T:Copy>(v: &mut ~[T], rhs: &const [T]) {
     let new_len = v.len() + rhs.len();
@@ -656,6 +689,17 @@ pub fn push_all<T:Copy>(v: &mut ~[T], rhs: &const [T]) {
     }
 }
 
+/// Takes ownership of the vector `rhs`, moving all elements into the specified
+/// vector `v`. This does not copy any elements, and it is illegal to use the
+/// `rhs` vector after calling this method (because it is moved here).
+///
+/// # Example
+///
+/// ~~~ {.rust}
+/// let mut a = ~[~1];
+/// vec::push_all_move(&mut a, ~[~2, ~3, ~4]);
+/// assert!(a == ~[~1, ~2, ~3, ~4]);
+/// ~~~
 #[inline(always)]
 pub fn push_all_move<T>(v: &mut ~[T], mut rhs: ~[T]) {
     let new_len = v.len() + rhs.len();
@@ -724,6 +768,9 @@ pub fn dedup<T:Eq>(v: &mut ~[T]) {
 }
 
 // Appending
+
+/// Iterates over the `rhs` vector, copying each element and appending it to the
+/// `lhs`. Afterwards, the `lhs` is then returned for use again.
 #[inline(always)]
 pub fn append<T:Copy>(lhs: ~[T], rhs: &const [T]) -> ~[T] {
     let mut v = lhs;
@@ -731,6 +778,8 @@ pub fn append<T:Copy>(lhs: ~[T], rhs: &const [T]) -> ~[T] {
     v
 }
 
+/// Appends one element to the vector provided. The vector itself is then
+/// returned for use again.
 #[inline(always)]
 pub fn append_one<T>(lhs: ~[T], x: T) -> ~[T] {
     let mut v = lhs;
@@ -806,6 +855,13 @@ pub fn map<T, U>(v: &[T], f: &fn(t: &T) -> U) -> ~[U] {
     result
 }
 
+/// Consumes a vector, mapping it into a different vector. This function takes
+/// ownership of the supplied vector `v`, moving each element into the closure
+/// provided to generate a new element. The vector of new elements is then
+/// returned.
+///
+/// The original vector `v` cannot be used after this function call (it is moved
+/// inside), but there are no restrictions on the type of the vector.
 pub fn map_consume<T, U>(v: ~[T], f: &fn(v: T) -> U) -> ~[U] {
     let mut result = ~[];
     do consume(v) |_i, x| {
@@ -1444,8 +1500,8 @@ pub fn reversed<T:Copy>(v: &const [T]) -> ~[T] {
  * ~~~
  */
 #[inline(always)]
-pub fn _each<'r,T>(v: &'r [T], f: &fn(&'r T) -> bool) -> bool {
-    //             ^^^^
+pub fn each<'r,T>(v: &'r [T], f: &fn(&'r T) -> bool) -> bool {
+    //            ^^^^
     // NB---this CANNOT be &const [T]!  The reason
     // is that you are passing it to `f()` using
     // an immutable.
@@ -1467,13 +1523,11 @@ pub fn _each<'r,T>(v: &'r [T], f: &fn(&'r T) -> bool) -> bool {
     return true;
 }
 
-pub fn each<'r,T>(v: &'r [T], f: &fn(&'r T) -> bool) -> bool { _each(v, f) }
-
 /// Like `each()`, but for the case where you have
 /// a vector with mutable contents and you would like
 /// to mutate the contents as you iterate.
 #[inline(always)]
-pub fn _each_mut<'r,T>(v: &'r mut [T], f: &fn(elem: &'r mut T) -> bool) -> bool {
+pub fn each_mut<'r,T>(v: &'r mut [T], f: &fn(elem: &'r mut T) -> bool) -> bool {
     let mut broke = false;
     do as_mut_buf(v) |p, n| {
         let mut n = n;
@@ -1491,14 +1545,10 @@ pub fn _each_mut<'r,T>(v: &'r mut [T], f: &fn(elem: &'r mut T) -> bool) -> bool
     return broke;
 }
 
-pub fn each_mut<'r,T>(v: &'r mut [T], f: &fn(elem: &'r mut T) -> bool) -> bool {
-    _each_mut(v, f)
-}
-
 /// Like `each()`, but for the case where you have a vector that *may or may
 /// not* have mutable contents.
 #[inline(always)]
-pub fn _each_const<T>(v: &const [T], f: &fn(elem: &const T) -> bool) -> bool {
+pub fn each_const<T>(v: &const [T], f: &fn(elem: &const T) -> bool) -> bool {
     let mut i = 0;
     let n = v.len();
     while i < n {
@@ -1510,17 +1560,13 @@ pub fn _each_const<T>(v: &const [T], f: &fn(elem: &const T) -> bool) -> bool {
     return true;
 }
 
-pub fn each_const<t>(v: &const [t], f: &fn(elem: &const t) -> bool) -> bool {
-    _each_const(v, f)
-}
-
 /**
  * Iterates over a vector's elements and indices
  *
  * Return true to continue, false to break.
  */
 #[inline(always)]
-pub fn _eachi<'r,T>(v: &'r [T], f: &fn(uint, v: &'r T) -> bool) -> bool {
+pub fn eachi<'r,T>(v: &'r [T], f: &fn(uint, v: &'r T) -> bool) -> bool {
     let mut i = 0;
     for each(v) |p| {
         if !f(i, p) { return false; }
@@ -1529,18 +1575,14 @@ pub fn _eachi<'r,T>(v: &'r [T], f: &fn(uint, v: &'r T) -> bool) -> bool {
     return true;
 }
 
-pub fn eachi<'r,T>(v: &'r [T], f: &fn(uint, v: &'r T) -> bool) -> bool {
-    _eachi(v, f)
-}
-
 /**
  * Iterates over a mutable vector's elements and indices
  *
  * Return true to continue, false to break.
  */
 #[inline(always)]
-pub fn _eachi_mut<'r,T>(v: &'r mut [T],
-                        f: &fn(uint, v: &'r mut T) -> bool) -> bool {
+pub fn eachi_mut<'r,T>(v: &'r mut [T],
+                       f: &fn(uint, v: &'r mut T) -> bool) -> bool {
     let mut i = 0;
     for each_mut(v) |p| {
         if !f(i, p) {
@@ -1551,23 +1593,14 @@ pub fn _eachi_mut<'r,T>(v: &'r mut [T],
     return true;
 }
 
-pub fn eachi_mut<'r,T>(v: &'r mut [T],
-                       f: &fn(uint, v: &'r mut T) -> bool) -> bool {
-    _eachi_mut(v, f)
-}
-
 /**
  * Iterates over a vector's elements in reverse
  *
  * Return true to continue, false to break.
  */
 #[inline(always)]
-pub fn _each_reverse<'r,T>(v: &'r [T], blk: &fn(v: &'r T) -> bool) -> bool {
-    _eachi_reverse(v, |_i, v| blk(v))
-}
-
 pub fn each_reverse<'r,T>(v: &'r [T], blk: &fn(v: &'r T) -> bool) -> bool {
-    _each_reverse(v, blk)
+    eachi_reverse(v, |_i, v| blk(v))
 }
 
 /**
@@ -1576,7 +1609,7 @@ pub fn each_reverse<'r,T>(v: &'r [T], blk: &fn(v: &'r T) -> bool) -> bool {
  * Return true to continue, false to break.
  */
 #[inline(always)]
-pub fn _eachi_reverse<'r,T>(v: &'r [T],
+pub fn eachi_reverse<'r,T>(v: &'r [T],
                             blk: &fn(i: uint, v: &'r T) -> bool) -> bool {
     let mut i = v.len();
     while i > 0 {
@@ -1588,11 +1621,6 @@ pub fn _eachi_reverse<'r,T>(v: &'r [T],
     return true;
 }
 
-pub fn eachi_reverse<'r,T>(v: &'r [T],
-                           blk: &fn(i: uint, v: &'r T) -> bool) -> bool {
-    _eachi_reverse(v, blk)
-}
-
 /**
  * Iterates over two vectors simultaneously
  *
@@ -1601,7 +1629,7 @@ pub fn eachi_reverse<'r,T>(v: &'r [T],
  * Both vectors must have the same length
  */
 #[inline]
-pub fn _each2<U, T>(v1: &[U], v2: &[T], f: &fn(u: &U, t: &T) -> bool) -> bool {
+pub fn each2<U, T>(v1: &[U], v2: &[T], f: &fn(u: &U, t: &T) -> bool) -> bool {
     assert_eq!(v1.len(), v2.len());
     for uint::range(0u, v1.len()) |i| {
         if !f(&v1[i], &v2[i]) {
@@ -1611,10 +1639,6 @@ pub fn _each2<U, T>(v1: &[U], v2: &[T], f: &fn(u: &U, t: &T) -> bool) -> bool {
     return true;
 }
 
-pub fn each2<U, T>(v1: &[U], v2: &[T], f: &fn(u: &U, t: &T) -> bool) -> bool {
-    _each2(v1, v2, f)
-}
-
 /**
  *
  * Iterates over two vector with mutable.
@@ -1624,7 +1648,8 @@ pub fn each2<U, T>(v1: &[U], v2: &[T], f: &fn(u: &U, t: &T) -> bool) -> bool {
  * Both vectors must have the same length
  */
 #[inline]
-pub fn _each2_mut<U, T>(v1: &mut [U], v2: &mut [T], f: &fn(u: &mut U, t: &mut T) -> bool) -> bool {
+pub fn each2_mut<U, T>(v1: &mut [U], v2: &mut [T],
+                       f: &fn(u: &mut U, t: &mut T) -> bool) -> bool {
     assert_eq!(v1.len(), v2.len());
     for uint::range(0u, v1.len()) |i| {
         if !f(&mut v1[i], &mut v2[i]) {
@@ -1634,10 +1659,6 @@ pub fn _each2_mut<U, T>(v1: &mut [U], v2: &mut [T], f: &fn(u: &mut U, t: &mut T)
     return true;
 }
 
-pub fn each2_mut<U, T>(v1: &mut [U], v2: &mut [T], f: &fn(u: &mut U, t: &mut T) -> bool) -> bool {
-    _each2_mut(v1, v2, f)
-}
-
 /**
  * Iterate over all permutations of vector `v`.
  *
@@ -1761,6 +1782,9 @@ pub fn as_mut_buf<T,U>(s: &mut [T], f: &fn(*mut T, uint) -> U) -> U {
 
 // Equality
 
+/// Tests whether two slices are equal to one another. This is only true if both
+/// slices are of the same length, and each of the corresponding elements return
+/// true when queried via the `eq` function.
 fn eq<T: Eq>(a: &[T], b: &[T]) -> bool {
     let (a_len, b_len) = (a.len(), b.len());
     if a_len != b_len { return false; }
@@ -1773,6 +1797,9 @@ fn eq<T: Eq>(a: &[T], b: &[T]) -> bool {
     true
 }
 
+/// Similar to the `vec::eq` function, but this is defined for types which
+/// implement `TotalEq` as opposed to types which implement `Eq`. Equality
+/// comparisons are done via the `equals` function instead of `eq`.
 fn equals<T: TotalEq>(a: &[T], b: &[T]) -> bool {
     let (a_len, b_len) = (a.len(), b.len());
     if a_len != b_len { return false; }
@@ -1946,6 +1973,7 @@ fn is_empty(&const self) -> bool { is_empty(*self) }
     fn len(&const self) -> uint { len(*self) }
 }
 
+#[allow(missing_doc)]
 pub trait CopyableVector<T> {
     fn to_owned(&self) -> ~[T];
 }
@@ -1965,6 +1993,7 @@ fn to_owned(&self) -> ~[T] {
     }
 }
 
+#[allow(missing_doc)]
 pub trait ImmutableVector<'self, T> {
     fn slice(&self, start: uint, end: uint) -> &'self [T];
     fn iter(self) -> VecIterator<'self, T>;
@@ -2140,6 +2169,7 @@ unsafe fn unsafe_ref(&self, index: uint) -> *T {
     }
 }
 
+#[allow(missing_doc)]
 pub trait ImmutableEqVector<T:Eq> {
     fn position_elem(&self, t: &T) -> Option<uint>;
     fn rposition_elem(&self, t: &T) -> Option<uint>;
@@ -2159,6 +2189,7 @@ fn rposition_elem(&self, t: &T) -> Option<uint> {
     }
 }
 
+#[allow(missing_doc)]
 pub trait ImmutableCopyableVector<T> {
     fn filtered(&self, f: &fn(&T) -> bool) -> ~[T];
     fn rfind(&self, f: &fn(t: &T) -> bool) -> Option<T>;
@@ -2208,6 +2239,7 @@ unsafe fn unsafe_get(&self, index: uint) -> T {
     }
 }
 
+#[allow(missing_doc)]
 pub trait OwnedVector<T> {
     fn push(&mut self, t: T);
     fn push_all_move(&mut self, rhs: ~[T]);
@@ -2312,6 +2344,7 @@ impl<T> Mutable for ~[T] {
     fn clear(&mut self) { self.truncate(0) }
 }
 
+#[allow(missing_doc)]
 pub trait OwnedCopyableVector<T:Copy> {
     fn push_all(&mut self, rhs: &const [T]);
     fn grow(&mut self, n: uint, initval: &T);
@@ -2335,6 +2368,7 @@ fn grow_set(&mut self, index: uint, initval: &T, val: T) {
     }
 }
 
+#[allow(missing_doc)]
 trait OwnedEqVector<T:Eq> {
     fn dedup(&mut self);
 }
@@ -2346,6 +2380,7 @@ fn dedup(&mut self) {
     }
 }
 
+#[allow(missing_doc)]
 pub trait MutableVector<'self, T> {
     fn mut_slice(self, start: uint, end: uint) -> &'self mut [T];
 
@@ -2386,6 +2421,7 @@ pub unsafe fn from_buf<T>(ptr: *T, elts: uint) -> ~[T] {
 }
 
 /// The internal 'unboxed' representation of a vector
+#[allow(missing_doc)]
 pub struct UnboxedVecRepr {
     fill: uint,
     alloc: uint,
@@ -2405,13 +2441,17 @@ pub mod raw {
     use util;
 
     /// The internal representation of a (boxed) vector
+    #[allow(missing_doc)]
     pub struct VecRepr {
         box_header: managed::raw::BoxHeaderRepr,
         unboxed: UnboxedVecRepr
     }
 
+    /// The internal representation of a slice
     pub struct SliceRepr {
+        /// Pointer to the base of this slice
         data: *u8,
+        /// The length of the slice
         len: uint
     }
 
@@ -2855,13 +2895,14 @@ fn clone(&self) -> ~[A] {
     }
 }
 
-// could be implemented with &[T] with .slice(), but this avoids bounds checks
+/// An external iterator for vectors (use with the std::iterator module)
 pub struct VecIterator<'self, T> {
     priv ptr: *T,
     priv end: *T,
     priv lifetime: &'self T // FIXME: #5922
 }
 
+// could be implemented with &[T] with .slice(), but this avoids bounds checks
 impl<'self, T> Iterator<&'self T> for VecIterator<'self, T> {
     #[inline]
     fn next(&mut self) -> Option<&'self T> {