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, 9 insertions, 1 deletions

diff --git a/src/libstd/container.rs b/src/libstd/container.rs
index 505aa5881c5..065582e2e0d 100644
--- a/src/libstd/container.rs
+++ b/src/libstd/container.rs
@@ -12,6 +12,8 @@
 
 use option::Option;
 
+/// A trait to represent the abstract idea of a container. The only concrete
+/// knowledge known is the number of elements contained within.
 pub trait Container {
     /// Return the number of elements in the container
     fn len(&const self) -> uint;
@@ -20,16 +22,19 @@ pub trait Container {
     fn is_empty(&const self) -> bool;
 }
 
+/// A trait to represent mutable containers
 pub trait Mutable: Container {
     /// Clear the container, removing all values.
     fn clear(&mut self);
 }
 
+/// A map is a key-value store where values may be looked up by their keys. This
+/// trait provides basic operations to operate on these stores.
 pub trait Map<K, V>: Mutable {
     /// Return true if the map contains a value for the specified key
     fn contains_key(&self, key: &K) -> bool;
 
-    // Visits all keys and values
+    /// Visits all keys and values
     fn each<'a>(&'a self, f: &fn(&K, &'a V) -> bool) -> bool;
 
     /// Visit all keys
@@ -65,6 +70,9 @@ pub trait Map<K, V>: Mutable {
     fn pop(&mut self, k: &K) -> Option<V>;
 }
 
+/// A set is a group of objects which are each distinct from one another. This
+/// trait represents actions which can be performed on sets to manipulate and
+/// iterate over them.
 pub trait Set<T>: Mutable {
     /// Return true if the set contains a value
     fn contains(&self, value: &T) -> bool;