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.

Author: bors

Diff for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: 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 for: src/libstd/str.rs

@@ -10,7 +10,7 @@
 
 /*!
 
-String manipulation
+Unicode string manipulation (`str` type)
 
 # Basic Usage
 

Diff for: 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 for: 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 for: 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 for: 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 for: 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