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.

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.
 //!

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;

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;

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:
 //!

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};

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,

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

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;
 

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 {

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)];
 

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

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;
 

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.

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

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,

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:"
 

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::*;

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)];
 

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)];
 

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)];
 

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)];
 

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)];
 

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)];
 

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}`.

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)];
 

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)];
 

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)];
 

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)];
 

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)];
 

src/libstd/ops.rs

@@ -13,8 +13,10 @@
 
 /*!
  *
- * Traits for the built-in operators. Implementing these traits allows you to get
+ * Traits representing built-in operators, useful for overloading
- * an effect similar to overloading operators.
+ *
+ * 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)`.

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.
 //!

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.

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

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

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;

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,

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)];
 

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};

src/libstd/str.rs

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

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

src/libstd/to_bytes.rs

@@ -10,7 +10,7 @@
 
 /*!
 
-The `ToBytes` and `IterBytes` traits
+The `ToBytes` and `IterBytes` traits for converting to raw bytes
 
 */
 

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;

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;

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