Add docs to a bunch of stuff

mk/crates.mk

@@ -73,7 +73,7 @@ DEPS_arena := std collections
 DEPS_graphviz := std
 DEPS_glob := std
 DEPS_serialize := std collections log
-DEPS_term := std collections
+DEPS_term := std collections log
 DEPS_semver := std
 DEPS_uuid := std serialize rand
 DEPS_sync := std

src/libarena/lib.rs

@@ -14,6 +14,10 @@
 //! once, once the arena itself is destroyed. They do not support deallocation
 //! of individual objects while the arena itself is still alive. The benefit
 //! of an arena is very fast allocation; just a pointer bump.
+//!
+//! This crate has two arenas implemented: TypedArena, which is a simpler
+//! arena but can only hold objects of a single type, and Arena, which is a
+//! more complex, slower Arena which can hold objects of any type.
 
 #![crate_id = "arena#0.11.0-pre"]
 #![crate_type = "rlib"]
@@ -56,41 +60,42 @@ impl Chunk {
     }
 }
 
-// Arenas are used to quickly allocate objects that share a
-// lifetime. The arena uses ~[u8] vectors as a backing store to
-// allocate objects from. For each allocated object, the arena stores
-// a pointer to the type descriptor followed by the
-// object. (Potentially with alignment padding after each of them.)
-// When the arena is destroyed, it iterates through all of its chunks,
-// and uses the tydesc information to trace through the objects,
-// calling the destructors on them.
-// One subtle point that needs to be addressed is how to handle
-// failures while running the user provided initializer function. It
-// is important to not run the destructor on uninitialized objects, but
-// how to detect them is somewhat subtle. Since alloc() can be invoked
-// recursively, it is not sufficient to simply exclude the most recent
-// object. To solve this without requiring extra space, we use the low
-// order bit of the tydesc pointer to encode whether the object it
-// describes has been fully initialized.
-
-// As an optimization, objects with destructors are stored in
-// different chunks than objects without destructors. This reduces
-// overhead when initializing plain-old-data and means we don't need
-// to waste time running the destructors of POD.
+/// A slower reflection-based arena that can allocate objects of any type.
+///
+/// This arena uses Vec<u8> as a backing store to allocate objects from.  For
+/// each allocated object, the arena stores a pointer to the type descriptor
+/// followed by the object. (Potentially with alignment padding after each
+/// element.) When the arena is destroyed, it iterates through all of its
+/// chunks, and uses the tydesc information to trace through the objects,
+/// calling the destructors on them.  One subtle point that needs to be
+/// addressed is how to handle failures while running the user provided
+/// initializer function. It is important to not run the destructor on
+/// uninitialized objects, but how to detect them is somewhat subtle. Since
+/// alloc() can be invoked recursively, it is not sufficient to simply exclude
+/// the most recent object. To solve this without requiring extra space, we
+/// use the low order bit of the tydesc pointer to encode whether the object
+/// it describes has been fully initialized.
+///
+/// As an optimization, objects with destructors are stored in
+/// different chunks than objects without destructors. This reduces
+/// overhead when initializing plain-old-data and means we don't need
+/// to waste time running the destructors of POD.
 pub struct Arena {
     // The head is separated out from the list as a unbenchmarked
-    // microoptimization, to avoid needing to case on the list to
-    // access the head.
+    // microoptimization, to avoid needing to case on the list to access the
+    // head.
     head: Chunk,
     copy_head: Chunk,
     chunks: RefCell<Vec<Chunk>>,
 }
 
 impl Arena {
+    /// Allocate a new Arena with 32 bytes preallocated.
     pub fn new() -> Arena {
         Arena::new_with_size(32u)
     }
 
+    /// Allocate a new Arena with `initial_size` bytes preallocated.
     pub fn new_with_size(initial_size: uint) -> Arena {
         Arena {
             head: chunk(initial_size, false),
@@ -265,7 +270,8 @@ impl Arena {
         }
     }
 
-    // The external interface
+    /// Allocate a new item in the arena, using `op` to initialize the value
+    /// and returning a reference to it.
     #[inline]
     pub fn alloc<'a, T>(&'a self, op: || -> T) -> &'a T {
         unsafe {
@@ -313,7 +319,7 @@ fn test_arena_destructors_fail() {
     });
 }
 
