rollup merge of #19288: steveklabnik/doc_style_cleanup

This is considered good convention.

This is about half of them in total, I just don't want an impossible to land patch. :smile:

4 files changed, 513 insertions, 584 deletions

diff --git a/src/libcore/finally.rs b/src/libcore/finally.rs
index 2e358e7a74b..e1e409fbaeb 100644
--- a/src/libcore/finally.rs
+++ b/src/libcore/finally.rs
@@ -58,38 +58,36 @@ impl<T> Finally<T> for fn() -> T {
     }
 }
 
-/**
- * The most general form of the `finally` functions. The function
- * `try_fn` will be invoked first; whether or not it panics, the
- * function `finally_fn` will be invoked next. The two parameters
- * `mutate` and `drop` are used to thread state through the two
- * closures. `mutate` is used for any shared, mutable state that both
- * closures require access to; `drop` is used for any state that the
- * `try_fn` requires ownership of.
- *
- * **WARNING:** While shared, mutable state between the try and finally
- * function is often necessary, one must be very careful; the `try`
- * function could have panicked at any point, so the values of the shared
- * state may be inconsistent.
- *
- * # Example
- *
- * ```
- * use std::finally::try_finally;
- *
- * struct State<'a> { buffer: &'a mut [u8], len: uint }
- * # let mut buf = [];
- * let mut state = State { buffer: &mut buf, len: 0 };
- * try_finally(
- *     &mut state, (),
- *     |state, ()| {
- *         // use state.buffer, state.len
- *     },
- *     |state| {
- *         // use state.buffer, state.len to cleanup
- *     })
- * ```
- */
+/// The most general form of the `finally` functions. The function
+/// `try_fn` will be invoked first; whether or not it panics, the
+/// function `finally_fn` will be invoked next. The two parameters
+/// `mutate` and `drop` are used to thread state through the two
+/// closures. `mutate` is used for any shared, mutable state that both
+/// closures require access to; `drop` is used for any state that the
+/// `try_fn` requires ownership of.
+///
+/// **WARNING:** While shared, mutable state between the try and finally
+/// function is often necessary, one must be very careful; the `try`
+/// function could have panicked at any point, so the values of the shared
+/// state may be inconsistent.
+///
+/// # Example
+///
+/// ```
+/// use std::finally::try_finally;
+///
+/// struct State<'a> { buffer: &'a mut [u8], len: uint }
+/// # let mut buf = [];
+/// let mut state = State { buffer: &mut buf, len: 0 };
+/// try_finally(
+///     &mut state, (),
+///     |state, ()| {
+///         // use state.buffer, state.len
+///     },
+///     |state| {
+///         // use state.buffer, state.len to cleanup
+///     })
+/// ```
 pub fn try_finally<T,U,R>(mutate: &mut T,
                           drop: U,
                           try_fn: |&mut T, U| -> R,
diff --git a/src/libcore/fmt/float.rs b/src/libcore/fmt/float.rs
index 31a46c26e2a..1e31df83779 100644
--- a/src/libcore/fmt/float.rs
+++ b/src/libcore/fmt/float.rs
@@ -54,36 +54,36 @@ pub enum SignFormat {
 
 static DIGIT_E_RADIX: uint = ('e' as uint) - ('a' as uint) + 11u;
 
-/**
- * Converts a number to its string representation as a byte vector.
- * This is meant to be a common base implementation for all numeric string
- * conversion functions like `to_string()` or `to_str_radix()`.
- *
- * # Arguments
- * - `num`           - The number to convert. Accepts any number that
- *                     implements the numeric traits.
- * - `radix`         - Base to use. Accepts only the values 2-36. If the exponential notation
- *                     is used, then this base is only used for the significand. The exponent
- *                     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. 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.
- *                    See `ExponentFormat`.
- * - `exp_capital`   - Whether or not to use a capital letter for the exponent sign, if
- *                     exponential notation is desired.
- * - `f`             - A closure to invoke with the bytes representing the
- *                     float.
- *
- * # Panics
- * - Panics if `radix` < 2 or `radix` > 36.
- * - Panics if `radix` > 14 and `exp_format` is `ExpDec` due to conflict
- *   between digit and exponent sign `'e'`.
- * - Panics if `radix` > 25 and `exp_format` is `ExpBin` due to conflict
- *   between digit and exponent sign `'p'`.
- */
+/// Converts a number to its string representation as a byte vector.
+/// This is meant to be a common base implementation for all numeric string
+/// conversion functions like `to_string()` or `to_str_radix()`.
+///
+/// # Arguments
+///
+/// - `num`           - The number to convert. Accepts any number that
+///                     implements the numeric traits.
+/// - `radix`         - Base to use. Accepts only the values 2-36. If the exponential notation
+///                     is used, then this base is only used for the significand. The exponent
+///                     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. 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.
+///                    See `ExponentFormat`.
+/// - `exp_capital`   - Whether or not to use a capital letter for the exponent sign, if
+///                     exponential notation is desired.
+/// - `f`             - A closure to invoke with the bytes representing the
+///                     float.
+///
+/// # Panics
+///
+/// - Panics if `radix` < 2 or `radix` > 36.
+/// - Panics if `radix` > 14 and `exp_format` is `ExpDec` due to conflict
+///   between digit and exponent sign `'e'`.
+/// - Panics if `radix` > 25 and `exp_format` is `ExpBin` due to conflict
+///   between digit and exponent sign `'p'`.
 pub fn float_to_str_bytes_common<T: Float, U>(
     num: T,
     radix: uint,
diff --git a/src/libcore/ops.rs b/src/libcore/ops.rs
index 185c937eb6b..b2749ca054a 100644
--- a/src/libcore/ops.rs
+++ b/src/libcore/ops.rs
@@ -57,60 +57,54 @@
 
 use kinds::Sized;
 
-/**
- *
- * The `Drop` trait is used to run some code when a value goes out of scope. This
- * is sometimes called a 'destructor'.
- *
- * # Example
- *
- * A trivial implementation of `Drop`. The `drop` method is called when `_x` goes
- * out of scope, and therefore `main` prints `Dropping!`.
- *
- * ```rust
- * struct HasDrop;
- *
- * impl Drop for HasDrop {
- *   fn drop(&mut self) {
- *       println!("Dropping!");
- *   }
- * }
- *
- * fn main() {
- *   let _x = HasDrop;
- * }
- * ```
- */
+/// The `Drop` trait is used to run some code when a value goes out of scope. This
+/// is sometimes called a 'destructor'.
+///
+/// # Example
+///
+/// A trivial implementation of `Drop`. The `drop` method is called when `_x` goes
+/// out of scope, and therefore `main` prints `Dropping!`.
+///
+/// ```rust
+/// struct HasDrop;
+///
+/// impl Drop for HasDrop {
+///   fn drop(&mut self) {
+///       println!("Dropping!");
+///   }
+/// }
+///
+/// fn main() {
+///   let _x = HasDrop;
+/// }
+/// ```
 #[lang="drop"]
 pub trait Drop {
     /// The `drop` method, called when the value goes out of scope.
     fn drop(&mut self);
 }
 
-/**
- *
- * The `Add` trait is used to specify the functionality of `+`.
- *
- * # Example
- *
- * A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up
- * calling `add`, and therefore, `main` prints `Adding!`.
- *
- * ```rust
- * struct Foo;
- *
- * impl Add<Foo, Foo> for Foo {
- *     fn add(&self, _rhs: &Foo) -> Foo {
- *       println!("Adding!");
- *       *self
- *   }
- * }
- *
- * fn main() {
- *   Foo + Foo;
- * }
- * ```
- */
+/// The `Add` trait is used to specify the functionality of `+`.
+///
+/// # Example
+///
+/// A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up
+/// calling `add`, and therefore, `main` prints `Adding!`.
+///
+/// ```rust
+/// struct Foo;
+///
+/// impl Add<Foo, Foo> for Foo {
+///     fn add(&self, _rhs: &Foo) -> Foo {
+///       println!("Adding!");
+///       *self
+///   }
+/// }
+///
+/// fn main() {
+///   Foo + Foo;
+/// }
+/// ```
 #[lang="add"]
 pub trait Add<Sized? RHS,Result> for Sized? {
     /// The method for the `+` operator
@@ -128,30 +122,27 @@ macro_rules! add_impl(
 
 add_impl!(uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64)
 
-/**
- *
- * The `Sub` trait is used to specify the functionality of `-`.
- *
- * # Example
- *
- * A trivial implementation of `Sub`. When `Foo - Foo` happens, it ends up
- * calling `sub`, and therefore, `main` prints `Subtracting!`.
- *
- * ```rust
- * struct Foo;
- *
- * impl Sub<Foo, Foo> for Foo {
- *     fn sub(&self, _rhs: &Foo) -> Foo {
- *         println!("Subtracting!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     Foo - Foo;
- * }
- * ```
- */
+/// The `Sub` trait is used to specify the functionality of `-`.
+///
+/// # Example
+///
+/// A trivial implementation of `Sub`. When `Foo - Foo` happens, it ends up
+/// calling `sub`, and therefore, `main` prints `Subtracting!`.
+///
+/// ```rust
+/// struct Foo;
+///
+/// impl Sub<Foo, Foo> for Foo {
+///     fn sub(&self, _rhs: &Foo) -> Foo {
+///         println!("Subtracting!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo - Foo;
+/// }
+/// ```
 #[lang="sub"]
 pub trait Sub<Sized? RHS, Result> for Sized? {
     /// The method for the `-` operator
@@ -169,30 +160,27 @@ macro_rules! sub_impl(
 
 sub_impl!(uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64)
 
-/**
- *
- * The `Mul` trait is used to specify the functionality of `*`.
- *
- * # Example
- *
- * A trivial implementation of `Mul`. When `Foo * Foo` happens, it ends up
- * calling `mul`, and therefore, `main` prints `Multiplying!`.
- *
- * ```rust
- * struct Foo;
- *
- * impl Mul<Foo, Foo> for Foo {
- *     fn mul(&self, _rhs: &Foo) -> Foo {
- *         println!("Multiplying!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     Foo * Foo;
- * }
- * ```
- */
+/// The `Mul` trait is used to specify the functionality of `*`.
+///
+/// # Example
+///
+/// A trivial implementation of `Mul`. When `Foo * Foo` happens, it ends up
+/// calling `mul`, and therefore, `main` prints `Multiplying!`.
+///
+/// ```rust
+/// struct Foo;
+///
+/// impl Mul<Foo, Foo> for Foo {
+///     fn mul(&self, _rhs: &Foo) -> Foo {
+///         println!("Multiplying!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo * Foo;
+/// }
+/// ```
 #[lang="mul"]
 pub trait Mul<Sized? RHS, Result>  for Sized? {
     /// The method for the `*` operator
@@ -210,30 +198,27 @@ macro_rules! mul_impl(
 
 mul_impl!(uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64)
 
-/**
- *
- * The `Div` trait is used to specify the functionality of `/`.
- *
- * # Example
- *
- * A trivial implementation of `Div`. When `Foo / Foo` happens, it ends up
- * calling `div`, and therefore, `main` prints `Dividing!`.
- *
- * ```
- * struct Foo;
- *
- * impl Div<Foo, Foo> for Foo {
- *     fn div(&self, _rhs: &Foo) -> Foo {
- *         println!("Dividing!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     Foo / Foo;
- * }
- * ```
- */
+/// The `Div` trait is used to specify the functionality of `/`.
+///
+/// # Example
+///
+/// A trivial implementation of `Div`. When `Foo / Foo` happens, it ends up
+/// calling `div`, and therefore, `main` prints `Dividing!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl Div<Foo, Foo> for Foo {
+///     fn div(&self, _rhs: &Foo) -> Foo {
+///         println!("Dividing!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo / Foo;
+/// }
+/// ```
 #[lang="div"]
 pub trait Div<Sized? RHS, Result> for Sized? {
     /// The method for the `/` operator
@@ -251,30 +236,27 @@ macro_rules! div_impl(
 
 div_impl!(uint u8 u16 u32 u64 int i8 i16 i32 i64 f32 f64)
 
-/**
- *
- * The `Rem` trait is used to specify the functionality of `%`.
- *
- * # Example
- *
- * A trivial implementation of `Rem`. When `Foo % Foo` happens, it ends up
- * calling `rem`, and therefore, `main` prints `Remainder-ing!`.
- *
- * ```
- * struct Foo;
- *
- * impl Rem<Foo, Foo> for Foo {
- *     fn rem(&self, _rhs: &Foo) -> Foo {
- *         println!("Remainder-ing!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     Foo % Foo;
- * }
- * ```
- */
+/// The `Rem` trait is used to specify the functionality of `%`.
+///
+/// # Example
+///
+/// A trivial implementation of `Rem`. When `Foo % Foo` happens, it ends up
+/// calling `rem`, and therefore, `main` prints `Remainder-ing!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl Rem<Foo, Foo> for Foo {
+///     fn rem(&self, _rhs: &Foo) -> Foo {
+///         println!("Remainder-ing!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo % Foo;
+/// }
+/// ```
 #[lang="rem"]
 pub trait Rem<Sized? RHS, Result>  for Sized? {
     /// The method for the `%` operator
@@ -306,30 +288,27 @@ rem_impl!(uint u8 u16 u32 u64 int i8 i16 i32 i64)
 rem_float_impl!(f32, fmodf)
 rem_float_impl!(f64, fmod)
 
-/**
- *
- * The `Neg` trait is used to specify the functionality of unary `-`.
- *
- * # Example
- *
- * A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
- * `neg`, and therefore, `main` prints `Negating!`.
- *
- * ```
- * struct Foo;
- *
- * impl Neg<Foo> for Foo {
- *     fn neg(&self) -> Foo {
- *         println!("Negating!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     -Foo;
- * }
- * ```
- */
+/// The `Neg` trait is used to specify the functionality of unary `-`.
+///
+/// # Example
+///
+/// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
+/// `neg`, and therefore, `main` prints `Negating!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl Neg<Foo> for Foo {
+///     fn neg(&self) -> Foo {
+///         println!("Negating!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     -Foo;
+/// }
+/// ```
 #[lang="neg"]
 pub trait Neg<Result> for Sized? {
     /// The method for the unary `-` operator
@@ -363,30 +342,27 @@ neg_uint_impl!(u32, i32)
 neg_uint_impl!(u64, i64)
 
 
-/**
- *
- * The `Not` trait is used to specify the functionality of unary `!`.
- *
- * # Example
- *
- * A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
- * `not`, and therefore, `main` prints `Not-ing!`.
- *
- * ```
- * struct Foo;
- *
- * impl Not<Foo> for Foo {
- *     fn not(&self) -> Foo {
- *         println!("Not-ing!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     !Foo;
- * }
- * ```
- */
+/// The `Not` trait is used to specify the functionality of unary `!`.
+///
+/// # Example
+///
+/// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
+/// `not`, and therefore, `main` prints `Not-ing!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl Not<Foo> for Foo {
+///     fn not(&self) -> Foo {
+///         println!("Not-ing!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     !Foo;
+/// }
+/// ```
 #[lang="not"]
 pub trait Not<Result> for Sized? {
     /// The method for the unary `!` operator
@@ -405,30 +381,27 @@ macro_rules! not_impl(
 
 not_impl!(bool uint u8 u16 u32 u64 int i8 i16 i32 i64)
 
-/**
- *
- * The `BitAnd` trait is used to specify the functionality of `&`.
- *
- * # Example
- *
- * A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
- * calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
- *
- * ```
- * struct Foo;
- *
- * impl BitAnd<Foo, Foo> for Foo {
- *     fn bitand(&self, _rhs: &Foo) -> Foo {
- *         println!("Bitwise And-ing!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     Foo & Foo;
- * }
- * ```
- */
+/// The `BitAnd` trait is used to specify the functionality of `&`.
+///
+/// # Example
+///
+/// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
+/// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl BitAnd<Foo, Foo> for Foo {
+///     fn bitand(&self, _rhs: &Foo) -> Foo {
+///         println!("Bitwise And-ing!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo & Foo;
+/// }
+/// ```
 #[lang="bitand"]
 pub trait BitAnd<Sized? RHS, Result> for Sized? {
     /// The method for the `&` operator
@@ -446,30 +419,27 @@ macro_rules! bitand_impl(
 
 bitand_impl!(bool uint u8 u16 u32 u64 int i8 i16 i32 i64)
 
-/**
- *
- * The `BitOr` trait is used to specify the functionality of `|`.
- *
- * # Example
- *
- * A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
- * calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
- *
- * ```
- * struct Foo;
- *
- * impl BitOr<Foo, Foo> for Foo {
- *     fn bitor(&self, _rhs: &Foo) -> Foo {
- *         println!("Bitwise Or-ing!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     Foo | Foo;
- * }
- * ```
- */
+/// The `BitOr` trait is used to specify the functionality of `|`.
+///
+/// # Example
+///
+/// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
+/// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl BitOr<Foo, Foo> for Foo {
+///     fn bitor(&self, _rhs: &Foo) -> Foo {
+///         println!("Bitwise Or-ing!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo | Foo;
+/// }
+/// ```
 #[lang="bitor"]
 pub trait BitOr<Sized? RHS, Result> for Sized? {
     /// The method for the `|` operator
@@ -487,30 +457,27 @@ macro_rules! bitor_impl(
 
 bitor_impl!(bool uint u8 u16 u32 u64 int i8 i16 i32 i64)
 
-/**
- *
- * The `BitXor` trait is used to specify the functionality of `^`.
- *
- * # Example
- *
- * A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
- * calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
- *
- * ```
- * struct Foo;
- *
- * impl BitXor<Foo, Foo> for Foo {
- *     fn bitxor(&self, _rhs: &Foo) -> Foo {
- *         println!("Bitwise Xor-ing!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     Foo ^ Foo;
- * }
- * ```
- */
+/// The `BitXor` trait is used to specify the functionality of `^`.
+///
+/// # Example
+///
+/// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
+/// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl BitXor<Foo, Foo> for Foo {
+///     fn bitxor(&self, _rhs: &Foo) -> Foo {
+///         println!("Bitwise Xor-ing!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo ^ Foo;
+/// }
+/// ```
 #[lang="bitxor"]
 pub trait BitXor<Sized? RHS, Result> for Sized? {
     /// The method for the `^` operator
@@ -528,30 +495,27 @@ macro_rules! bitxor_impl(
 
 bitxor_impl!(bool uint u8 u16 u32 u64 int i8 i16 i32 i64)
 
-/**
- *
- * The `Shl` trait is used to specify the functionality of `<<`.
- *
- * # Example
- *
- * A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
- * calling `shl`, and therefore, `main` prints `Shifting left!`.
- *
- * ```
- * struct Foo;
- *
- * impl Shl<Foo, Foo> for Foo {
- *     fn shl(&self, _rhs: &Foo) -> Foo {
- *         println!("Shifting left!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     Foo << Foo;
- * }
- * ```
- */
+/// The `Shl` trait is used to specify the functionality of `<<`.
+///
+/// # Example
+///
+/// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
+/// calling `shl`, and therefore, `main` prints `Shifting left!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl Shl<Foo, Foo> for Foo {
+///     fn shl(&self, _rhs: &Foo) -> Foo {
+///         println!("Shifting left!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo << Foo;
+/// }
+/// ```
 #[lang="shl"]
 pub trait Shl<Sized? RHS, Result> for Sized? {
     /// The method for the `<<` operator
@@ -571,30 +535,27 @@ macro_rules! shl_impl(
 
 shl_impl!(uint u8 u16 u32 u64 int i8 i16 i32 i64)
 
-/**
- *
- * The `Shr` trait is used to specify the functionality of `>>`.
- *
- * # Example
- *
- * A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
- * calling `shr`, and therefore, `main` prints `Shifting right!`.
- *
- * ```
- * struct Foo;
- *
- * impl Shr<Foo, Foo> for Foo {
- *     fn shr(&self, _rhs: &Foo) -> Foo {
- *         println!("Shifting right!");
- *         *self
- *     }
- * }
- *
- * fn main() {
- *     Foo >> Foo;
- * }
- * ```
- */
+/// The `Shr` trait is used to specify the functionality of `>>`.
+///
+/// # Example
+///
+/// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
+/// calling `shr`, and therefore, `main` prints `Shifting right!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl Shr<Foo, Foo> for Foo {
+///     fn shr(&self, _rhs: &Foo) -> Foo {
+///         println!("Shifting right!");
+///         *self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo >> Foo;
+/// }
+/// ```
 #[lang="shr"]
 pub trait Shr<Sized? RHS, Result> for Sized? {
     /// The method for the `>>` operator
@@ -612,105 +573,96 @@ macro_rules! shr_impl(
 
 shr_impl!(uint u8 u16 u32 u64 int i8 i16 i32 i64)
 
-/**
- *
- * The `Index` trait is used to specify the functionality of indexing operations
- * like `arr[idx]` when used in an immutable context.
- *
- * # Example
- *
- * A trivial implementation of `Index`. When `Foo[Foo]` happens, it ends up
- * calling `index`, and therefore, `main` prints `Indexing!`.
- *
- * ```
- * struct Foo;
- *
- * impl Index<Foo, Foo> for Foo {
- *     fn index<'a>(&'a self, _index: &Foo) -> &'a Foo {
- *         println!("Indexing!");
- *         self
- *     }
- * }
- *
- * fn main() {
- *     Foo[Foo];
- * }
- * ```
- */
+/// The `Index` trait is used to specify the functionality of indexing operations
+/// like `arr[idx]` when used in an immutable context.
+///
+/// # Example
+///
+/// A trivial implementation of `Index`. When `Foo[Foo]` happens, it ends up
+/// calling `index`, and therefore, `main` prints `Indexing!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl Index<Foo, Foo> for Foo {
+///     fn index<'a>(&'a self, _index: &Foo) -> &'a Foo {
+///         println!("Indexing!");
+///         self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo[Foo];
+/// }
+/// ```
 #[lang="index"]
 pub trait Index<Sized? Index, Sized? Result> for Sized? {
     /// The method for the indexing (`Foo[Bar]`) operation
     fn index<'a>(&'a self, index: &Index) -> &'a Result;
 }
 
-/**
- *
- * The `IndexMut` trait is used to specify the functionality of indexing
- * operations like `arr[idx]`, when used in a mutable context.
- *
- * # Example
- *
- * A trivial implementation of `IndexMut`. When `Foo[Foo]` happens, it ends up
- * calling `index_mut`, and therefore, `main` prints `Indexing!`.
- *
- * ```
- * struct Foo;
- *
- * impl IndexMut<Foo, Foo> for Foo {
- *     fn index_mut<'a>(&'a mut self, _index: &Foo) -> &'a mut Foo {
- *         println!("Indexing!");
- *         self
- *     }
- * }
- *
- * fn main() {
- *     &mut Foo[Foo];
- * }
- * ```
- */
+/// The `IndexMut` trait is used to specify the functionality of indexing
+/// operations like `arr[idx]`, when used in a mutable context.
+///
+/// # Example
+///
+/// A trivial implementation of `IndexMut`. When `Foo[Foo]` happens, it ends up
+/// calling `index_mut`, and therefore, `main` prints `Indexing!`.
+///
+/// ```
+/// struct Foo;
+///
+/// impl IndexMut<Foo, Foo> for Foo {
+///     fn index_mut<'a>(&'a mut self, _index: &Foo) -> &'a mut Foo {
+///         println!("Indexing!");
+///         self
+///     }
+/// }
+///
+/// fn main() {
+///     &mut Foo[Foo];
+/// }
+/// ```
 #[lang="index_mut"]
 pub trait IndexMut<Sized? Index, Sized? Result> for Sized? {
     /// The method for the indexing (`Foo[Bar]`) operation
     fn index_mut<'a>(&'a mut self, index: &Index) -> &'a mut Result;
 }
 
-/**
- *
- * The `Slice` trait is used to specify the functionality of slicing operations
- * like `arr[from..to]` when used in an immutable context.
- *
- * # Example
- *
- * A trivial implementation of `Slice`. When `Foo[..Foo]` happens, it ends up
- * calling `slice_to`, and therefore, `main` prints `Slicing!`.
- *
- * ```ignore
- * struct Foo;
- *
- * impl Slice<Foo, Foo> for Foo {
- *     fn as_slice_<'a>(&'a self) -> &'a Foo {
- *         println!("Slicing!");
- *         self
- *     }
- *     fn slice_from_or_fail<'a>(&'a self, _from: &Foo) -> &'a Foo {
- *         println!("Slicing!");
- *         self
- *     }
- *     fn slice_to_or_fail<'a>(&'a self, _to: &Foo) -> &'a Foo {
- *         println!("Slicing!");
- *         self
- *     }
- *     fn slice_or_fail<'a>(&'a self, _from: &Foo, _to: &Foo) -> &'a Foo {
- *         println!("Slicing!");
- *         self
- *     }
- * }
- *
- * fn main() {
- *     Foo[..Foo];
- * }
- * ```
- */
+/// The `Slice` trait is used to specify the functionality of slicing operations
+/// like `arr[from..to]` when used in an immutable context.
+///
+/// # Example
+///
+/// A trivial implementation of `Slice`. When `Foo[..Foo]` happens, it ends up
+/// calling `slice_to`, and therefore, `main` prints `Slicing!`.
+///
+/// ```ignore
+/// struct Foo;
+///
+/// impl Slice<Foo, Foo> for Foo {
+///     fn as_slice_<'a>(&'a self) -> &'a Foo {
+///         println!("Slicing!");
+///         self
+///     }
+///     fn slice_from_or_fail<'a>(&'a self, _from: &Foo) -> &'a Foo {
+///         println!("Slicing!");
+///         self
+///     }
+///     fn slice_to_or_fail<'a>(&'a self, _to: &Foo) -> &'a Foo {
+///         println!("Slicing!");
+///         self
+///     }
+///     fn slice_or_fail<'a>(&'a self, _from: &Foo, _to: &Foo) -> &'a Foo {
+///         println!("Slicing!");
+///         self
+///     }
+/// }
+///
+/// fn main() {
+///     Foo[..Foo];
+/// }
+/// ```
 #[lang="slice"]
 pub trait Slice<Sized? Idx, Sized? Result> for Sized? {
     /// The method for the slicing operation foo[]
@@ -723,43 +675,40 @@ pub trait Slice<Sized? Idx, Sized? Result> for Sized? {
     fn slice_or_fail<'a>(&'a self, from: &Idx, to: &Idx) -> &'a Result;
 }
 
-/**
- *
- * The `SliceMut` trait is used to specify the functionality of slicing
- * operations like `arr[from..to]`, when used in a mutable context.
- *
- * # Example
- *
- * A trivial implementation of `SliceMut`. When `Foo[Foo..]` happens, it ends up
- * calling `slice_from_mut`, and therefore, `main` prints `Slicing!`.
- *
- * ```ignore
- * struct Foo;
- *
- * impl SliceMut<Foo, Foo> for Foo {
- *     fn as_mut_slice_<'a>(&'a mut self) -> &'a mut Foo {
- *         println!("Slicing!");
- *         self
- *     }
- *     fn slice_from_or_fail_mut<'a>(&'a mut self, _from: &Foo) -> &'a mut Foo {
- *         println!("Slicing!");
- *         self
- *     }
- *     fn slice_to_or_fail_mut<'a>(&'a mut self, _to: &Foo) -> &'a mut Foo {
- *         println!("Slicing!");
- *         self
- *     }
- *     fn slice_or_fail_mut<'a>(&'a mut self, _from: &Foo, _to: &Foo) -> &'a mut Foo {
- *         println!("Slicing!");
- *         self
- *     }
- * }
- *
- * pub fn main() {
- *     Foo[mut Foo..];
- * }
- * ```
- */
+/// The `SliceMut` trait is used to specify the functionality of slicing
+/// operations like `arr[from..to]`, when used in a mutable context.
+///
+/// # Example
+///
+/// A trivial implementation of `SliceMut`. When `Foo[Foo..]` happens, it ends up
+/// calling `slice_from_mut`, and therefore, `main` prints `Slicing!`.
+///
+/// ```ignore
+/// struct Foo;
+///
+/// impl SliceMut<Foo, Foo> for Foo {
+///     fn as_mut_slice_<'a>(&'a mut self) -> &'a mut Foo {
+///         println!("Slicing!");
+///         self
+///     }
+///     fn slice_from_or_fail_mut<'a>(&'a mut self, _from: &Foo) -> &'a mut Foo {
+///         println!("Slicing!");
+///         self
+///     }
+///     fn slice_to_or_fail_mut<'a>(&'a mut self, _to: &Foo) -> &'a mut Foo {
+///         println!("Slicing!");
+///         self
+///     }
+///     fn slice_or_fail_mut<'a>(&'a mut self, _from: &Foo, _to: &Foo) -> &'a mut Foo {
+///         println!("Slicing!");
+///         self
+///     }
+/// }
+///
+/// pub fn main() {
+///     Foo[mut Foo..];
+/// }
+/// ```
 #[lang="slice_mut"]
 pub trait SliceMut<Sized? Idx, Sized? Result> for Sized? {
     /// The method for the slicing operation foo[]
@@ -772,33 +721,30 @@ pub trait SliceMut<Sized? Idx, Sized? Result> for Sized? {
     fn slice_or_fail_mut<'a>(&'a mut self, from: &Idx, to: &Idx) -> &'a mut Result;
 }
 
-/**
- *
- * The `Deref` trait is used to specify the functionality of dereferencing
- * operations like `*v`.
- *
- * # Example
- *
- * A struct with a single field which is accessible via dereferencing the
- * struct.
- *
- * ```
- * struct DerefExample<T> {
- *     value: T
- * }
- *
- * impl<T> Deref<T> for DerefExample<T> {
- *     fn deref<'a>(&'a self) -> &'a T {
- *         &self.value
- *     }
- * }
- *
- * fn main() {
- *     let x = DerefExample { value: 'a' };
- *     assert_eq!('a', *x);
- * }
- * ```
- */
+/// The `Deref` trait is used to specify the functionality of dereferencing
+/// operations like `*v`.
+///
+/// # Example
+///
+/// A struct with a single field which is accessible via dereferencing the
+/// struct.
+///
+/// ```
+/// struct DerefExample<T> {
+///     value: T
+/// }
+///
+/// impl<T> Deref<T> for DerefExample<T> {
+///     fn deref<'a>(&'a self) -> &'a T {
+///         &self.value
+///     }
+/// }
+///
+/// fn main() {
+///     let x = DerefExample { value: 'a' };
+///     assert_eq!('a', *x);
+/// }
+/// ```
 #[lang="deref"]
 pub trait Deref<Sized? Result> for Sized? {
     /// The method called to dereference a value
@@ -813,40 +759,37 @@ impl<'a, Sized? T> Deref<T> for &'a mut T {
     fn deref(&self) -> &T { *self }
 }
 
-/**
- *
- * The `DerefMut` trait is used to specify the functionality of dereferencing
- * mutably like `*v = 1;`
- *
- * # Example
- *
- * A struct with a single field which is modifiable via dereferencing the
- * struct.
- *
- * ```
- * struct DerefMutExample<T> {
- *     value: T
- * }
- *
- * impl<T> Deref<T> for DerefMutExample<T> {
- *     fn deref<'a>(&'a self) -> &'a T {
- *         &self.value
- *     }
- * }
- *
- * impl<T> DerefMut<T> for DerefMutExample<T> {
- *     fn deref_mut<'a>(&'a mut self) -> &'a mut T {
- *         &mut self.value
- *     }
- * }
- *
- * fn main() {
- *     let mut x = DerefMutExample { value: 'a' };
- *     *x = 'b';
- *     assert_eq!('b', *x);
- * }
- * ```
- */
+/// The `DerefMut` trait is used to specify the functionality of dereferencing
+/// mutably like `*v = 1;`
+///
+/// # Example
+///
+/// A struct with a single field which is modifiable via dereferencing the
+/// struct.
+///
+/// ```
+/// struct DerefMutExample<T> {
+///     value: T
+/// }
+///
+/// impl<T> Deref<T> for DerefMutExample<T> {
+///     fn deref<'a>(&'a self) -> &'a T {
+///         &self.value
+///     }
+/// }
+///
+/// impl<T> DerefMut<T> for DerefMutExample<T> {
+///     fn deref_mut<'a>(&'a mut self) -> &'a mut T {
+///         &mut self.value
+///     }
+/// }
+///
+/// fn main() {
+///     let mut x = DerefMutExample { value: 'a' };
+///     *x = 'b';
+///     assert_eq!('b', *x);
+/// }
+/// ```
 #[lang="deref_mut"]
 pub trait DerefMut<Sized? Result>: Deref<Result> {
     /// The method called to mutably dereference a value
diff --git a/src/libcore/slice.rs b/src/libcore/slice.rs
index 35fbde5838c..950f04a5d97 100644
--- a/src/libcore/slice.rs
+++ b/src/libcore/slice.rs
@@ -1632,9 +1632,7 @@ impl BinarySearchResult {
 // Free functions
 //
 
-/**
- * Converts a pointer to A into a slice of length 1 (without copying).
- */
+/// Converts a pointer to A into a slice of length 1 (without copying).
 #[unstable = "waiting for DST"]
 pub fn ref_slice<'a, A>(s: &'a A) -> &'a [A] {
     unsafe {
@@ -1642,9 +1640,7 @@ pub fn ref_slice<'a, A>(s: &'a A) -> &'a [A] {
     }
 }
 
-/**
- * Converts a pointer to A into a slice of length 1 (without copying).
- */
+/// Converts a pointer to A into a slice of length 1 (without copying).
 #[unstable = "waiting for DST"]
 pub fn mut_ref_slice<'a, A>(s: &'a mut A) -> &'a mut [A] {
     unsafe {
@@ -1708,10 +1704,8 @@ pub mod raw {
     use raw::Slice;
     use option::{None, Option, Some};
 
-    /**
-     * Form a slice from a pointer and length (as a number of units,
-     * not bytes).
-     */
+    /// Form a slice from a pointer and length (as a number of units,
+    /// not bytes).
     #[inline]
     #[deprecated = "renamed to slice::from_raw_buf"]
     pub unsafe fn buf_as_slice<T,U>(p: *const T, len: uint, f: |v: &[T]| -> U)
@@ -1722,10 +1716,8 @@ pub mod raw {
         }))
     }
 
-    /**
-     * Form a slice from a pointer and length (as a number of units,
-     * not bytes).
-     */
+    /// Form a slice from a pointer and length (as a number of units,
+    /// not bytes).
     #[inline]
     #[deprecated = "renamed to slice::from_raw_mut_buf"]
     pub unsafe fn mut_buf_as_slice<T,
@@ -1740,12 +1732,10 @@ pub mod raw {
         }))
     }
 
-    /**
-     * Returns a pointer to first element in slice and adjusts
-     * slice so it no longer contains that element. Returns None
-     * if the slice is empty. O(1).
-     */
-     #[inline]
+    /// Returns a pointer to first element in slice and adjusts
+    /// slice so it no longer contains that element. Returns None
+    /// if the slice is empty. O(1).
+    #[inline]
     #[deprecated = "inspect `Slice::{data, len}` manually (increment data by 1)"]
     pub unsafe fn shift_ptr<T>(slice: &mut Slice<T>) -> Option<*const T> {
         if slice.len == 0 { return None; }
@@ -1755,11 +1745,9 @@ pub mod raw {
         Some(head)
     }
 
-    /**
-     * Returns a pointer to last element in slice and adjusts
-     * slice so it no longer contains that element. Returns None
-     * if the slice is empty. O(1).
-     */
+    /// Returns a pointer to last element in slice and adjusts
+    /// slice so it no longer contains that element. Returns None
+    /// if the slice is empty. O(1).
     #[inline]
     #[deprecated = "inspect `Slice::{data, len}` manually (decrement len by 1)"]
     pub unsafe fn pop_ptr<T>(slice: &mut Slice<T>) -> Option<*const T> {