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.

8 files changed, 35 insertions, 0 deletions

diff --git a/src/libstd/num/cmath.rs b/src/libstd/num/cmath.rs
index 9626224916b..96d3b79e338 100644
--- a/src/libstd/num/cmath.rs
+++ b/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:"
 
diff --git a/src/libstd/num/f32.rs b/src/libstd/num/f32.rs
index 64737c47f29..62ce5ed65e1 100644
--- a/src/libstd/num/f32.rs
+++ b/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};
diff --git a/src/libstd/num/f64.rs b/src/libstd/num/f64.rs
index f01d45bbd1d..de44d861645 100644
--- a/src/libstd/num/f64.rs
+++ b/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};
diff --git a/src/libstd/num/float.rs b/src/libstd/num/float.rs
index 30de95b4846..97d661d8fe2 100644
--- a/src/libstd/num/float.rs
+++ b/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};
diff --git a/src/libstd/num/int_macros.rs b/src/libstd/num/int_macros.rs
index 778e741ff3b..023f44c433c 100644
--- a/src/libstd/num/int_macros.rs
+++ b/src/libstd/num/int_macros.rs
@@ -26,12 +26,17 @@ pub static bytes : uint = ($bits / 8);
 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 }
 
diff --git a/src/libstd/num/num.rs b/src/libstd/num/num.rs
index 96b302d3174..91631d3c9b9 100644
--- a/src/libstd/num/num.rs
+++ b/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};
diff --git a/src/libstd/num/strconv.rs b/src/libstd/num/strconv.rs
index 1d65b84b7ce..30efe9a3922 100644
--- a/src/libstd/num/strconv.rs
+++ b/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};
diff --git a/src/libstd/num/uint_macros.rs b/src/libstd/num/uint_macros.rs
index f16b4f4a740..c2e722f9e0e 100644
--- a/src/libstd/num/uint_macros.rs
+++ b/src/libstd/num/uint_macros.rs
@@ -27,27 +27,39 @@ pub static bytes : uint = ($bits / 8);
 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 }