libextra: Require documentation by default

src/libextra/arc.rs

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

src/libextra/arena.rs

@@ -32,6 +32,8 @@
 // overhead when initializing plain-old-data and means we don't need
 // to waste time running the destructors of POD.
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use list::{MutList, MutCons, MutNil};

src/libextra/base64.rs

@@ -15,7 +15,10 @@ use core::prelude::*;
 use core::str;
 use core::vec;
 
+/// A trait for converting a value to base64 encoding.
 pub trait ToBase64 {
+    /// Converts the value of `self` to a base64 value, returning the owned
+    /// string
     fn to_base64(&self) -> ~str;
 }
 
@@ -112,6 +115,7 @@ impl<'self> ToBase64 for &'self str {
     }
 }
 
+#[allow(missing_doc)]
 pub trait FromBase64 {
     fn from_base64(&self) -> ~[u8];
 }

src/libextra/bitv.rs

@@ -211,9 +211,11 @@ enum BitvVariant { Big(~BigBitv), Small(~SmallBitv) }
 
 enum Op {Union, Intersect, Assign, Difference}
 
-// The bitvector type
+/// The bitvector type
 pub struct Bitv {
+    /// Internal representation of the bit vector (small or large)
     rep: BitvVariant,
+    /// The number of valid bits in the internal representation
     nbits: uint
 }
 

src/libextra/dbg.rs

@@ -10,6 +10,8 @@
 
 //! Unsafe debugging functions for inspecting values.
 
+#[allow(missing_doc)];
+
 use core::cast::transmute;
 use core::sys;
 

src/libextra/deque.rs

@@ -18,6 +18,7 @@ use core::vec;
 
 static initial_capacity: uint = 32u; // 2^5
 
