/** -> ///

This is considered good convention.

5 files changed, 94 insertions, 123 deletions

diff --git a/src/libstd/num/strconv.rs b/src/libstd/num/strconv.rs
index 649298d9c08..be6e387ad83 100644
--- a/src/libstd/num/strconv.rs
+++ b/src/libstd/num/strconv.rs
@@ -67,31 +67,32 @@ pub enum SignFormat {
     SignAll,
 }
 
-/**
- * Converts an integral number to its string representation as a byte vector.
- * This is meant to be a common base implementation for all integral 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.
- * - `sign`          - How to emit the sign. Options are:
- *     - `SignNone`: No sign at all. Basically emits `abs(num)`.
- *     - `SignNeg`:  Only `-` on negative values.
- *     - `SignAll`:  Both `+` on positive, and `-` on negative numbers.
- * - `f`             - a callback which will be invoked for each ascii character
- *                     which composes the string representation of this integer
- *
- * # Return value
- * A tuple containing the byte vector, and a boolean flag indicating
- * whether it represents a special value like `inf`, `-inf`, `NaN` or not.
- * It returns a tuple because there can be ambiguity between a special value
- * and a number representation at higher bases.
- *
- * # Panics
- * - Panics if `radix` < 2 or `radix` > 36.
- */
+/// Converts an integral number to its string representation as a byte vector.
+/// This is meant to be a common base implementation for all integral 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.
+/// - `sign`          - How to emit the sign. Options are:
+///     - `SignNone`: No sign at all. Basically emits `abs(num)`.
+///     - `SignNeg`:  Only `-` on negative values.
+///     - `SignAll`:  Both `+` on positive, and `-` on negative numbers.
+/// - `f`             - a callback which will be invoked for each ascii character
+///                     which composes the string representation of this integer
+///
+/// # Return value
+///
+/// A tuple containing the byte vector, and a boolean flag indicating
+/// whether it represents a special value like `inf`, `-inf`, `NaN` or not.
+/// It returns a tuple because there can be ambiguity between a special value
+/// and a number representation at higher bases.
+///
+/// # Panics
+///
+/// - Panics if `radix` < 2 or `radix` > 36.
 fn int_to_str_bytes_common<T: Int>(num: T, radix: uint, sign: SignFormat, f: |u8|) {
     assert!(2 <= radix && radix <= 36);
 
diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index 9b50361ec1f..c6554d2ed58 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -788,18 +788,16 @@ pub fn homedir() -> Option<Path> {
     _homedir()
 }
 
-/**
- * Returns the path to a temporary directory.
- *
- * On Unix, returns the value of the 'TMPDIR' environment variable if it is
- * set, otherwise for non-Android it returns '/tmp'. If Android, since there
- * is no global temporary folder (it is usually allocated per-app), we return
- * '/data/local/tmp'.
- *
- * On Windows, returns the value of, in order, the 'TMP', 'TEMP',
- * 'USERPROFILE' environment variable  if any are set and not the empty
- * string. Otherwise, tmpdir returns the path to the Windows directory.
- */
+/// Returns the path to a temporary directory.
+///
+/// On Unix, returns the value of the 'TMPDIR' environment variable if it is
+/// set, otherwise for non-Android it returns '/tmp'. If Android, since there
+/// is no global temporary folder (it is usually allocated per-app), we return
+/// '/data/local/tmp'.
+///
+/// On Windows, returns the value of, in order, the 'TMP', 'TEMP',
+/// 'USERPROFILE' environment variable  if any are set and not the empty
+/// string. Otherwise, tmpdir returns the path to the Windows directory.
 pub fn tmpdir() -> Path {
     return lookup();
 
@@ -933,16 +931,14 @@ pub fn last_os_error() -> String {
 
 static EXIT_STATUS: AtomicInt = INIT_ATOMIC_INT;
 
-/**
- * Sets the process exit code
- *
- * Sets the exit code returned by the process if all supervised tasks
- * terminate successfully (without panicking). If the current root task panics
- * and is supervised by the scheduler then any user-specified exit status is
- * ignored and the process exits with the default panic status.
- *
- * Note that this is not synchronized against modifications of other threads.
- */
+/// Sets the process exit code
+///
+/// Sets the exit code returned by the process if all supervised tasks
+/// terminate successfully (without panicking). If the current root task panics
+/// and is supervised by the scheduler then any user-specified exit status is
+/// ignored and the process exits with the default panic status.
+///
+/// Note that this is not synchronized against modifications of other threads.
 pub fn set_exit_status(code: int) {
     EXIT_STATUS.store(code, SeqCst)
 }
@@ -963,11 +959,9 @@ unsafe fn load_argc_and_argv(argc: int,
     })
 }
 
-/**
- * Returns the command line arguments
- *
- * Returns a list of the command line arguments.
- */
+/// Returns the command line arguments
+///
+/// Returns a list of the command line arguments.
 #[cfg(target_os = "macos")]
 fn real_args_as_bytes() -> Vec<Vec<u8>> {
     unsafe {
diff --git a/src/libstd/sync/lock.rs b/src/libstd/sync/lock.rs
index 6b63f7ae618..77f5b013519 100644
--- a/src/libstd/sync/lock.rs
+++ b/src/libstd/sync/lock.rs
@@ -29,9 +29,7 @@ use rustrt::task::Task;
 
 use super::raw;
 
-/****************************************************************************
- * Poisoning helpers
- ****************************************************************************/
+// Poisoning helpers
 
 struct PoisonOnFail<'a> {
     flag: &'a mut bool,
@@ -67,9 +65,7 @@ impl<'a> Drop for PoisonOnFail<'a> {
     }
 }
 
-/****************************************************************************
- * Condvar
- ****************************************************************************/
+// Condvar
 
 enum Inner<'a> {
     InnerMutex(raw::MutexGuard<'a>),
@@ -147,10 +143,6 @@ impl<'a> Condvar<'a> {
     }
 }
 
-/****************************************************************************
- * Mutex
- ****************************************************************************/
-
 /// A wrapper type which provides synchronized access to the underlying data, of
 /// type `T`. A mutex always provides exclusive access, and concurrent requests
 /// will block while the mutex is already locked.
@@ -249,10 +241,6 @@ impl<'a, T: Send> DerefMut<T> for MutexGuard<'a, T> {
     fn deref_mut<'a>(&'a mut self) -> &'a mut T { &mut *self._data }
 }
 
-/****************************************************************************
- * R/W lock protected lock
- ****************************************************************************/
-
 /// A dual-mode reader-writer lock. The data can be accessed mutably or
 /// immutably, and immutably-accessing tasks may run concurrently.
 ///
@@ -387,10 +375,6 @@ impl<'a, T: Send + Sync> DerefMut<T> for RWLockWriteGuard<'a, T> {
     fn deref_mut<'a>(&'a mut self) -> &'a mut T { &mut *self._data }
 }
 
