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.

1 files changed, 10 insertions, 0 deletions

diff --git a/src/libstd/tuple.rs b/src/libstd/tuple.rs
index 639df89a377..da2c52014e8 100644
--- a/src/libstd/tuple.rs
+++ b/src/libstd/tuple.rs
@@ -10,14 +10,20 @@
 
 //! Operations on tuples
 
+#[allow(missing_doc)];
+
 use kinds::Copy;
 use vec;
 
 pub use self::inner::*;
 
+/// Method extensions to pairs where both types satisfy the `Copy` bound
 pub trait CopyableTuple<T, U> {
+    /// Return the first element of self
     fn first(&self) -> T;
+    /// Return the second element of self
     fn second(&self) -> U;
+    /// Return the results of swapping the two elements of self
     fn swap(&self) -> (U, T);
 }
 
@@ -47,8 +53,12 @@ impl<T:Copy,U:Copy> CopyableTuple<T, U> for (T, U) {
     }
 }
 
+/// Method extensions for pairs where the types don't necessarily satisfy the
+/// `Copy` bound
 pub trait ImmutableTuple<T, U> {
+    /// Return a reference to the first element of self
     fn first_ref<'a>(&'a self) -> &'a T;
+    /// Return a reference to the second element of self
     fn second_ref<'a>(&'a self) -> &'a U;
 }