-/// An arena that can hold objects of only one type.
+/// A faster arena that can hold objects of only one type.
 ///
 /// Safety note: Modifying objects in the arena that have already had their
 /// `drop` destructors run can cause leaks, because the destructor will not
@@ -405,13 +411,13 @@ impl<T> TypedArenaChunk<T> {
 }
 
 impl<T> TypedArena<T> {
-    /// Creates a new arena with preallocated space for 8 objects.
+    /// Creates a new TypedArena with preallocated space for 8 objects.
     #[inline]
     pub fn new() -> TypedArena<T> {
         TypedArena::with_capacity(8)
     }
 
-    /// Creates a new arena with preallocated space for the given number of
+    /// Creates a new TypedArena with preallocated space for the given number of
     /// objects.
     #[inline]
     pub fn with_capacity(capacity: uint) -> TypedArena<T> {
@@ -423,7 +429,7 @@ impl<T> TypedArena<T> {
         }
     }
 
-    /// Allocates an object into this arena.
+    /// Allocates an object in the TypedArena, returning a reference to it.
     #[inline]
     pub fn alloc<'a>(&'a self, object: T) -> &'a T {
         unsafe {

src/libflate/lib.rs

@@ -10,7 +10,11 @@
 
 /*!
 
-Simple compression
+Simple [DEFLATE][def]-based compression. This is a wrapper around the
+[`miniz`][mz] library, which is a one-file pure-C implementation of zlib.
+
+[def]: https://en.wikipedia.org/wiki/DEFLATE
+[mz]: https://code.google.com/p/miniz/
 
 */
 
@@ -31,23 +35,21 @@ extern crate libc;
 use std::c_vec::CVec;
 use libc::{c_void, size_t, c_int};
 
-
-pub mod rustrt {
-    use libc::{c_void, size_t, c_int};
-    #[link(name = "miniz", kind = "static")]
-    extern {
-        pub fn tdefl_compress_mem_to_heap(psrc_buf: *c_void,
-                                          src_buf_len: size_t,
-                                          pout_len: *mut size_t,
-                                          flags: c_int)
-                                          -> *mut c_void;
-
-        pub fn tinfl_decompress_mem_to_heap(psrc_buf: *c_void,
-                                            src_buf_len: size_t,
-                                            pout_len: *mut size_t,
-                                            flags: c_int)
-                                            -> *mut c_void;
-    }
+#[link(name = "miniz", kind = "static")]
+extern {
+    /// Raw miniz compression function.
+    fn tdefl_compress_mem_to_heap(psrc_buf: *c_void,
+                                      src_buf_len: size_t,
+                                      pout_len: *mut size_t,
+                                      flags: c_int)
+                                      -> *mut c_void;
+
+    /// Raw miniz decompression function.
+    fn tinfl_decompress_mem_to_heap(psrc_buf: *c_void,
+                                        src_buf_len: size_t,
+                                        pout_len: *mut size_t,
+                                        flags: c_int)
+                                        -> *mut c_void;
 }
 
 static LZ_NORM : c_int = 0x80;  // LZ with 128 probes, "normal"
@@ -57,7 +59,7 @@ static TDEFL_WRITE_ZLIB_HEADER : c_int = 0x01000; // write zlib header and adler
 fn deflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
     unsafe {
         let mut outsz : size_t = 0;
-        let res = rustrt::tdefl_compress_mem_to_heap(bytes.as_ptr() as *c_void,
+        let res = tdefl_compress_mem_to_heap(bytes.as_ptr() as *c_void,
                                                      bytes.len() as size_t,
                                                      &mut outsz,
                                                      flags);
@@ -69,18 +71,20 @@ fn deflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
     }
 }
 
+/// Compress a buffer, without writing any sort of header on the output.
 pub fn deflate_bytes(bytes: &[u8]) -> Option<CVec<u8>> {
     deflate_bytes_internal(bytes, LZ_NORM)
 }
 
+/// Compress a buffer, using a header that zlib can understand.
 pub fn deflate_bytes_zlib(bytes: &[u8]) -> Option<CVec<u8>> {
     deflate_bytes_internal(bytes, LZ_NORM | TDEFL_WRITE_ZLIB_HEADER)
 }
 
 fn inflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
     unsafe {
         let mut outsz : size_t = 0;
-        let res = rustrt::tinfl_decompress_mem_to_heap(bytes.as_ptr() as *c_void,
+        let res = tinfl_decompress_mem_to_heap(bytes.as_ptr() as *c_void,
                                                        bytes.len() as size_t,
                                                        &mut outsz,
                                                        flags);
@@ -92,10 +96,12 @@ fn inflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
     }
 }
 
+/// Decompress a buffer, without parsing any sort of header on the input.
 pub fn inflate_bytes(bytes: &[u8]) -> Option<CVec<u8>> {
     inflate_bytes_internal(bytes, 0)
 }
 
+/// Decompress a buffer that starts with a zlib header.
 pub fn inflate_bytes_zlib(bytes: &[u8]) -> Option<CVec<u8>> {
     inflate_bytes_internal(bytes, TINFL_FLAG_PARSE_ZLIB_HEADER)
 }

src/libnum/lib.rs

@@ -8,6 +8,40 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Simple numerics.
+//!
+//! This crate contains arbitrary-sized integer, rational, and complex types.
+//!
+//! ## Example
+//!
+//! This example uses the BigRational type and [Newton's method][newt] to
+//! approximate a square root to arbitrary precision:
+//!
+//! ```
+//! extern crate num;
+//!
+//! use num::bigint::BigInt;
+//! use num::rational::{Ratio, BigRational};
+//!
+//! fn approx_sqrt(number: u64, iterations: uint) -> BigRational {
+//!     let start: Ratio<BigInt> = Ratio::from_integer(FromPrimitive::from_u64(number).unwrap());
+//!     let mut approx = start.clone();
+//!
+//!     for _ in range(0, iterations) {
+//!         approx = (approx + (start / approx)) /
+//!             Ratio::from_integer(FromPrimitive::from_u64(2).unwrap());
+//!     }
+//!
+//!     approx
+//! }
+//!
+//! fn main() {
+//!     println!("{}", approx_sqrt(10, 4)); // prints 4057691201/1283082416
+//! }
+//! ```
+//!
+//! [newt]: https://en.wikipedia.org/wiki/Methods_of_computing_square_roots#Babylonian_method
+
 #![feature(macro_rules)]
 
 #![crate_id = "num#0.11.0-pre"]

src/libsyntax/diagnostic.rs

@@ -259,7 +259,7 @@ pub struct EmitterWriter {
 }
 
 enum Destination {
-    Terminal(term::Terminal<io::stdio::StdWriter>),
+    Terminal(Box<term::Terminal<Box<Writer:Send>>:Send>),
     Raw(Box<Writer:Send>),
 }
 
@@ -274,9 +274,9 @@ impl EmitterWriter {
         };
 
         if use_color {
-            let dst = match term::Terminal::new(stderr.unwrap()) {
-                Ok(t) => Terminal(t),
-                Err(..) => Raw(box io::stderr()),
+            let dst = match term::stderr() {
+                Some(t) => Terminal(t),
+                None    => Raw(box stderr),
             };
             EmitterWriter { dst: dst }
         } else {