-/****************************************************************************
- * Barrier
- ****************************************************************************/
-
 /// A barrier enables multiple tasks to synchronize the beginning
 /// of some computation.
 ///
@@ -452,10 +436,6 @@ impl Barrier {
     }
 }
 
-/****************************************************************************
- * Tests
- ****************************************************************************/
-
 #[cfg(test)]
 mod tests {
     use prelude::*;
@@ -795,9 +775,6 @@ mod tests {
         }
     }
 
-    /************************************************************************
-     * Barrier tests
-     ************************************************************************/
     #[test]
     fn test_barrier() {
         let barrier = Arc::new(Barrier::new(10));
diff --git a/src/libstd/sync/raw.rs b/src/libstd/sync/raw.rs
index ff3f2c9462c..47580a11513 100644
--- a/src/libstd/sync/raw.rs
+++ b/src/libstd/sync/raw.rs
@@ -32,10 +32,6 @@ use vec::Vec;
 use super::mutex;
 use comm::{Receiver, Sender, channel};
 
-/****************************************************************************
- * Internals
- ****************************************************************************/
-
 // Each waiting task receives on one of these.
 type WaitEnd = Receiver<()>;
 type SignalEnd = Sender<()>;
@@ -353,10 +349,6 @@ struct SemCondGuard<'a> {
     cvar: Condvar<'a>,
 }
 
-/****************************************************************************
- * Semaphores
- ****************************************************************************/
-
 /// A counting, blocking, bounded-waiting semaphore.
 pub struct Semaphore {
     sem: Sem<()>,
@@ -394,10 +386,6 @@ impl Semaphore {
     }
 }
 
-/****************************************************************************
- * Mutexes
- ****************************************************************************/
-
 /// A blocking, bounded-waiting, mutual exclusion lock with an associated
 /// FIFO condition variable.
 ///
@@ -441,10 +429,6 @@ impl Mutex {
     }
 }
 
-/****************************************************************************
- * Reader-writer locks
- ****************************************************************************/
-
 // NB: Wikipedia - Readers-writers_problem#The_third_readers-writers_problem
 
 /// A blocking, no-starvation, reader-writer lock with an associated condvar.
@@ -618,10 +602,6 @@ impl<'a> Drop for RWLockReadGuard<'a> {
     }
 }
 
