auto merge of #11134 : lucab/rust/lucab/libstd-doc, r=cmr

Uniform the short title of modules provided by libstd, in order to make their roles more explicit when glancing at the index.

44 files changed, 50 insertions, 42 deletions

diff --git a/src/libstd/any.rs b/src/libstd/any.rs
index 45a91d01b7a..814cf328771 100644
--- a/src/libstd/any.rs
+++ b/src/libstd/any.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Traits for dynamic typing of any type (through runtime reflection)
+//!
 //! This module implements the `Any` trait, which enables dynamic typing
 //! of any type, through runtime reflection.
 //!
diff --git a/src/libstd/ascii.rs b/src/libstd/ascii.rs
index 4cdcbbdb9e8..97f0a6a9d8a 100644
--- a/src/libstd/ascii.rs
+++ b/src/libstd/ascii.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations on ASCII strings and characters.
+//! Operations on ASCII strings and characters
 
 use to_str::{ToStr,IntoStr};
 use str;
diff --git a/src/libstd/at_vec.rs b/src/libstd/at_vec.rs
index 7b1d29b664b..fd8b88417e0 100644
--- a/src/libstd/at_vec.rs
+++ b/src/libstd/at_vec.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Managed vectors
+//! Operations on managed vectors (`@[T]` type)
 
 use clone::Clone;
 use container::Container;
diff --git a/src/libstd/bool.rs b/src/libstd/bool.rs
index 29c304f9ac5..923aacf352b 100644
--- a/src/libstd/bool.rs
+++ b/src/libstd/bool.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The `bool` module contains useful code to help work with boolean values.
+//! Operations on boolean values (`bool` type)
 //!
 //! A quick summary:
 //!
diff --git a/src/libstd/char.rs b/src/libstd/char.rs
index 93667bb6225..4e9c72de618 100644
--- a/src/libstd/char.rs
+++ b/src/libstd/char.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Utilities for manipulating the char type
+//! Unicode characters manipulation (`char` type)
 
 use cast::transmute;
 use option::{None, Option, Some};
