libstd: Document the following modules:

* native::io
* std::char
* std::fmt
* std::fmt::parse
* std::io
* std::io::extensions
* std::io::net::ip
* std::io::net::udp
* std::io::net::unix
* std::io::pipe
* std::num
* std::num::f32
* std::num::f64
* std::num::strconv
* std::os

4 files changed, 183 insertions, 46 deletions

diff --git a/src/libstd/num/f32.rs b/src/libstd/num/f32.rs
index 3ba3a9a134f..323f24a52c3 100644
--- a/src/libstd/num/f32.rs
+++ b/src/libstd/num/f32.rs
@@ -116,7 +116,7 @@ pub static NAN: f32 = 0.0_f32/0.0_f32;
 pub static INFINITY: f32 = 1.0_f32/0.0_f32;
 pub static NEG_INFINITY: f32 = -1.0_f32/0.0_f32;
 
-/* Module: consts */
+/// Various useful constants.
 pub mod consts {
     // FIXME (requires Issue #1433 to fix): replace with mathematical
     // staticants from cmath.
diff --git a/src/libstd/num/f64.rs b/src/libstd/num/f64.rs
index b95188b0765..fc8c5f47073 100644
--- a/src/libstd/num/f64.rs
+++ b/src/libstd/num/f64.rs
@@ -120,7 +120,7 @@ pub static NEG_INFINITY: f64 = -1.0_f64/0.0_f64;
 
 // FIXME (#1999): add is_normal, is_subnormal, and fpclassify
 
-/* Module: consts */
+/// Various useful constants.
 pub mod consts {
     // FIXME (requires Issue #1433 to fix): replace with mathematical
     // constants from cmath.
diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs
index 98379b5e5fb..31124db49b9 100644
--- a/src/libstd/num/mod.rs
+++ b/src/libstd/num/mod.rs
@@ -96,25 +96,56 @@ pub trait One: Mul<Self, Self> {
 /// Returns the multiplicative identity, `1`.
 #[inline(always)] pub fn one<T: One>() -> T { One::one() }
 
-pub trait Signed: Num
-                + Neg<Self> {
+/// Useful functions for signed numbers (i.e. numbers that can be negative).
+pub trait Signed: Num + Neg<Self> {
+    /// Computes the absolute value.
+    ///
+    /// For float, f32, and f64, `NaN` will be returned if the number is `NaN`.
     fn abs(&self) -> Self;
+
+    /// The positive difference of two numbers.
+    ///
+    /// Returns `zero` if the number is less than or equal to `other`, otherwise the difference
+    /// between `self` and `other` is returned.
     fn abs_sub(&self, other: &Self) -> Self;
+
+    /// Returns the sign of the number.
+    ///
+    /// For `float`, `f32`, `f64`:
+    ///   * `1.0` if the number is positive, `+0.0` or `INFINITY`
+    ///   * `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY`
+    ///   * `NaN` if the number is `NaN`
+    ///
+    /// For `int`:
+    ///   * `0` if the number is zero
+    ///   * `1` if the number is positive
+    ///   * `-1` if the number is negative
     fn signum(&self) -> Self;
 
+    /// Returns true if the number is positive and false if the number is zero or negative.
     fn is_positive(&self) -> bool;
+
+    /// Returns true if the number is negative and false if the number is zero or positive.
     fn is_negative(&self) -> bool;
 }
 
 /// Computes the absolute value.
 ///
 /// For float, f32, and f64, `NaN` will be returned if the number is `NaN`
-#[inline(always)] pub fn abs<T: Signed>(value: T) -> T { value.abs() }
+#[inline(always)]
+pub fn abs<T: Signed>(value: T) -> T {
+    value.abs()
+}
+
 /// The positive difference of two numbers.
 ///
 /// Returns `zero` if the number is less than or equal to `other`,
 /// otherwise the difference between `self` and `other` is returned.
-#[inline(always)] pub fn abs_sub<T: Signed>(x: T, y: T) -> T { x.abs_sub(&y) }
+#[inline(always)]
+pub fn abs_sub<T: Signed>(x: T, y: T) -> T {
+    x.abs_sub(&y)
+}
+
 /// Returns the sign of the number.
 ///
 /// For float, f32, f64:
@@ -308,70 +339,150 @@ pub enum FPCategory {
     FPNormal,
 }
 
-/// Primitive floating point numbers
-pub trait Float: Signed
-               + Round
-               + Primitive {
+/// Operations on primitive floating point numbers.
+///
+/// TODO(#5527): In a future version of Rust, many of these functions will become constants.
+///
+/// FIXME(#8888): Several of these functions have a parameter named `unused_self`. Removing it
+/// requires #8888 to be fixed.
+pub trait Float: Signed + Round + Primitive {
+    /// Returns the maximum of the two numbers.
     fn max(self, other: Self) -> Self;
+    /// Returns the minimum of the two numbers.
     fn min(self, other: Self) -> Self;
 
-    // FIXME (#5527): These should be associated constants
+    /// Returns the NaN value.
     fn nan() -> Self;
+
+    /// Returns the infinite value.
     fn infinity() -> Self;
+
+    /// Returns the negative infinite value.
     fn neg_infinity() -> Self;
+
+    /// Returns -0.0.
     fn neg_zero() -> Self;
 
+    /// Returns true if this value is NaN and false otherwise.
     fn is_nan(&self) -> bool;
+
+    /// Returns true if this value is positive infinity or negative infinity and false otherwise.
     fn is_infinite(&self) -> bool;
+
+    /// Returns true if this number is neither infinite nor NaN.
     fn is_finite(&self) -> bool;
+
+    /// Returns true if this number is neither zero, infinite, denormal, or NaN.
     fn is_normal(&self) -> bool;
+
+    /// Returns the category that this number falls into.
     fn classify(&self) -> FPCategory;
 
-    // FIXME (#8888): Removing `unused_self` requires #8888 to be fixed.
+    /// Returns the number of binary digits of mantissa that this type supports.
     fn mantissa_digits(unused_self: Option<Self>) -> uint;
+
+    /// Returns the number of binary digits of exponent that this type supports.
     fn digits(unused_self: Option<Self>) -> uint;
+
+    /// Returns the smallest positive number that this type can represent.
     fn epsilon() -> Self;
+
+    /// Returns the minimum binary exponent that this type can represent.
     fn min_exp(unused_self: Option<Self>) -> int;
+
+    /// Returns the maximum binary exponent that this type can represent.
     fn max_exp(unused_self: Option<Self>) -> int;
+
+    /// Returns the minimum base-10 exponent that this type can represent.
     fn min_10_exp(unused_self: Option<Self>) -> int;
+
+    /// Returns the maximum base-10 exponent that this type can represent.
     fn max_10_exp(unused_self: Option<Self>) -> int;
 
+    /// Constructs a floating point number created by multiplying `x` by 2 raised to the power of
+    /// `exp`.
     fn ldexp(x: Self, exp: int) -> Self;
+
+    /// Breaks the number into a normalized fraction and a base-2 exponent, satisfying:
+    ///
+    ///  * `self = x * pow(2, exp)`
+    ///
+    ///  * `0.5 <= abs(x) < 1.0`
     fn frexp(&self) -> (Self, int);
 
+    /// Returns the exponential of the number, minus 1, in a way that is accurate even if the
+    /// number is close to zero.
     fn exp_m1(&self) -> Self;
+
+    /// Returns the natural logarithm of the number plus 1 (`ln(1+n)`) more accurately than if the
+    /// operations were performed separately.
     fn ln_1p(&self) -> Self;
+
+    /// Fused multiply-add. Computes `(self * a) + b` with only one rounding error. This produces a
+    /// more accurate result with better performance than a separate multiplication operation
+    /// followed by an add.
     fn mul_add(&self, a: Self, b: Self) -> Self;
+
+    /// Returns the next representable floating-point value in the direction of `other`.
     fn next_after(&self, other: Self) -> Self;
 
+    /// Returns the mantissa, exponent and sign as integers, respectively.
     fn integer_decode(&self) -> (u64, i16, i8);
 
-    // Common Mathematical Constants
-    // FIXME (#5527): These should be associated constants
+    /// Archimedes' constant.
     fn pi() -> Self;
+
+    /// 2.0 * pi.
     fn two_pi() -> Self;
+
+    /// pi / 2.0.
     fn frac_pi_2() -> Self;
+
+    /// pi / 3.0.
     fn frac_pi_3() -> Self;
+
+    /// pi / 4.0.
     fn frac_pi_4() -> Self;
+
+    /// pi / 6.0.
     fn frac_pi_6() -> Self;
+
+    /// pi / 8.0.
     fn frac_pi_8() -> Self;
+
+    /// 1.0 / pi.
     fn frac_1_pi() -> Self;
+
+    /// 2.0 / pi.
     fn frac_2_pi() -> Self;
+
+    /// 2.0 / sqrt(pi).
     fn frac_2_sqrtpi() -> Self;
+
+    /// sqrt(2.0).
     fn sqrt2() -> Self;
+
+    /// 1.0 / sqrt(2.0).
     fn frac_1_sqrt2() -> Self;
+
+    /// Euler's number.
     fn e() -> Self;
+
+    /// log2(e).
     fn log2_e() -> Self;
+
+    /// log10(e).
     fn log10_e() -> Self;
+
+    /// ln(2.0).
     fn ln_2() -> Self;
-    fn ln_10() -> Self;
 
-    // Fractional functions
+    /// ln(10.0).
+    fn ln_10() -> Self;
 
     /// Take the reciprocal (inverse) of a number, `1/x`.
     fn recip(&self) -> Self;
 
-    // Algebraic functions
     /// Raise a number to a power.
     fn powf(&self, n: &Self) -> Self;
 
@@ -385,8 +496,6 @@ pub trait Float: Signed
     /// legs of length `x` and `y`.
     fn hypot(&self, other: &Self) -> Self;
 
-    // Trigonometric functions
-
     /// Computes the sine of a number (in radians).
     fn sin(&self) -> Self;
     /// Computes the cosine of a number (in radians).
@@ -412,8 +521,6 @@ pub trait Float: Signed
     /// `(sin(x), cos(x))`.
     fn sin_cos(&self) -> (Self, Self);
 
-    // Exponential functions
-
     /// Returns `e^(self)`, (the exponential function).
     fn exp(&self) -> Self;
     /// Returns 2 raised to the power of the number, `2^(self)`.
@@ -427,8 +534,6 @@ pub trait Float: Signed
     /// Returns the base 10 logarithm of the number.
     fn log10(&self) -> Self;
 
-    // Hyperbolic functions
-
     /// Hyperbolic sine function.
     fn sinh(&self) -> Self;
     /// Hyperbolic cosine function.
@@ -442,8 +547,6 @@ pub trait Float: Signed
     /// Inverse hyperbolic tangent function.
     fn atanh(&self) -> Self;
 
-    // Angular conversions
-
     /// Convert radians to degrees.
     fn to_degrees(&self) -> Self;
     /// Convert degrees to radians.
@@ -978,8 +1081,10 @@ pub fn cast<T: NumCast,U: NumCast>(n: T) -> Option<U> {
     NumCast::from(n)
 }
 
-/// An interface for casting between machine scalars
+/// An interface for casting between machine scalars.
 pub trait NumCast: ToPrimitive {
+    /// Creates a number from another value that can be converted into a primitive via the
+    /// `ToPrimitive` trait.
     fn from<T: ToPrimitive>(n: T) -> Option<Self>;
 }
 
@@ -1059,19 +1164,30 @@ impl<T: CheckedAdd + CheckedSub + Zero + Ord + Bounded> Saturating for T {
     }
 }
 
+/// Performs addition that returns `None` instead of wrapping around on overflow.
 pub trait CheckedAdd: Add<Self, Self> {
+    /// Adds two numbers, checking for overflow. If overflow happens, `None` is returned.
     fn checked_add(&self, v: &Self) -> Option<Self>;
 }
 
+/// Performs subtraction that returns `None` instead of wrapping around on underflow.
 pub trait CheckedSub: Sub<Self, Self> {
+    /// Subtracts two numbers, checking for underflow. If underflow happens, `None` is returned.
     fn checked_sub(&self, v: &Self) -> Option<Self>;
 }
 
+/// Performs multiplication that returns `None` instead of wrapping around on underflow or
+/// overflow.
 pub trait CheckedMul: Mul<Self, Self> {
+    /// Multiplies two numbers, checking for underflow or overflow. If underflow or overflow
+    /// happens, `None` is returned.
     fn checked_mul(&self, v: &Self) -> Option<Self>;
 }
 
+/// Performs division that returns `None` instead of wrapping around on underflow or overflow.
 pub trait CheckedDiv: Div<Self, Self> {
+    /// Divides two numbers, checking for underflow or overflow. If underflow or overflow happens,
+    /// `None` is returned.
     fn checked_div(&self, v: &Self) -> Option<Self>;
 }
 
diff --git a/src/libstd/num/strconv.rs b/src/libstd/num/strconv.rs
index 9d3d012bae7..9f9a9ec8e2e 100644
--- a/src/libstd/num/strconv.rs
+++ b/src/libstd/num/strconv.rs
@@ -24,31 +24,66 @@ use num;
 use num::{NumCast, Zero, One, cast, Int};
 use num::{Round, Float, FPNaN, FPInfinite, ToPrimitive};
 
+/// A flag that specifies whether to use exponential (scientific) notation.
 pub enum ExponentFormat {
+    /// Do not use exponential notation.
     ExpNone,
+    /// Use exponential notation with the exponent having a base of 10 and the
+    /// exponent sign being `e` or `E`. For example, 1000 would be printed
+    /// 1e3.
     ExpDec,
-    ExpBin
+    /// Use exponential notation with the exponent having a base of 2 and the
+    /// exponent sign being `p` or `P`. For example, 8 would be printed 1p3.
+    ExpBin,
 }
 
+/// The number of digits used for emitting the fractional part of a number, if
+/// any.
 pub enum SignificantDigits {
+    /// All calculable digits will be printed.
+    ///
+    /// Note that bignums or fractions may cause a surprisingly large number
+    /// of digits to be printed.
     DigAll,
+
+    /// At most the given number of digits will be printed, truncating any
+    /// trailing zeroes.
     DigMax(uint),
+
+    /// Precisely the given number of digits will be printed.
     DigExact(uint)
 }
 
+/// How to emit the sign of a number.
 pub enum SignFormat {
+    /// No sign will be printed. The exponent sign will also be emitted.
     SignNone,
+    /// `-` will be printed for negative values, but no sign will be emitted
+    /// for positive numbers.
     SignNeg,
-    SignAll
+    /// `+` will be printed for positive values, and `-` will be printed for
+    /// negative values.
+    SignAll,
 }
 
+/// Encompasses functions used by the string converter.
 pub trait NumStrConv {
+    /// Returns the NaN value.
     fn nan()      -> Option<Self>;
+
+    /// Returns the infinite value.
     fn inf()      -> Option<Self>;
+
+    /// Returns the negative infinite value.
     fn neg_inf()  -> Option<Self>;
+
+    /// Returns -0.0.
     fn neg_zero() -> Option<Self>;
 
+    /// Rounds the number toward zero.
     fn round_to_zero(&self)   -> Self;
+
+    /// Returns the fractional part of the number.
     fn fractional_part(&self) -> Self;
 }
 
@@ -200,25 +235,11 @@ pub fn int_to_str_bytes_common<T: Int>(num: T, radix: uint, sign: SignFormat, f:
  *                     itself always printed using a base of 10.
  * - `negative_zero` - Whether to treat the special value `-0` as
  *                     `-0` or as `+0`.
- * - `sign`          - How to emit the sign. Options are:
- *     - `SignNone`: No sign at all. The exponent sign is also omitted.
- *     - `SignNeg`:  Only `-` on negative values.
- *     - `SignAll`:  Both `+` on positive, and `-` on negative numbers.
- * - `digits`        - The amount of digits to use for emitting the
- *                     fractional part, if any. Options are:
- *     - `DigAll`:         All calculatable digits. Beware of bignums or
- *                         fractions!
- *     - `DigMax(uint)`:   Maximum N digits, truncating any trailing zeros.
- *     - `DigExact(uint)`: Exactly N digits.
+ * - `sign`          - How to emit the sign. See `SignFormat`.
+ * - `digits`        - The amount of digits to use for emitting the fractional
+ *                     part, if any. See `SignificantDigits`.
  * - `exp_format`   - Whether or not to use the exponential (scientific) notation.
- *                    Options are:
- *     - `ExpNone`: Do not use the exponential notation.
- *     - `ExpDec`:  Use the exponential notation with the exponent having a base of 10,
- *                  and exponent sign being `'e'` or `'E'` depending on the value of
- *                  the `exp_upper` argument. E.g. the number 1000 would be printed as 1e3.
- *     - `ExpBin`:  Use the exponential notation with the exponent having a base of 2,
- *                  and exponent sign being `'p'` or `'P'` depending on the value of
- *                  the `exp_upper` argument. E.g. the number 8 would be printed as 1p3.
+ *                    See `ExponentFormat`.
  * - `exp_capital`   - Whether or not to use a capital letter for the exponent sign, if
  *                     exponential notation is desired.
  *