Convert various inner doc-comments to outer doc-comments

Author: brendanzab

src/libcore/cmp.rs

@@ -127,12 +127,11 @@ totalord_impl!(uint)
 
 totalord_impl!(char)
 
+/// Compares (a1, b1) against (a2, b2), where the a values are more significant.
 pub fn cmp2<A:TotalOrd,B:TotalOrd>(
     a1: &A, b1: &B,
     a2: &A, b2: &B) -> Ordering
 {
-    //! Compares (a1, b1) against (a2, b2), where the a values are more significant.
-
     match a1.cmp(a2) {
         Less => Less,
         Greater => Greater,

src/libcore/either.rs

@@ -26,26 +26,22 @@ pub enum Either<T, U> {
     Right(U)
 }
 
+/// Applies a function based on the given either value
+///
+/// If `value` is left(T) then `f_left` is applied to its contents, if
+/// `value` is right(U) then `f_right` is applied to its contents, and the
+/// result is returned.
 #[inline(always)]
 pub fn either<T, U, V>(f_left: &fn(&T) -> V,
                        f_right: &fn(&U) -> V, value: &Either<T, U>) -> V {
-    /*!
-     * Applies a function based on the given either value
-     *
-     * If `value` is left(T) then `f_left` is applied to its contents, if
-     * `value` is right(U) then `f_right` is applied to its contents, and the
-     * result is returned.
-     */
-
     match *value {
       Left(ref l) => f_left(l),
       Right(ref r) => f_right(r)
     }
 }
 
+/// Extracts from a vector of either all the left values
 pub fn lefts<T:Copy,U>(eithers: &[Either<T, U>]) -> ~[T] {
-    //! Extracts from a vector of either all the left values
-
     do vec::build_sized(eithers.len()) |push| {
         for eithers.each |elt| {
             match *elt {
@@ -56,9 +52,8 @@ pub fn lefts<T:Copy,U>(eithers: &[Either<T, U>]) -> ~[T] {
     }
 }
 
+/// Extracts from a vector of either all the right values
 pub fn rights<T, U: Copy>(eithers: &[Either<T, U>]) -> ~[U] {
-    //! Extracts from a vector of either all the right values
-
     do vec::build_sized(eithers.len()) |push| {
         for eithers.each |elt| {
             match *elt {
@@ -69,15 +64,11 @@ pub fn rights<T, U: Copy>(eithers: &[Either<T, U>]) -> ~[U] {
     }
 }
 
-pub fn partition<T, U>(eithers: ~[Either<T, U>])
-    -> (~[T], ~[U]) {
-    /*!
-     * Extracts from a vector of either all the left values and right values
-     *
-     * Returns a structure containing a vector of left values and a vector of
-     * right values.
-     */
-
+/// Extracts from a vector of either all the left values and right values
+///
+/// Returns a structure containing a vector of left values and a vector of
+/// right values.
+pub fn partition<T, U>(eithers: ~[Either<T, U>]) -> (~[T], ~[U]) {
     let mut lefts: ~[T] = ~[];
     let mut rights: ~[U] = ~[];
     do vec::consume(eithers) |_i, elt| {
@@ -89,60 +80,51 @@ pub fn partition<T, U>(eithers: ~[Either<T, U>])
     return (lefts, rights);
 }
 
+/// Flips between left and right of a given either
 #[inline(always)]
 pub fn flip<T, U>(eith: Either<T, U>) -> Either<U, T> {
-    //! Flips between left and right of a given either
-
     match eith {
       Right(r) => Left(r),
       Left(l) => Right(l)
     }
 }
 
+/// Converts either::t to a result::t
+///
+/// Converts an `either` type to a `result` type, making the "right" choice
+/// an ok result, and the "left" choice a fail
 #[inline(always)]
-pub fn to_result<T, U>(eith: Either<T, U>)
-    -> Result<U, T> {
-    /*!
-     * Converts either::t to a result::t
-     *
-     * Converts an `either` type to a `result` type, making the "right" choice
-     * an ok result, and the "left" choice a fail
-     */
-
+pub fn to_result<T, U>(eith: Either<T, U>) -> Result<U, T> {
     match eith {
       Right(r) => result::Ok(r),
       Left(l) => result::Err(l)
     }
 }
 
+/// Checks whether the given value is a left
 #[inline(always)]
 pub fn is_left<T, U>(eith: &Either<T, U>) -> bool {
-    //! Checks whether the given value is a left
-
     match *eith { Left(_) => true, _ => false }
 }
 
+/// Checks whether the given value is a right
 #[inline(always)]
 pub fn is_right<T, U>(eith: &Either<T, U>) -> bool {
-    //! Checks whether the given value is a right
-
     match *eith { Right(_) => true, _ => false }
 }
 
+/// Retrieves the value in the left branch. Fails if the either is Right.
 #[inline(always)]
 pub fn unwrap_left<T,U>(eith: Either<T,U>) -> T {
-    //! Retrieves the value in the left branch. Fails if the either is Right.
-
     match eith {
         Left(x) => x,
         Right(_) => fail!("either::unwrap_left Right")
     }
 }
 
+/// Retrieves the value in the right branch. Fails if the either is Left.
 #[inline(always)]
 pub fn unwrap_right<T,U>(eith: Either<T,U>) -> U {
-    //! Retrieves the value in the right branch. Fails if the either is Left.
-
     match eith {
         Right(x) => x,
         Left(_) => fail!("either::unwrap_right Left")

src/libcore/managed.rs

@@ -35,16 +35,16 @@ pub mod raw {
 
 }
 
+/// Determine if two shared boxes point to the same object
 #[inline(always)]
 pub fn ptr_eq<T>(a: @T, b: @T) -> bool {
-    //! Determine if two shared boxes point to the same object
     let a_ptr: *T = to_unsafe_ptr(&*a), b_ptr: *T = to_unsafe_ptr(&*b);
     a_ptr == b_ptr
 }
 
+/// Determine if two mutable shared boxes point to the same object
 #[inline(always)]
 pub fn mut_ptr_eq<T>(a: @mut T, b: @mut T) -> bool {
-    //! Determine if two mutable shared boxes point to the same object
     let a_ptr: *T = to_unsafe_ptr(&*a), b_ptr: *T = to_unsafe_ptr(&*b);
     a_ptr == b_ptr
 }

src/libcore/option.rs

@@ -182,34 +182,28 @@ pub impl<T> Option<T> {
     #[inline(always)]
     fn is_some(&const self) -> bool { !self.is_none() }
 
+    /// Update an optional value by optionally running its content through a
+    /// function that returns an option.
     #[inline(always)]
     fn chain<U>(self, f: &fn(t: T) -> Option<U>) -> Option<U> {
-        /*!
-         * Update an optional value by optionally running its content through a
-         * function that returns an option.
-         */
 
         match self {
             Some(t) => f(t),
             None => None
         }
     }
 
+    /// Returns the leftmost Some() value, or None if both are None.
     #[inline(always)]
     fn or(self, optb: Option<T>) -> Option<T> {
-        /*!
-         * Returns the leftmost Some() value, or None if both are None.
-         */
         match self {
             Some(opta) => Some(opta),
             _ => optb
         }
     }
 
-    /**
-     * Update an optional value by optionally running its content by reference
-     * through a function that returns an option.
-     */
+    /// Update an optional value by optionally running its content by reference
+    /// through a function that returns an option.
     #[inline(always)]
     fn chain_ref<'a, U>(&'a self, f: &fn(x: &'a T) -> Option<U>) -> Option<U> {
         match *self { Some(ref x) => f(x), None => None }