diff --git a/src/libstd/clone.rs b/src/libstd/clone.rs
index 6bff438bbc6..b383c9edf36 100644
--- a/src/libstd/clone.rs
+++ b/src/libstd/clone.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-/*! The Clone trait for types that cannot be "implicitly copied"
+/*! The `Clone` trait for types that cannot be 'implicitly copied'
 
 In Rust, some simple types are "implicitly copyable" and when you
 assign them or pass them as arguments, the receiver will get a copy,
diff --git a/src/libstd/comm/mod.rs b/src/libstd/comm/mod.rs
index 26e235e6d52..6281f6d53ab 100644
--- a/src/libstd/comm/mod.rs
+++ b/src/libstd/comm/mod.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Rust Communication Primitives
+//! Communication primitives for concurrent tasks (`Chan` and `Port` types)
 //!
 //! Rust makes it very difficult to share data among tasks to prevent race
 //! conditions and to improve parallelism, but there is often a need for
diff --git a/src/libstd/container.rs b/src/libstd/container.rs
index c91a53f9663..326b9fa3d33 100644
--- a/src/libstd/container.rs
+++ b/src/libstd/container.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Container traits
+//! Traits for generic containers (including `Map` and `Set`)
 
 use option::Option;
 
diff --git a/src/libstd/default.rs b/src/libstd/default.rs
index 120cf3fa801..aaba23c683b 100644
--- a/src/libstd/default.rs
+++ b/src/libstd/default.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The Default trait
+//! The `Default` trait for types which may have meaningful default values
 
 /// A trait that types which have a useful default value should implement.
 pub trait Default {
diff --git a/src/libstd/either.rs b/src/libstd/either.rs
index 96f4e524852..d07006aa6de 100644
--- a/src/libstd/either.rs
+++ b/src/libstd/either.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! A type that represents one of two alternatives
+//! Representing values with two possibilities (`Either` type)
 
 #[allow(missing_doc)];
 
diff --git a/src/libstd/fmt/mod.rs b/src/libstd/fmt/mod.rs
index 3bbf8031fff..cd9c0f5d2b7 100644
--- a/src/libstd/fmt/mod.rs
+++ b/src/libstd/fmt/mod.rs
@@ -10,7 +10,7 @@
 
 /*!
 
-The Formatting Module
+Utilities for formatting and printing strings
 
 This module contains the runtime support for the `format!` syntax extension.
 This macro is implemented in the compiler to emit calls to this module in order
diff --git a/src/libstd/from_str.rs b/src/libstd/from_str.rs
index e5bf9f6bb2a..289a5f11c4f 100644
--- a/src/libstd/from_str.rs
+++ b/src/libstd/from_str.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! The trait for types that can be created from strings
+//! The `FromStr` trait for types that can be created from strings
 
 use option::Option;
 
diff --git a/src/libstd/hashmap.rs b/src/libstd/hashmap.rs
index 03956560db9..6ef327ab617 100644
--- a/src/libstd/hashmap.rs
+++ b/src/libstd/hashmap.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! An unordered map and set type implemented as hash tables
+//! Unordered containers, implemented as hash-tables (`HashSet` and `HashMap` types)
 //!
 //! The tables use a keyed hash with new random keys generated for each container, so the ordering
 //! of a set of keys in a hash table is randomized.
diff --git a/src/libstd/kinds.rs b/src/libstd/kinds.rs
index b116f92f3d0..462a0f1b0c8 100644
--- a/src/libstd/kinds.rs
+++ b/src/libstd/kinds.rs
@@ -9,7 +9,7 @@
 // except according to those terms.
 
 /*!
-The kind traits
+Primitive traits representing basic 'kinds' of types
 
 Rust types can be classified in various useful ways according to
 intrinsic properties of the type. These classifications, often called
diff --git a/src/libstd/logging.rs b/src/libstd/logging.rs
index fb83cfdd6ea..d1b812ae365 100644
--- a/src/libstd/logging.rs
+++ b/src/libstd/logging.rs
@@ -10,7 +10,7 @@
 
 /*!
 
-Logging
+Utilities for program-wide and customizable logging
 
 This module is used by the compiler when emitting output for the logging family
 of macros. The methods of this module shouldn't necessarily be used directly,
diff --git a/src/libstd/num/cmath.rs b/src/libstd/num/cmath.rs
index 5212b6fc15e..a91dee7fa50 100644
--- a/src/libstd/num/cmath.rs
+++ b/src/libstd/num/cmath.rs
@@ -12,6 +12,8 @@
 #[allow(non_uppercase_statics)];
 #[allow(dead_code)];
 
+//! Bindings for the C math library (for basic mathematic functions)
+
 // 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 2cb7d527618..43b0235c5f4 100644
--- a/src/libstd/num/f32.rs
+++ b/src/libstd/num/f32.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `f32`
+//! Operations and constants for 32-bits floats (`f32` type)
 #[allow(missing_doc)];
 
 use prelude::*;
diff --git a/src/libstd/num/f64.rs b/src/libstd/num/f64.rs
index 1f01c26ad76..c2d19d41215 100644
--- a/src/libstd/num/f64.rs
+++ b/src/libstd/num/f64.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `f64`
+//! Operations and constants for 64-bits floats (`f64` type)
 
 #[allow(missing_doc)];
 
diff --git a/src/libstd/num/i16.rs b/src/libstd/num/i16.rs
index fcf1f24d0e4..5f431dfdf04 100644
--- a/src/libstd/num/i16.rs
+++ b/src/libstd/num/i16.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `i16`
+//! Operations and constants for signed 16-bits integers (`i16` type)
 
 #[allow(non_uppercase_statics)];
 
diff --git a/src/libstd/num/i32.rs b/src/libstd/num/i32.rs
index 385e1c91ca5..8bb03344923 100644
--- a/src/libstd/num/i32.rs
+++ b/src/libstd/num/i32.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `i32`
+//! Operations and constants for signed 32-bits integers (`i32` type)
 
 #[allow(non_uppercase_statics)];
 
diff --git a/src/libstd/num/i64.rs b/src/libstd/num/i64.rs
index f6b369b1312..891043ad5f8 100644
--- a/src/libstd/num/i64.rs
+++ b/src/libstd/num/i64.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `i64`
+//! Operations and constants for signed 64-bits integers (`i64` type)
 
 #[allow(non_uppercase_statics)];
 
diff --git a/src/libstd/num/i8.rs b/src/libstd/num/i8.rs
index 9de90ca4657..fd123ec57cc 100644
--- a/src/libstd/num/i8.rs
+++ b/src/libstd/num/i8.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `i8`
+//! Operations and constants for signed 8-bits integers (`i8` type)
 
 #[allow(non_uppercase_statics)];
 
diff --git a/src/libstd/num/int.rs b/src/libstd/num/int.rs
index 517bd45e45b..123555e4a63 100644
--- a/src/libstd/num/int.rs
+++ b/src/libstd/num/int.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `int`
+//! Operations and constants for architecture-sized signed integers (`int` type)
 
 #[allow(non_uppercase_statics)];
 
diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs
index 0f81a5faac8..8dbec0f63c6 100644
--- a/src/libstd/num/mod.rs
+++ b/src/libstd/num/mod.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Numeric traits and functions for generic mathematics.
+//! Numeric traits and functions for generic mathematics
 //!
 //! These are implemented for the primitive numeric types in `std::{u8, u16,
 //! u32, u64, uint, i8, i16, i32, i64, int, f32, f64, float}`.
diff --git a/src/libstd/num/u16.rs b/src/libstd/num/u16.rs
index ed8ec3b6c54..7e4145fc723 100644
--- a/src/libstd/num/u16.rs
+++ b/src/libstd/num/u16.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `u16`
+//! Operations and constants for unsigned 16-bits integers (`u16` type)
 
 #[allow(non_uppercase_statics)];
 
diff --git a/src/libstd/num/u32.rs b/src/libstd/num/u32.rs
index 29775498033..34c2a892d56 100644
--- a/src/libstd/num/u32.rs
+++ b/src/libstd/num/u32.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `u32`
+//! Operations and constants for unsigned 32-bits integers (`u32` type)
 
 #[allow(non_uppercase_statics)];
 
diff --git a/src/libstd/num/u64.rs b/src/libstd/num/u64.rs
index dc43801eb39..c307b038627 100644
--- a/src/libstd/num/u64.rs
+++ b/src/libstd/num/u64.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `u64`
+//! Operations and constants for unsigned 64-bits integer (`u64` type)
 
 #[allow(non_uppercase_statics)];
 
diff --git a/src/libstd/num/u8.rs b/src/libstd/num/u8.rs
index 12ad4efdbd5..06bda72c5fe 100644
--- a/src/libstd/num/u8.rs
+++ b/src/libstd/num/u8.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `u8`
+//! Operations and constants for unsigned 8-bits integers (`u8` type)
 
 #[allow(non_uppercase_statics)];
 
diff --git a/src/libstd/num/uint.rs b/src/libstd/num/uint.rs
index 549490050c5..a752cd938ba 100644
--- a/src/libstd/num/uint.rs
+++ b/src/libstd/num/uint.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations and constants for `uint`
+//! Operations and constants for architecture-sized unsigned integers (`uint` type)
 
 #[allow(non_uppercase_statics)];
 
diff --git a/src/libstd/ops.rs b/src/libstd/ops.rs
index 5bce884448a..fbefce71e88 100644
--- a/src/libstd/ops.rs
+++ b/src/libstd/ops.rs
@@ -13,8 +13,10 @@
 
 /*!
  *
- * Traits for the built-in operators. Implementing these traits allows you to get
- * an effect similar to overloading operators.
+ * Traits representing built-in operators, useful for overloading
+ *
+ * Implementing these traits allows you to get an effect similar to
+ * overloading operators.
  *
  * The values for the right hand side of an operator are automatically
  * borrowed, so `a + b` is sugar for `a.add(&b)`.
diff --git a/src/libstd/option.rs b/src/libstd/option.rs
index 5467a894cff..35db800b3cc 100644
--- a/src/libstd/option.rs
+++ b/src/libstd/option.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Operations on the ubiquitous `Option` type.
+//! Optionally nullable values (`Option` type)
 //!
 //! Type `Option` represents an optional value.
 //!
diff --git a/src/libstd/prelude.rs b/src/libstd/prelude.rs
index f59264254ad..3c81ff661bc 100644
--- a/src/libstd/prelude.rs
+++ b/src/libstd/prelude.rs
@@ -10,6 +10,8 @@
 
 /*!
 
+The standard module imported by default into all Rust modules
+
 Many programming languages have a 'prelude': a particular subset of the
 libraries that come with the language. Every program imports the prelude by
 default.
diff --git a/src/libstd/rand/mod.rs b/src/libstd/rand/mod.rs
index 917b14e4b4f..336bbe637b4 100644
--- a/src/libstd/rand/mod.rs
+++ b/src/libstd/rand/mod.rs
@@ -9,7 +9,7 @@
 // except according to those terms.
 
 /*!
-Random number generation.
+Utilities for random number generation
 
 The key functions are `random()` and `Rng::gen()`. These are polymorphic
 and so can be used to generate any type that implements `Rand`. Type inference
diff --git a/src/libstd/rc.rs b/src/libstd/rc.rs
index f2beea992c6..9158e8cdb89 100644
--- a/src/libstd/rc.rs
+++ b/src/libstd/rc.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-/*! Task-local reference counted boxes
+/*! Task-local reference-counted boxes (`Rc` type)
 
 The `Rc` type provides shared ownership of an immutable value. Destruction is deterministic, and
 will occur as soon as the last owner is gone. It is marked as non-sendable because it avoids the
diff --git a/src/libstd/result.rs b/src/libstd/result.rs
index 2dbba309698..4e8db15a92e 100644
--- a/src/libstd/result.rs
+++ b/src/libstd/result.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! A type representing either success or failure
+//! Signaling success or failure states (`Result` type)
 
 use clone::Clone;
 use cmp::Eq;
diff --git a/src/libstd/rt/mod.rs b/src/libstd/rt/mod.rs
index 0dd6c883d5b..9bd804f7bab 100644
--- a/src/libstd/rt/mod.rs
+++ b/src/libstd/rt/mod.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-/*! The Rust Runtime, including the task scheduler and I/O
+/*! Runtime services, including the task scheduler and I/O dispatcher
 
 The `rt` module provides the private runtime infrastructure necessary
 to support core language features like the exchange and local heap,
diff --git a/src/libstd/run.rs b/src/libstd/run.rs
index 33be746e604..337cb744080 100644
--- a/src/libstd/run.rs
+++ b/src/libstd/run.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Process spawning.
+//! Utilities for spawning and managing processes
 
 #[allow(missing_doc)];
 
diff --git a/src/libstd/send_str.rs b/src/libstd/send_str.rs
index b0bc4c3f467..f10818b052d 100644
--- a/src/libstd/send_str.rs
+++ b/src/libstd/send_str.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! `SendStr` definition and trait implementations
+//! The `SendStr` trait for optionally static strings
 
 use clone::{Clone, DeepClone};
 use cmp::{Eq, TotalEq, Ord, TotalOrd, Equiv};
diff --git a/src/libstd/str.rs b/src/libstd/str.rs
index 2f5ef932a18..8e6d8523f77 100644
--- a/src/libstd/str.rs
+++ b/src/libstd/str.rs
@@ -10,7 +10,7 @@
 
 /*!
 
-String manipulation
+Unicode string manipulation (`str` type)
 
 # Basic Usage
 
diff --git a/src/libstd/task.rs b/src/libstd/task.rs
index 2f0f9bf64af..bc45b9e3c4a 100644
--- a/src/libstd/task.rs
+++ b/src/libstd/task.rs
@@ -9,7 +9,7 @@
 // except according to those terms.
 
 /*!
- * Task management.
+ * Utilities for managing and scheduling tasks
  *
  * An executing Rust program consists of a tree of tasks, each with their own
  * stack, and sole ownership of their allocated heap data. Tasks communicate
diff --git a/src/libstd/to_bytes.rs b/src/libstd/to_bytes.rs
index 815320be94e..9de812ed385 100644
--- a/src/libstd/to_bytes.rs
+++ b/src/libstd/to_bytes.rs
@@ -10,7 +10,7 @@
 
 /*!
 
-The `ToBytes` and `IterBytes` traits
+The `ToBytes` and `IterBytes` traits for converting to raw bytes
 
 */
 
diff --git a/src/libstd/trie.rs b/src/libstd/trie.rs
index 09dd091d0e7..4f3f253d5e2 100644
--- a/src/libstd/trie.rs
+++ b/src/libstd/trie.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! An ordered map and set for integer keys implemented as a radix trie
+//! Ordered containers with integer keys, implemented as radix tries (`TrieSet` and `TrieMap` types)
 
 use prelude::*;
 use uint;
diff --git a/src/libstd/util.rs b/src/libstd/util.rs
index 85dac814add..d12d61ed46c 100644
--- a/src/libstd/util.rs
+++ b/src/libstd/util.rs
@@ -8,7 +8,7 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Miscellaneous helpers for common patterns.
+//! Miscellaneous helpers for common patterns
 
 use cast;
 use ptr;
diff --git a/src/libstd/vec.rs b/src/libstd/vec.rs
index aa349ed8186..9662a610810 100644
--- a/src/libstd/vec.rs
+++ b/src/libstd/vec.rs
@@ -10,7 +10,7 @@
 
 /*!
 
-Vector manipulation
+Utilities for vector manipulation
 
 The `vec` module contains useful code to help work with vector values.
 Vectors are Rust's list type. Vectors contain zero or more values of