-/****************************************************************************
- * Tests
- ****************************************************************************/
-
 #[cfg(test)]
 mod tests {
     pub use self::RWLockMode::*;
@@ -634,9 +614,6 @@ mod tests {
     use result;
     use task;
 
-    /************************************************************************
-     * Semaphore tests
-     ************************************************************************/
     #[test]
     fn test_sem_acquire_release() {
         let s = Semaphore::new(1);
@@ -644,16 +621,19 @@ mod tests {
         s.release();
         s.acquire();
     }
+
     #[test]
     fn test_sem_basic() {
         let s = Semaphore::new(1);
         let _g = s.access();
     }
+
     #[test]
     #[should_fail]
     fn test_sem_basic2() {
         Semaphore::new(-1);
     }
+
     #[test]
     fn test_sem_as_mutex() {
         let s = Arc::new(Semaphore::new(1));
@@ -665,6 +645,7 @@ mod tests {
         let _g = s.access();
         for _ in range(0u, 5) { task::deschedule(); }
     }
+
     #[test]
     fn test_sem_as_cvar() {
         /* Child waits and parent signals */
@@ -691,6 +672,7 @@ mod tests {
         s.acquire();
         tx.send(());
     }
+
     #[test]
     fn test_sem_multi_resource() {
         // Parent and child both get in the critical section at the same
@@ -708,6 +690,7 @@ mod tests {
         tx2.send(());
         let _ = rx1.recv();
     }
+
     #[test]
     fn test_sem_runtime_friendly_blocking() {
         // Force the runtime to schedule two threads on the same sched_loop.
@@ -727,9 +710,7 @@ mod tests {
         }
         rx.recv(); // wait for child to be done
     }
-    /************************************************************************
-     * Mutex tests
-     ************************************************************************/
+
     #[test]
     fn test_mutex_lock() {
         // Unsafely achieve shared state, and do the textbook
@@ -761,6 +742,7 @@ mod tests {
             }
         }
     }
+
     #[test]
     fn test_mutex_cond_wait() {
         let m = Arc::new(Mutex::new());
@@ -820,14 +802,17 @@ mod tests {
         // wait until all children wake up
         for rx in rxs.iter_mut() { rx.recv(); }
     }
+
     #[test]
     fn test_mutex_cond_broadcast() {
         test_mutex_cond_broadcast_helper(12);
     }
+
     #[test]
     fn test_mutex_cond_broadcast_none() {
         test_mutex_cond_broadcast_helper(0);
     }
+
     #[test]
     fn test_mutex_cond_no_waiter() {
         let m = Arc::new(Mutex::new());
@@ -838,6 +823,7 @@ mod tests {
         let lock = m2.lock();
         assert!(!lock.cond.signal());
     }
+
     #[test]
     fn test_mutex_killed_simple() {
         use any::Any;
@@ -854,6 +840,7 @@ mod tests {
         // child task must have finished by the time try returns
         drop(m.lock());
     }
+
     #[test]
     fn test_mutex_cond_signal_on_0() {
         // Tests that signal_on(0) is equivalent to signal().
@@ -866,6 +853,7 @@ mod tests {
         });
         lock.cond.wait();
     }
+
     #[test]
     fn test_mutex_no_condvars() {
         let result = task::try(proc() {
@@ -884,11 +872,10 @@ mod tests {
         });
         assert!(result.is_err());
     }
-    /************************************************************************
-     * Reader/writer lock tests
-     ************************************************************************/
+
     #[cfg(test)]
     pub enum RWLockMode { Read, Write, Downgrade, DowngradeRead }
+
     #[cfg(test)]
     fn lock_rwlock_in_mode(x: &Arc<RWLock>, mode: RWLockMode, blk: ||) {
         match mode {
@@ -898,6 +885,7 @@ mod tests {
             DowngradeRead => { let _g = x.write().downgrade(); blk() }
         }
     }
+
     #[cfg(test)]
     fn test_rwlock_exclusion(x: Arc<RWLock>,
                              mode1: RWLockMode,
@@ -934,6 +922,7 @@ mod tests {
             }
         }
     }
+
     #[test]
     fn test_rwlock_readers_wont_modify_the_data() {
         test_rwlock_exclusion(Arc::new(RWLock::new()), Read, Write);
@@ -943,6 +932,7 @@ mod tests {
         test_rwlock_exclusion(Arc::new(RWLock::new()), Write, DowngradeRead);
         test_rwlock_exclusion(Arc::new(RWLock::new()), DowngradeRead, Write);
     }
+
     #[test]
     fn test_rwlock_writers_and_writers() {
         test_rwlock_exclusion(Arc::new(RWLock::new()), Write, Write);
@@ -950,6 +940,7 @@ mod tests {
         test_rwlock_exclusion(Arc::new(RWLock::new()), Downgrade, Write);
         test_rwlock_exclusion(Arc::new(RWLock::new()), Downgrade, Downgrade);
     }
+
     #[cfg(test)]
     fn test_rwlock_handshake(x: Arc<RWLock>,
                              mode1: RWLockMode,
@@ -982,6 +973,7 @@ mod tests {
             rx1.recv();
         })
     }
+
     #[test]
     fn test_rwlock_readers_and_readers() {
         test_rwlock_handshake(Arc::new(RWLock::new()), Read, Read, false);
@@ -991,6 +983,7 @@ mod tests {
         test_rwlock_handshake(Arc::new(RWLock::new()), Read, DowngradeRead, true);
         // Two downgrade_reads can never both end up reading at the same time.
     }
+
     #[test]
     fn test_rwlock_downgrade_unlock() {
         // Tests that downgrade can unlock the lock in both modes
@@ -1001,12 +994,14 @@ mod tests {
         lock_rwlock_in_mode(&y, DowngradeRead, || { });
         test_rwlock_exclusion(y, Write, Write);
     }
+
     #[test]
     fn test_rwlock_read_recursive() {
         let x = RWLock::new();
         let _g1 = x.read();
         let _g2 = x.read();
     }
+
     #[test]
     fn test_rwlock_cond_wait() {
         // As test_mutex_cond_wait above.
@@ -1040,6 +1035,7 @@ mod tests {
         rx.recv(); // Wait until child wakes up
         drop(x.read()); // Just for good measure
     }
+
     #[cfg(test)]
     fn test_rwlock_cond_broadcast_helper(num_waiters: uint) {
         // Much like the mutex broadcast test. Downgrade-enabled.
@@ -1073,11 +1069,13 @@ mod tests {
         // wait until all children wake up
         for rx in rxs.iter_mut() { let _ = rx.recv(); }
     }
+
     #[test]
     fn test_rwlock_cond_broadcast() {
         test_rwlock_cond_broadcast_helper(0);
         test_rwlock_cond_broadcast_helper(12);
     }
+
     #[cfg(test)]
     fn rwlock_kill_helper(mode1: RWLockMode, mode2: RWLockMode) {
         use any::Any;
@@ -1095,22 +1093,27 @@ mod tests {
         // child task must have finished by the time try returns
         lock_rwlock_in_mode(&x, mode2, || { })
     }
+
     #[test]
     fn test_rwlock_reader_killed_writer() {
         rwlock_kill_helper(Read, Write);
     }
+
     #[test]
     fn test_rwlock_writer_killed_reader() {
         rwlock_kill_helper(Write, Read);
     }
+
     #[test]
     fn test_rwlock_reader_killed_reader() {
         rwlock_kill_helper(Read, Read);
     }
+
     #[test]
     fn test_rwlock_writer_killed_writer() {
         rwlock_kill_helper(Write, Write);
     }
+
     #[test]
     fn test_rwlock_kill_downgrader() {
         rwlock_kill_helper(Downgrade, Read);
diff --git a/src/libstd/sys/windows/process.rs b/src/libstd/sys/windows/process.rs
index 3fb5ee34356..37e0fd6e55d 100644
--- a/src/libstd/sys/windows/process.rs
+++ b/src/libstd/sys/windows/process.rs
@@ -33,13 +33,11 @@ use string::String;
 
 pub use sys_common::ProcessConfig;
 
-/**
- * A value representing a child process.
- *
- * The lifetime of this value is linked to the lifetime of the actual
- * process - the Process destructor calls self.finish() which waits
- * for the process to terminate.
- */
+/// A value representing a child process.
+///
+/// The lifetime of this value is linked to the lifetime of the actual
+/// process - the Process destructor calls self.finish() which waits
+/// for the process to terminate.
 pub struct Process {
     /// The unique id of the process (this should never be negative).
     pid: pid_t,
@@ -263,16 +261,14 @@ impl Process {
         }
     }
 
-    /**
-     * Waits for a process to exit and returns the exit code, failing
-     * if there is no process with the specified id.
-     *
-     * Note that this is private to avoid race conditions on unix where if
-     * a user calls waitpid(some_process.get_id()) then some_process.finish()
-     * and some_process.destroy() and some_process.finalize() will then either
-     * operate on a none-existent process or, even worse, on a newer process
-     * with the same id.
-     */
+    /// Waits for a process to exit and returns the exit code, failing
+    /// if there is no process with the specified id.
+    ///
+    /// Note that this is private to avoid race conditions on unix where if
+    /// a user calls waitpid(some_process.get_id()) then some_process.finish()
+    /// and some_process.destroy() and some_process.finalize() will then either
+    /// operate on a none-existent process or, even worse, on a newer process
+    /// with the same id.
     pub fn wait(&self, deadline: u64) -> IoResult<ProcessExit> {
         use libc::types::os::arch::extra::DWORD;
         use libc::consts::os::extra::{