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.

Author: alexcrichton

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 mod raw {
         (**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 mod raw {
     }
 
     #[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 mod raw {
         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 @@ Similar to a mutable option type, but friendlier.
 
 #[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 @@ use cmp::{Eq, Ord};
     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 @@ by convention implementing the `Clone` trait and calling the
 
 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 @@ clone_impl!(())
 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 @@ and `Eq` to overload the `==` and `!=` operators.
 
 */
 
+#[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 @@ impl<K:Hash + Eq,V:Eq> Eq for HashMap<K, V> {
     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 @@ implement `Reader` and `Writer`, where appropriate.
 
 */
 
+#[allow(missing_doc)];
+
 use result::Result;
 
 use container::Container;

src/libstd/iter.rs

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