auto merge of #6798 : alexcrichton/rust/doc-lints, r=pcwalton

These commits perform a variety of actions:

1. The linting of missing documentation has been consolidated under one `missing_doc` attribute, and many more things are linted about.
2. A test was added for linting missing documentation, which revealed a large number of corner cases in both linting and the `missing_doc` lint pass. Some notable edge cases:
  * When compiling with `--test`, all `missing_doc` warnings are suppressed
  * If any parent of the current item has `#[doc(hidden)]`, then the `missing_doc` warning is suppressed
3. Both the std and extra libraries were modified to `#[deny(missing_doc)]` by default.

I believe that the libraries are getting to the point where they're fairly well documented, and they should definitely stay that way. If developing a particular new module, it's easy enough to add `#[allow(missing_doc)]` at the top, but those should definitely be flags for removal in favor of actual documentation.

I added as much documentation as I could throughout std/extra, although I avoided trying to document things that I knew nothing about. I can't say that this lint pass will vouch for the quality of the documentation of std/extra, but it will certainly make sure that there's at least some describing words.

That being said, I may have a different opinion, so I don't mind amending these commits to turn off the lint by default for std/extra if people think otherwise.

Author: bors

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,13 +26,15 @@ use core::vec;
 
 pub type DListLink<T> = Option<@mut DListNode<T>>;
 
+#[allow(missing_doc)]
 pub struct DListNode<T> {
     data: T,
     linked: bool, // for assertions
     prev: DListLink<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,20 +11,24 @@
 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,
             pos: @mut 0
         }
     }
 
-    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::*;