rollup merge of rust-lang#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. 😄

Author: alexcrichton

src/libcollections/enum_set.rs

@@ -42,27 +42,25 @@ impl<E:CLike+fmt::Show> fmt::Show for EnumSet<E> {
     }
 }
 
-/**
-An interface for casting C-like enum to uint and back.
-A typically implementation is as below.
-
-```{rust,ignore}
-#[repr(uint)]
-enum Foo {
-    A, B, C
-}
-
-impl CLike for Foo {
-    fn to_uint(&self) -> uint {
-        *self as uint
-    }
-
-    fn from_uint(v: uint) -> Foo {
-        unsafe { mem::transmute(v) }
-    }
-}
-```
-*/
+/// An interface for casting C-like enum to uint and back.
+/// A typically implementation is as below.
+///
+/// ```{rust,ignore}
+/// #[repr(uint)]
+/// enum Foo {
+///     A, B, C
+/// }
+///
+/// impl CLike for Foo {
+///     fn to_uint(&self) -> uint {
+///         *self as uint
+///     }
+///
+///     fn from_uint(v: uint) -> Foo {
+///         unsafe { mem::transmute(v) }
+///     }
+/// }
+/// ```
 pub trait CLike {
     /// Converts a C-like enum to a `uint`.
     fn to_uint(&self) -> uint;

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,

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,