From a9a7a427a1f1a61497105283594d32b976d7559f Mon Sep 17 00:00:00 2001
From: Luca Bruno <lucab@debian.org>
Date: Tue, 24 Dec 2013 17:08:28 +0100
Subject: [PATCH] std: uniform modules titles for doc

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

Signed-off-by: Luca Bruno <lucab@debian.org>
---
 src/libstd/any.rs       | 2 ++
 src/libstd/ascii.rs     | 2 +-
 src/libstd/at_vec.rs    | 2 +-
 src/libstd/bool.rs      | 2 +-
 src/libstd/char.rs      | 2 +-
 src/libstd/clone.rs     | 2 +-
 src/libstd/comm/mod.rs  | 2 +-
 src/libstd/container.rs | 2 +-
 src/libstd/default.rs   | 2 +-
 src/libstd/either.rs    | 2 +-
 src/libstd/fmt/mod.rs   | 2 +-
 src/libstd/from_str.rs  | 2 +-
 src/libstd/hashmap.rs   | 2 +-
 src/libstd/kinds.rs     | 2 +-
 src/libstd/logging.rs   | 2 +-
 src/libstd/num/cmath.rs | 2 ++
 src/libstd/num/f32.rs   | 2 +-
 src/libstd/num/f64.rs   | 2 +-
 src/libstd/num/i16.rs   | 2 +-
 src/libstd/num/i32.rs   | 2 +-
 src/libstd/num/i64.rs   | 2 +-
 src/libstd/num/i8.rs    | 2 +-
 src/libstd/num/int.rs   | 2 +-
 src/libstd/num/mod.rs   | 2 +-
 src/libstd/num/u16.rs   | 2 +-
 src/libstd/num/u32.rs   | 2 +-
 src/libstd/num/u64.rs   | 2 +-
 src/libstd/num/u8.rs    | 2 +-
 src/libstd/num/uint.rs  | 2 +-
 src/libstd/ops.rs       | 6 ++++--
 src/libstd/option.rs    | 2 +-
 src/libstd/prelude.rs   | 2 ++
 src/libstd/rand/mod.rs  | 2 +-
 src/libstd/rc.rs        | 2 +-
 src/libstd/result.rs    | 2 +-
 src/libstd/rt/mod.rs    | 2 +-
 src/libstd/run.rs       | 2 +-
 src/libstd/send_str.rs  | 2 +-
 src/libstd/str.rs       | 2 +-
 src/libstd/task.rs      | 2 +-
 src/libstd/to_bytes.rs  | 2 +-
 src/libstd/trie.rs      | 2 +-
 src/libstd/util.rs      | 2 +-
 src/libstd/vec.rs       | 2 +-
 44 files changed, 50 insertions(+), 42 deletions(-)

diff --git a/src/libstd/any.rs b/src/libstd/any.rs
index 45a91d01b7a9c..814cf3287717b 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 4cdcbbdb9e8e1..97f0a6a9d8af8 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 7b1d29b664b6d..fd8b88417e0eb 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 29c304f9ac539..923aacf352bc0 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 93667bb6225ff..4e9c72de61887 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 6bff438bbc605..b383c9edf36d3 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 21db234122b2e..5ff3b6ed9c45f 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 c91a53f966388..326b9fa3d3321 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 120cf3fa8013b..aaba23c683bca 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 96f4e524852d1..d07006aa6de75 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 3bbf8031fff93..cd9c0f5d2b77c 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 e5bf9f6bb2a41..289a5f11c4f61 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 b5d5b8a6149bd..d6d95bf486604 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 b116f92f3d0c9..462a0f1b0c8a4 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 fb83cfdd6ea8a..d1b812ae36567 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 5212b6fc15ec4..a91dee7fa501c 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 2cb7d527618e6..43b0235c5f45a 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 1f01c26ad76f3..c2d19d4121542 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 fcf1f24d0e455..5f431dfdf0427 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 385e1c91ca503..8bb03344923de 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 f6b369b1312a5..891043ad5f82d 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 9de90ca4657d1..fd123ec57cc74 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 517bd45e45bd1..123555e4a63d8 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 0f81a5faac811..8dbec0f63c601 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 ed8ec3b6c54b9..7e4145fc723db 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 2977549803384..34c2a892d56b7 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 dc43801eb3958..c307b038627f9 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 12ad4efdbd5d1..06bda72c5fe6d 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 549490050c590..a752cd938ba0d 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 5bce884448a21..fbefce71e88a6 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 0e55ad732d714..4e2134d59e340 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 583e87370bc72..80803db657366 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 76bb6723a2ee3..72fe475c31246 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 f2beea992c67a..9158e8cdb899c 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 79198d0314f87..35c8a1abe6fc0 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 0dd6c883d5b47..9bd804f7babe8 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 69704c855ee8f..ef58a64810407 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 b0bc4c3f46793..f10818b052df1 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 2f5ef932a18e6..8e6d8523f779b 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 2f0f9bf64af4c..bc45b9e3c4a6a 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 815320be94e6a..9de812ed3856a 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 09dd091d0e716..4f3f253d5e24d 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 85dac814add57..d12d61ed46c88 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 aa349ed81860a..9662a61081037 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