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, 12 insertions, 0 deletions

diff --git a/src/libstd/hashmap.rs b/src/libstd/hashmap.rs
index e6ccb7a1d6b..72f92bc1522 100644
--- a/src/libstd/hashmap.rs
+++ b/src/libstd/hashmap.rs
@@ -34,6 +34,14 @@ struct Bucket<K,V> {
     value: V,
 }
 
+/// A hash map implementation which uses linear probing along with the SipHash
+/// hash function for internal state. This means that the order of all hash maps
+/// is randomized by keying each hash map randomly on creation.
+///
+/// It is required that the keys implement the `Eq` and `Hash` traits, although
+/// this can frequently be achieved by just implementing the `Eq` and
+/// `IterBytes` traits as `Hash` is automatically implemented for types that
+/// implement `IterBytes`.
 pub struct HashMap<K,V> {
     priv k0: u64,
     priv k1: u64,
@@ -53,6 +61,7 @@ fn resize_at(capacity: uint) -> uint {
     ((capacity as float) * 3. / 4.) as uint
 }
 
+/// Creates a new hash map with the specified capacity.
 pub fn linear_map_with_capacity<K:Eq + Hash,V>(
     initial_capacity: uint) -> HashMap<K, V> {
     let mut r = rand::task_rng();
@@ -539,6 +548,9 @@ impl<K:Hash + Eq,V:Eq> Eq for HashMap<K, V> {
     fn ne(&self, other: &HashMap<K, V>) -> bool { !self.eq(other) }
 }
 
+/// An implementation of a hash set using the underlying representation of a
+/// HashMap where the value is (). As with the `HashMap` type, a `HashSet`
+/// requires that the elements implement the `Eq` and `Hash` traits.
 pub struct HashSet<T> {
     priv map: HashMap<T, ()>
 }