+#[allow(missing_doc)]
 pub struct Deque<T> {
     priv nelts: uint,
     priv lo: uint,

src/libextra/dlist.rs

@@ -26,6 +26,7 @@ use core::vec;
 
 pub type DListLink<T> = Option<@mut DListNode<T>>;
 
+#[allow(missing_doc)]
 pub struct DListNode<T> {
     data: T,
     linked: bool, // for assertions
@@ -33,6 +34,7 @@ pub struct DListNode<T> {
     next: DListLink<T>,
 }
 
+#[allow(missing_doc)]
 pub struct DList<T> {
     size: uint,
     hd: DListLink<T>,
@@ -106,6 +108,7 @@ pub fn from_elem<T>(data: T) -> @mut DList<T> {
     list
 }
 
+/// Creates a new dlist from a vector of elements, maintaining the same order
 pub fn from_vec<T:Copy>(vec: &[T]) -> @mut DList<T> {
     do vec::foldl(DList(), vec) |list,data| {
         list.push(*data); // Iterating left-to-right -- add newly to the tail.

src/libextra/ebml.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 // Simple Extensible Binary Markup Language (ebml) reader and writer on a

src/libextra/fileinput.rs

@@ -94,6 +94,8 @@ total line count).
     }
 */
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use core::io::ReaderUtil;

src/libextra/flate.rs

@@ -14,6 +14,8 @@ Simple compression
 
 */
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use core::libc::{c_void, size_t, c_int};

src/libextra/flatpipes.rs

@@ -47,6 +47,8 @@ block the scheduler thread, so will their pipes.
 
 */
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 // The basic send/recv interface FlatChan and PortChan will implement

src/libextra/future.rs

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

src/libextra/getopts.rs

@@ -78,6 +78,8 @@
  * ```
  */
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use core::cmp::Eq;

src/libextra/io_util.rs

@@ -11,12 +11,16 @@
 use core::io::{Reader, BytesReader};
 use core::io;
 
+/// An implementation of the io::Reader interface which reads a buffer of bytes
 pub struct BufReader {
+    /// The buffer of bytes to read
     buf: ~[u8],
+    /// The current position in the buffer of bytes
     pos: @mut uint
 }
 
-pub impl BufReader {
+impl BufReader {
+    /// Creates a new buffer reader for the specified buffer
     pub fn new(v: ~[u8]) -> BufReader {
         BufReader {
             buf: v,
@@ -24,7 +28,7 @@ pub impl BufReader {
         }
     }
 
-    priv fn as_bytes_reader<A>(&self, f: &fn(&BytesReader) -> A) -> A {
+    fn as_bytes_reader<A>(&self, f: &fn(&BytesReader) -> A) -> A {
         // Recreating the BytesReader state every call since
         // I can't get the borrowing to work correctly
         let bytes_reader = BytesReader {

src/libextra/json.rs

@@ -43,9 +43,14 @@ pub type List = ~[Json];
 pub type Object = HashMap<~str, Json>;
 
 #[deriving(Eq)]
+/// If an error occurs while parsing some JSON, this is the structure which is
+/// returned
 pub struct Error {
+    /// The line number at which the error occurred
     line: uint,
+    /// The column number at which the error occurred
     col: uint,
+    /// A message describing the type of the error
     msg: @~str,
 }
 
@@ -75,10 +80,13 @@ fn spaces(n: uint) -> ~str {
     return ss;
 }
 
+/// A structure for implementing serialization to JSON.
 pub struct Encoder {
     priv wr: @io::Writer,
 }
 
+/// Creates a new JSON encoder whose output will be written to the writer
+/// specified.
 pub fn Encoder(wr: @io::Writer) -> Encoder {
     Encoder {
         wr: wr
@@ -228,11 +236,14 @@ impl serialize::Encoder for Encoder {
     }
 }
 
+/// Another encoder for JSON, but prints out human-readable JSON instead of
+/// compact data
 pub struct PrettyEncoder {
     priv wr: @io::Writer,
     priv indent: uint,
 }
 
+/// Creates a new encoder whose output will be written to the specified writer
 pub fn PrettyEncoder(wr: @io::Writer) -> PrettyEncoder {
     PrettyEncoder {
         wr: wr,
@@ -468,6 +479,7 @@ pub fn to_pretty_str(json: &Json) -> ~str {
     io::with_str_writer(|wr| to_pretty_writer(wr, json))
 }
 
+#[allow(missing_doc)]
 pub struct Parser {
     priv rdr: @io::Reader,
     priv ch: char,
@@ -846,10 +858,12 @@ pub fn from_str(s: &str) -> Result<Json, Error> {
     }
 }
 
+/// A structure to decode JSON to values in rust.
 pub struct Decoder {
     priv stack: ~[Json],
 }
 
+/// Creates a new decoder instance for decoding the specified JSON value.
 pub fn Decoder(json: Json) -> Decoder {
     Decoder {
         stack: ~[json]
@@ -1200,7 +1214,11 @@ impl Ord for Json {
     fn gt(&self, other: &Json) -> bool { (*other).lt(&(*self))  }
 }
 
-trait ToJson { fn to_json(&self) -> Json; }
+/// A trait for converting values to JSON
+trait ToJson {
+    /// Converts the value of `self` to an instance of JSON
+    fn to_json(&self) -> Json;
+}
 
 impl ToJson for Json {
     fn to_json(&self) -> Json { copy *self }

src/libextra/md4.rs

@@ -21,6 +21,8 @@ struct Quad {
     d: u32
 }
 
+/// Calculates the md4 hash of the given slice of bytes, returning the 128-bit
+/// result as a quad of u32's
 pub fn md4(msg: &[u8]) -> Quad {
     // subtle: if orig_len is merely uint, then the code below
     // which performs shifts by 32 bits or more has undefined
@@ -105,6 +107,8 @@ pub fn md4(msg: &[u8]) -> Quad {
     return Quad {a: a, b: b, c: c, d: d};
 }
 
+/// Calculates the md4 hash of a slice of bytes, returning the hex-encoded
+/// version of the hash
 pub fn md4_str(msg: &[u8]) -> ~str {
     let Quad {a, b, c, d} = md4(msg);
     fn app(a: u32, b: u32, c: u32, d: u32, f: &fn(u32)) {
@@ -123,6 +127,8 @@ pub fn md4_str(msg: &[u8]) -> ~str {
     result
 }
 
+/// Calculates the md4 hash of a string, returning the hex-encoded version of
+/// the hash
 pub fn md4_text(msg: &str) -> ~str { md4_str(str::to_bytes(msg)) }
 
 #[test]

src/libextra/net_ip.rs

@@ -10,6 +10,8 @@
 
 //! Types/fns concerning Internet Protocol (IP), versions 4 & 6
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use core::libc;

src/libextra/net_tcp.rs

@@ -11,6 +11,8 @@
 //! High-level interface to libuv's TCP functionality
 // FIXME #4425: Need FFI fixes
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use future;

src/libextra/net_url.rs

@@ -10,6 +10,8 @@
 
 //! Types/fns concerning URLs (see RFC 3986)
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use core::cmp::Eq;

src/libextra/num/bigint.rs

@@ -597,6 +597,8 @@ impl BigUint {
     }
 
 
+    /// Converts this big integer into a uint, returning the uint::max_value if
+    /// it's too large to fit in a uint.
     pub fn to_uint(&self) -> uint {
         match self.data.len() {
             0 => 0,

src/libextra/num/complex.rs

@@ -25,7 +25,9 @@ use core::num::{Zero,One,ToStrRadix};
 /// A complex number in Cartesian form.
 #[deriving(Eq,Clone)]
 pub struct Cmplx<T> {
+    /// Real portion of the complex number
     re: T,
+    /// Imaginary portion of the complex number
     im: T
 }
 

src/libextra/num/rational.rs

@@ -8,7 +8,6 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-
 //! Rational numbers
 
 use core::prelude::*;
@@ -22,6 +21,7 @@ use super::bigint::BigInt;
 
 /// Represents the ratio between 2 numbers.
 #[deriving(Clone)]
+#[allow(missing_doc)]
 pub struct Ratio<T> {
     numer: T,
     denom: T
@@ -49,7 +49,7 @@ impl<T: Clone + Integer + Ord>
         Ratio { numer: numer, denom: denom }
     }
 
-    // Create a new Ratio. Fails if `denom == 0`.
+    /// Create a new Ratio. Fails if `denom == 0`.
     #[inline(always)]
     pub fn new(numer: T, denom: T) -> Ratio<T> {
         if denom == Zero::zero() {

src/libextra/priority_queue.rs

@@ -17,6 +17,7 @@ use core::unstable::intrinsics::{move_val_init, init};
 use core::util::{replace, swap};
 use core::vec;
 
+#[allow(missing_doc)]
 pub struct PriorityQueue<T> {
     priv data: ~[T],
 }

src/libextra/rc.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#[allow(missing_doc)];
+
 /** Task-local reference counted smart pointers
 
 Task-local reference counted smart pointers are an alternative to managed boxes with deterministic

src/libextra/rope.rs

@@ -33,6 +33,8 @@
  * * access to a character by index is logarithmic (linear in strings);
  */
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use core::str;

src/libextra/semver.rs

@@ -10,6 +10,8 @@
 
 //! Semver parsing and logic
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use core::char;

src/libextra/serialize.rs

@@ -14,6 +14,7 @@
 Core encoding and decoding interfaces.
 */
 
+#[allow(missing_doc)];
 #[forbid(non_camel_case_types)];
 
 use core::prelude::*;

src/libextra/smallintmap.rs

@@ -23,6 +23,7 @@ use core::uint;
 use core::util::replace;
 use core::vec;
 
+#[allow(missing_doc)]
 pub struct SmallIntMap<T> {
     priv v: ~[Option<T>],
 }
@@ -186,6 +187,9 @@ pub impl<V:Copy> SmallIntMap<V> {
     }
 }
 
+/// A set implemented on top of the SmallIntMap type. This set is always a set
+/// of integers, and the space requirements are on the order of the highest
+/// valued integer in the set.
 pub struct SmallIntSet {
     priv map: SmallIntMap<()>
 }

src/libextra/sort.rs

@@ -167,6 +167,7 @@ pub fn quick_sort3<T:Copy + Ord + Eq>(arr: &mut [T]) {
     qsort3(arr, 0, (len - 1) as int);
 }
 
+#[allow(missing_doc)]
 pub trait Sort {
     fn qsort(self);
 }
@@ -179,6 +180,7 @@ static MIN_MERGE: uint = 64;
 static MIN_GALLOP: uint = 7;
 static INITIAL_TMP_STORAGE: uint = 128;
 
+#[allow(missing_doc)]
 pub fn tim_sort<T:Copy + Ord>(array: &mut [T]) {
     let size = array.len();
     if size < 2 {

src/libextra/stats.rs

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

src/libextra/std.rc

@@ -27,8 +27,12 @@ not required in or otherwise suitable for the core library.
 #[crate_type = "lib"];
 
 #[deny(non_camel_case_types)];
+#[deny(missing_doc)];
+
+// NOTE: remove these two attributes after the next snapshot
+#[no_core]; // for stage0
+#[allow(unrecognized_lint)]; // otherwise stage0 is seriously ugly
 
-#[no_core];
 #[no_std];
 
 extern mod core(name = "std", vers = "0.7-pre");

src/libextra/task_pool.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#[allow(missing_doc)];
+
 /// A task pool abstraction. Useful for achieving predictable CPU
 /// parallelism.
 

src/libextra/tempfile.rs

@@ -16,6 +16,8 @@ use core::os;
 use core::rand::RngUtil;
 use core::rand;
 
+/// Attempts to make a temporary directory inside of `tmpdir` whose name will
+/// have the suffix `suffix`. If no directory can be created, None is returned.
 pub fn mkdtemp(tmpdir: &Path, suffix: &str) -> Option<Path> {
     let mut r = rand::rng();
     for 1000.times {

src/libextra/term.rs

@@ -10,6 +10,8 @@
 
 //! Simple ANSI color library
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use core::io;

src/libextra/time.rs

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

src/libextra/treemap.rs

@@ -34,6 +34,7 @@ use core::util::{swap, replace};
 //   * union: |
 // These would be convenient since the methods work like `each`
 
+#[allow(missing_doc)]
 pub struct TreeMap<K, V> {
     priv root: Option<~TreeNode<K, V>>,
     priv length: uint
@@ -242,6 +243,9 @@ impl<'self, T> Iterator<&'self T> for TreeSetIterator<'self, T> {
     }
 }
 
+/// A implementation of the `Set` trait on top of the `TreeMap` container. The
+/// only requirement is that the type of the elements contained ascribes to the
+/// `TotalOrd` trait.
 pub struct TreeSet<T> {
     priv map: TreeMap<T, ()>
 }

src/libextra/unicode.rs

@@ -9,6 +9,7 @@
 // except according to those terms.
 
 #[forbid(deprecated_mode)];
+#[allow(missing_doc)];
 
 pub mod icu {
     pub type UBool = u8;

src/libextra/uv_iotask.rs

@@ -15,6 +15,8 @@
  * `interact` function you can execute code in a uv callback.
  */
 
+#[allow(missing_doc)];
+
 use core::prelude::*;
 
 use ll = uv_ll;

src/libextra/uv_ll.rs

@@ -31,6 +31,7 @@
  */
 
 #[allow(non_camel_case_types)]; // C types
+#[allow(missing_doc)];
 
 use core::prelude::*;
 

src/libextra/workcache.rs

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

src/libstd/run.rs

@@ -10,6 +10,8 @@
 
 //! Process spawning.
 
+#[allow(missing_doc)];
+
 use cast;
 use comm::{stream, SharedChan, GenericChan, GenericPort};
 use int;