convert doc-attributes to doc-comments using ./src/etc/sugarise-doc-comments.py (and manually tweaking) - for issue #2498

30 files changed, 1474 insertions, 1502 deletions

diff --git a/src/libstd/bitv.rs b/src/libstd/bitv.rs
index adc3a7969d6..f6c7b573f65 100644
--- a/src/libstd/bitv.rs
+++ b/src/libstd/bitv.rs
@@ -21,19 +21,19 @@ export eq_vec;
 // write an optimizing version of this module that produces a different obj
 // for the case where nbits <= 32.
 
-#[doc = "The bitvector type"]
+/// The bitvector type
 type bitv = @{storage: ~[mut uint], nbits: uint};
 
 const uint_bits: uint = 32u + (1u << 32u >> 27u);
 
-#[doc = "
-Constructs a bitvector
-
-# Arguments
-
-* nbits - The number of bits in the bitvector
-* init - If true then the bits are initialized to 1, otherwise 0
-"]
+/**
+ * Constructs a bitvector
+ *
+ * # Arguments
+ *
+ * * nbits - The number of bits in the bitvector
+ * * init - If true then the bits are initialized to 1, otherwise 0
+ */
 fn bitv(nbits: uint, init: bool) -> bitv {
     let elt = if init { !0u } else { 0u };
     let storage = vec::to_mut(vec::from_elem(nbits / uint_bits + 1u, elt));
@@ -63,12 +63,12 @@ fn union(v0: bitv, v1: bitv) -> bool {
 
 fn land(w0: uint, w1: uint) -> uint { ret w0 & w1; }
 
-#[doc = "
-Calculates the intersection of two bitvectors
-
-Sets `v0` to the intersection of `v0` and `v1`. Both bitvectors must be the
-same length. Returns 'true' if `v0` was changed.
-"]
+/**
+ * Calculates the intersection of two bitvectors
+ *
+ * Sets `v0` to the intersection of `v0` and `v1`. Both bitvectors must be the
+ * same length. Returns 'true' if `v0` was changed.
+ */
 fn intersect(v0: bitv, v1: bitv) -> bool {
     let sub = land;
     ret process(v0, v1, sub);
@@ -76,16 +76,16 @@ fn intersect(v0: bitv, v1: bitv) -> bool {
 
 fn right(_w0: uint, w1: uint) -> uint { ret w1; }
 
-#[doc = "
-Assigns the value of `v1` to `v0`
-
-Both bitvectors must be the same length. Returns `true` if `v0` was changed
-"]
+/**
+ * Assigns the value of `v1` to `v0`
+ *
+ * Both bitvectors must be the same length. Returns `true` if `v0` was changed
+ */
 fn assign(v0: bitv, v1: bitv) -> bool {
     let sub = right; ret process(v0, v1, sub);
 }
 
-#[doc = "Makes a copy of a bitvector"]
+/// Makes a copy of a bitvector
 fn clone(v: bitv) -> bitv {
     let storage = vec::to_mut(vec::from_elem(v.nbits / uint_bits + 1u, 0u));
     let len = vec::len(v.storage);
@@ -93,7 +93,7 @@ fn clone(v: bitv) -> bitv {
     ret @{storage: storage, nbits: v.nbits};
 }
 
-#[doc = "Retrieve the value at index `i`"]
+/// Retrieve the value at index `i`
 #[inline(always)]
 pure fn get(v: bitv, i: uint) -> bool {
     assert (i < v.nbits);
@@ -104,12 +104,12 @@ pure fn get(v: bitv, i: uint) -> bool {
     ret x == 1u;
 }
 
-#[doc = "
-Compares two bitvectors
-
-Both bitvectors must be the same length. Returns `true` if both bitvectors
-contain identical elements.
-"]
+/**
+ * Compares two bitvectors
+ *
+ * Both bitvectors must be the same length. Returns `true` if both bitvectors
+ * contain identical elements.
+ */
 fn equal(v0: bitv, v1: bitv) -> bool {
     if v0.nbits != v1.nbits { ret false; }
     let len = vec::len(v1.storage);
@@ -118,26 +118,26 @@ fn equal(v0: bitv, v1: bitv) -> bool {
     }
 }
 
-#[doc = "Set all bits to 0"]
+/// Set all bits to 0
 #[inline(always)]
 fn clear(v: bitv) { for each_storage(v) |w| { w = 0u } }
 
-#[doc = "Set all bits to 1"]
+/// Set all bits to 1
 #[inline(always)]
 fn set_all(v: bitv) { for each_storage(v) |w| { w = !0u } }
 
-#[doc = "Invert all bits"]
+/// Invert all bits
 #[inline(always)]
 fn invert(v: bitv) { for each_storage(v) |w| { w = !w } }
 
-#[doc = "
-Calculate the difference between two bitvectors
-
-Sets each element of `v0` to the value of that element minus the element
-of `v1` at the same index. Both bitvectors must be the same length.
-
-Returns `true` if `v0` was changed.
-"]
+/**
+ * Calculate the difference between two bitvectors
+ *
+ * Sets each element of `v0` to the value of that element minus the element
+ * of `v1` at the same index. Both bitvectors must be the same length.
+ *
+ * Returns `true` if `v0` was changed.
+ */
 fn difference(v0: bitv, v1: bitv) -> bool {
     invert(v1);
     let b = intersect(v0, v1);
@@ -145,11 +145,11 @@ fn difference(v0: bitv, v1: bitv) -> bool {
     ret b;
 }
 
-#[doc = "
-Set the value of a bit at a given index
-
-`i` must be less than the length of the bitvector.
-"]
+/**
+ * Set the value of a bit at a given index
+ *
+ * `i` must be less than the length of the bitvector.
+ */
 #[inline(always)]
 fn set(v: bitv, i: uint, x: bool) {
     assert (i < v.nbits);
@@ -161,14 +161,14 @@ fn set(v: bitv, i: uint, x: bool) {
 }
 
 
-#[doc = "Returns true if all bits are 1"]
+/// Returns true if all bits are 1
 fn is_true(v: bitv) -> bool {
     for each(v) |i| { if !i { ret false; } }
     ret true;
 }
 
 
-#[doc = "Returns true if all bits are 0"]
+/// Returns true if all bits are 0
 fn is_false(v: bitv) -> bool {
     for each(v) |i| { if i { ret false; } }
     ret true;
@@ -178,11 +178,11 @@ fn init_to_vec(v: bitv, i: uint) -> uint {
     ret if get(v, i) { 1u } else { 0u };
 }
 
-#[doc = "
-Converts the bitvector to a vector of uint with the same length.
-
-Each uint in the resulting vector has either value 0u or 1u.
-"]
+/**
+ * Converts the bitvector to a vector of uint with the same length.
+ *
+ * Each uint in the resulting vector has either value 0u or 1u.
+ */
 fn to_vec(v: bitv) -> ~[uint] {
     let sub = |x| init_to_vec(v, x);
     ret vec::from_fn::<uint>(v.nbits, sub);
@@ -207,24 +207,24 @@ fn each_storage(v: bitv, op: fn(&uint) -> bool) {
     }
 }
 
-#[doc = "
-Converts the bitvector to a string.
-
-The resulting string has the same length as the bitvector, and each character
-is either '0' or '1'.
-"]
+/**
+ * Converts the bitvector to a string.
+ *
+ * The resulting string has the same length as the bitvector, and each
+ * character is either '0' or '1'.
+ */
 fn to_str(v: bitv) -> str {
     let mut rs = "";
     for each(v) |i| { if i { rs += "1"; } else { rs += "0"; } }
     ret rs;
 }
 
-#[doc = "
-Compare a bitvector to a vector of uint
-
-The uint vector is expected to only contain the values 0u and 1u. Both the
-bitvector and vector must have the same length
-"]
+/**
+ * Compare a bitvector to a vector of uint
+ *
+ * The uint vector is expected to only contain the values 0u and 1u. Both the
+ * bitvector and vector must have the same length
+ */
 fn eq_vec(v0: bitv, v1: ~[uint]) -> bool {
     assert (v0.nbits == vec::len::<uint>(v1));
     let len = v0.nbits;
diff --git a/src/libstd/c_vec.rs b/src/libstd/c_vec.rs
index 258bc432da1..7f71b999d6f 100644
--- a/src/libstd/c_vec.rs
+++ b/src/libstd/c_vec.rs
@@ -1,29 +1,30 @@
-#[doc = "
-Library to interface with chunks of memory allocated in C.
-
-It is often desirable to safely interface with memory allocated from C,
-encapsulating the unsafety into allocation and destruction time.  Indeed,
-allocating memory externally is currently the only way to give Rust shared
-mut state with C programs that keep their own references; vectors are
-unsuitable because they could be reallocated or moved at any time, and
-importing C memory into a vector takes a one-time snapshot of the memory.
-
-This module simplifies the usage of such external blocks of memory.  Memory
-is encapsulated into an opaque object after creation; the lifecycle of the
-memory can be optionally managed by Rust, if an appropriate destructor
-closure is provided.  Safety is ensured by bounds-checking accesses, which
-are marshalled through get and set functions.
-
-There are three unsafe functions: the two introduction forms, and the
-pointer elimination form.  The introduction forms are unsafe for the obvious
-reason (they act on a pointer that cannot be checked inside the method), but
-the elimination form is somewhat more subtle in its unsafety.  By using a
-pointer taken from a c_vec::t without keeping a reference to the c_vec::t
-itself around, the c_vec could be garbage collected, and the memory within
-could be destroyed.  There are legitimate uses for the pointer elimination
-form -- for instance, to pass memory back into C -- but great care must be
-taken to ensure that a reference to the c_vec::t is still held if needed.
-"];
+/*!
+ * Library to interface with chunks of memory allocated in C.
+ *
+ * It is often desirable to safely interface with memory allocated from C,
+ * encapsulating the unsafety into allocation and destruction time.  Indeed,
+ * allocating memory externally is currently the only way to give Rust shared
+ * mut state with C programs that keep their own references; vectors are
+ * unsuitable because they could be reallocated or moved at any time, and
+ * importing C memory into a vector takes a one-time snapshot of the memory.
+ *
+ * This module simplifies the usage of such external blocks of memory.  Memory
+ * is encapsulated into an opaque object after creation; the lifecycle of the
+ * memory can be optionally managed by Rust, if an appropriate destructor
+ * closure is provided.  Safety is ensured by bounds-checking accesses, which
+ * are marshalled through get and set functions.
+ *
+ * There are three unsafe functions: the two introduction forms, and the
+ * pointer elimination form.  The introduction forms are unsafe for the
+ * obvious reason (they act on a pointer that cannot be checked inside the
+ * method), but the elimination form is somewhat more subtle in its unsafety.
+ * By using a pointer taken from a c_vec::t without keeping a reference to the
+ * c_vec::t itself around, the c_vec could be garbage collected, and the
+ * memory within could be destroyed.  There are legitimate uses for the
+ * pointer elimination form -- for instance, to pass memory back into C -- but
+ * great care must be taken to ensure that a reference to the c_vec::t is
+ * still held if needed.
+ */
 
 export c_vec;
 export c_vec, c_vec_with_dtor;
@@ -31,12 +32,12 @@ export get, set;
 export len;
 export ptr;
 
-#[doc = "
-The type representing a foreign chunk of memory
-
-Wrapped in a enum for opacity; FIXME #818 when it is possible to have
-truly opaque types, this should be revisited.
-"]
+/**
+ * The type representing a foreign chunk of memory
+ *
+ * Wrapped in a enum for opacity; FIXME #818 when it is possible to have
+ * truly opaque types, this should be revisited.
+ */
 enum c_vec<T> {
     c_vec_({ base: *mut T, len: uint, rsrc: @dtor_res})
 }
@@ -56,14 +57,14 @@ class dtor_res {
  Section: Introduction forms
  */
 
-#[doc = "
-Create a `c_vec` from a foreign buffer with a given length.
-
-# Arguments
-
-* base - A foreign pointer to a buffer
-* len - The number of elements in the buffer
-"]
+/**
+ * Create a `c_vec` from a foreign buffer with a given length.
+ *
+ * # Arguments
+ *
+ * * base - A foreign pointer to a buffer
+ * * len - The number of elements in the buffer
+ */
 unsafe fn c_vec<T>(base: *mut T, len: uint) -> c_vec<T> {
     ret c_vec_({
         base: base,
@@ -72,17 +73,17 @@ unsafe fn c_vec<T>(base: *mut T, len: uint) -> c_vec<T> {
     });
 }
 
-#[doc = "
-Create a `c_vec` from a foreign buffer, with a given length,
-and a function to run upon destruction.
-
-# Arguments
-
-* base - A foreign pointer to a buffer
-* len - The number of elements in the buffer
-* dtor - A function to run when the value is destructed, useful
-         for freeing the buffer, etc.
-"]
+/**
+ * Create a `c_vec` from a foreign buffer, with a given length,
+ * and a function to run upon destruction.
+ *
+ * # Arguments
+ *
+ * * base - A foreign pointer to a buffer
+ * * len - The number of elements in the buffer
+ * * dtor - A function to run when the value is destructed, useful
+ *          for freeing the buffer, etc.
+ */
 unsafe fn c_vec_with_dtor<T>(base: *mut T, len: uint, dtor: fn@())
   -> c_vec<T> {
     ret c_vec_({
@@ -96,21 +97,21 @@ unsafe fn c_vec_with_dtor<T>(base: *mut T, len: uint, dtor: fn@())
  Section: Operations
  */
 
-#[doc = "
-Retrieves an element at a given index
-
-Fails if `ofs` is greater or equal to the length of the vector
-"]
+/**
+ * Retrieves an element at a given index
+ *
+ * Fails if `ofs` is greater or equal to the length of the vector
+ */
 fn get<T: copy>(t: c_vec<T>, ofs: uint) -> T {
     assert ofs < len(t);
     ret unsafe { *ptr::mut_offset((*t).base, ofs) };
 }
 
-#[doc = "
-Sets the value of an element at a given index
-
-Fails if `ofs` is greater or equal to the length of the vector
-"]
+/**
+ * Sets the value of an element at a given index
+ *
+ * Fails if `ofs` is greater or equal to the length of the vector
+ */
 fn set<T: copy>(t: c_vec<T>, ofs: uint, v: T) {
     assert ofs < len(t);
     unsafe { *ptr::mut_offset((*t).base, ofs) = v };
@@ -120,12 +121,12 @@ fn set<T: copy>(t: c_vec<T>, ofs: uint, v: T) {
  Section: Elimination forms
  */
 
-#[doc = "Returns the length of the vector"]
+/// Returns the length of the vector
 fn len<T>(t: c_vec<T>) -> uint {
     ret (*t).len;
 }
 
-#[doc = "Returns a pointer to the first element of the vector"]
+/// Returns a pointer to the first element of the vector
 unsafe fn ptr<T>(t: c_vec<T>) -> *mut T {
     ret (*t).base;
 }
@@ -183,4 +184,4 @@ mod tests {
         set(cv, 2u, 34u8); /* safety */
     }
 
-}
\ No newline at end of file
+}
diff --git a/src/libstd/cmp.rs b/src/libstd/cmp.rs
index f94c0a7c6af..a89148ecec9 100644
--- a/src/libstd/cmp.rs
+++ b/src/libstd/cmp.rs
@@ -1,4 +1,4 @@
-#[doc="Additional general-purpose comparison functionality."]
+/// Additional general-purpose comparison functionality.
 
 const fuzzy_epsilon: float = 1.0e-6;
 
diff --git a/src/libstd/dbg.rs b/src/libstd/dbg.rs
index be0330e543a..ddc0d3b4450 100644
--- a/src/libstd/dbg.rs
+++ b/src/libstd/dbg.rs
@@ -1,4 +1,4 @@
-#[doc = "Unsafe debugging functions for inspecting values."];
+//! Unsafe debugging functions for inspecting values.
 
 import unsafe::reinterpret_cast;
 
@@ -47,7 +47,7 @@ unsafe fn ptr_cast<T, U>(x: @T) -> @U {
                               reinterpret_cast(x)))
 }
 
-#[doc = "Triggers a debugger breakpoint"]
+/// Triggers a debugger breakpoint
 fn breakpoint() {
     rustrt::rust_dbg_breakpoint();
 }
diff --git a/src/libstd/deque.rs b/src/libstd/deque.rs
index 32516de2524..416a52cde5b 100644
--- a/src/libstd/deque.rs
+++ b/src/libstd/deque.rs
@@ -1,4 +1,4 @@
-#[doc = "A deque. Untested as of yet. Likely buggy"];
+//! A deque. Untested as of yet. Likely buggy
 
 import option::{some, none};
 import dvec::{dvec, extensions};
diff --git a/src/libstd/fun_treemap.rs b/src/libstd/fun_treemap.rs
index 3e1a11665fe..6a3b40b88ff 100644
--- a/src/libstd/fun_treemap.rs
+++ b/src/libstd/fun_treemap.rs
@@ -1,13 +1,13 @@
-#[doc = "
-A functional key,value store that works on anything.
-
-This works using a binary search tree. In the first version, it's a
-very naive algorithm, but it will probably be updated to be a
-red-black tree or something else.
-
-This is copied and modified from treemap right now. It's missing a lot
-of features.
-"];
+/*!
+ * A functional key,value store that works on anything.
+ *
+ * This works using a binary search tree. In the first version, it's a
+ * very naive algorithm, but it will probably be updated to be a
+ * red-black tree or something else.
+ *
+ * This is copied and modified from treemap right now. It's missing a lot
+ * of features.
+ */
 
 import option::{some, none};
 import option = option;
@@ -25,10 +25,10 @@ enum tree_node<K, V> {
     node(@K, @V, @tree_node<K, V>, @tree_node<K, V>)
 }
 
-#[doc = "Create a treemap"]
+/// Create a treemap
 fn init<K, V>() -> treemap<K, V> { @empty }
 
-#[doc = "Insert a value into the map"]
+/// Insert a value into the map
 fn insert<K: copy, V: copy>(m: treemap<K, V>, k: K, v: V) -> treemap<K, V> {
     @alt m {
        @empty { node(@k, @v, @empty, @empty) }
@@ -42,7 +42,7 @@ fn insert<K: copy, V: copy>(m: treemap<K, V>, k: K, v: V) -> treemap<K, V> {
      }
 }
 
-#[doc = "Find a value based on the key"]
+/// Find a value based on the key
 fn find<K, V: copy>(m: treemap<K, V>, k: K) -> option<V> {
     alt *m {
       empty { none }
@@ -54,7 +54,7 @@ fn find<K, V: copy>(m: treemap<K, V>, k: K) -> option<V> {
     }
 }
 
-#[doc = "Visit all pairs in the map in order."]
+/// Visit all pairs in the map in order.
 fn traverse<K, V: copy>(m: treemap<K, V>, f: fn(K, V)) {
     alt *m {
       empty { }
diff --git a/src/libstd/getopts.rs b/src/libstd/getopts.rs
index c01885bf40b..fba3ae9e3db 100644
--- a/src/libstd/getopts.rs
+++ b/src/libstd/getopts.rs
@@ -1,67 +1,66 @@
-#[doc = "
-Simple getopt alternative.
-
-Construct a vector of options, either by using reqopt, optopt, and optflag or
-by building them from components yourself, and pass them to getopts, along
-with a vector of actual arguments (not including argv[0]). You'll either get a
-failure code back, or a match. You'll have to verify whether the amount of
-'free' arguments in the match is what you expect. Use opt_* accessors to get
-argument values out of the match object.
-
-Single-character options are expected to appear on the command line with a
-single preceding dash; multiple-character options are expected to be
-proceeded by two dashes. Options that expect an argument accept their argument
-following either a space or an equals sign.
-
-# Example
-
-The following example shows simple command line parsing for an application
-that requires an input file to be specified, accepts an optional output file
-name following -o, and accepts both -h and --help as optional flags.
-
-    use std;
-    import std::getopts::{optopt,optflag,getopts,opt_present,opt_maybe_str,
-        fail_str};
-
-    fn do_work(in: str, out: option<str>) {
-        // ...
-    }
-
-    fn print_usage(program: str) {
-        io::println(\"Usage: \" + program + \" [options]/~\");
-        io::println(\"-o\t\tOutput\");
-        io::println(\"-h --help\tUsage\");
-    }
-
-    fn main(args: [str]/~) {
-        check vec::is_not_empty(args);
-
-        let program : str = vec::head(args);
-
-        let opts = [
-            optopt(\"o\"),
-            optflag(\"h\"),
-            optflag(\"help\")
-        ]/~;
-        let match = alt getopts(vec::tail(args), opts) {
-            result::ok(m) { m }
-            result::err(f) { fail fail_str(f) }
-        };
-        if opt_present(match, \"h\") || opt_present(match, \"help\") {
-            print_usage(program);
-            ret;
-        }
-        let output = opt_maybe_str(match, \"o\");
-        let input = if vec::is_not_empty(match.free) {
-            match.free[0]
-        } else {
-            print_usage(program);
-            ret;
-        };
-        do_work(input, output);
-    }
-
-"];
+/*!
+ * Simple getopt alternative.
+ *
+ * Construct a vector of options, either by using reqopt, optopt, and optflag
+ * or by building them from components yourself, and pass them to getopts,
+ * along with a vector of actual arguments (not including argv[0]). You'll
+ * either get a failure code back, or a match. You'll have to verify whether
+ * the amount of 'free' arguments in the match is what you expect. Use opt_*
+ * accessors to get argument values out of the match object.
+ *
+ * Single-character options are expected to appear on the command line with a
+ * single preceding dash; multiple-character options are expected to be
+ * proceeded by two dashes. Options that expect an argument accept their
+ * argument following either a space or an equals sign.
+ *
+ * # Example
+ *
+ * The following example shows simple command line parsing for an application
+ * that requires an input file to be specified, accepts an optional output
+ * file name following -o, and accepts both -h and --help as optional flags.
+ *
+ *     use std;
+ *     import std::getopts::{optopt,optflag,getopts,opt_present,opt_maybe_str,
+ *         fail_str};
+ *
+ *     fn do_work(in: str, out: option<str>) {
+ *         // ...
+ *     }
+ *
+ *     fn print_usage(program: str) {
+ *         io::println("Usage: " + program + " [options]/~");
+ *         io::println("-o\t\tOutput");
+ *         io::println("-h --help\tUsage");
+ *     }
+ *
+ *     fn main(args: [str]/~) {
+ *         check vec::is_not_empty(args);
+ *
+ *         let program : str = vec::head(args);
+ *
+ *         let opts = [
+ *             optopt("o"),
+ *             optflag("h"),
+ *             optflag("help")
+ *         ]/~;
+ *         let match = alt getopts(vec::tail(args), opts) {
+ *             result::ok(m) { m }
+ *             result::err(f) { fail fail_str(f) }
+ *         };
+ *         if opt_present(match, "h") || opt_present(match, "help") {
+ *             print_usage(program);
+ *             ret;
+ *         }
+ *         let output = opt_maybe_str(match, "o");
+ *         let input = if vec::is_not_empty(match.free) {
+ *             match.free[0]
+ *         } else {
+ *             print_usage(program);
+ *             ret;
+ *         };
+ *         do_work(input, output);
+ *     }
+ */
 
 import core::result::{err, ok};
 import core::option;
@@ -91,7 +90,7 @@ enum hasarg { yes, no, maybe, }
 
 enum occur { req, optional, multi, }
 
-#[doc = "A description of a possible option"]
+/// A description of a possible option
 type opt = {name: name, hasarg: hasarg, occur: occur};
 
 fn mkname(nm: str) -> name {
@@ -100,40 +99,40 @@ fn mkname(nm: str) -> name {
         } else { long(nm) };
 }
 
-#[doc = "Create an option that is required and takes an argument"]
+/// Create an option that is required and takes an argument
 fn reqopt(name: str) -> opt {
     ret {name: mkname(name), hasarg: yes, occur: req};
 }
 
-#[doc = "Create an option that is optional and takes an argument"]
+/// Create an option that is optional and takes an argument
 fn optopt(name: str) -> opt {
     ret {name: mkname(name), hasarg: yes, occur: optional};
 }
 
-#[doc = "Create an option that is optional and does not take an argument"]
+/// Create an option that is optional and does not take an argument
 fn optflag(name: str) -> opt {
     ret {name: mkname(name), hasarg: no, occur: optional};
 }
 
-#[doc = "Create an option that is optional and takes an optional argument"]
+/// Create an option that is optional and takes an optional argument
 fn optflagopt(name: str) -> opt {
     ret {name: mkname(name), hasarg: maybe, occur: optional};
 }
 
-#[doc = "
-Create an option that is optional, takes an argument, and may occur
-multiple times
-"]
+/**
+ * Create an option that is optional, takes an argument, and may occur
+ * multiple times
+ */
 fn optmulti(name: str) -> opt {
     ret {name: mkname(name), hasarg: yes, occur: multi};
 }
 
 enum optval { val(str), given, }
 
-#[doc = "
-The result of checking command line arguments. Contains a vector
-of matches and a vector of free strings.
-"]
+/**
+ * The result of checking command line arguments. Contains a vector
+ * of matches and a vector of free strings.
+ */
 type match = {opts: ~[opt], vals: ~[~[optval]], free: ~[str]};
 
 fn is_arg(arg: str) -> bool {
@@ -148,10 +147,10 @@ fn find_opt(opts: ~[opt], nm: name) -> option<uint> {
     vec::position(opts, |opt| opt.name == nm)
 }
 
-#[doc = "
-The type returned when the command line does not conform to the
-expected format. Pass this value to <fail_str> to get an error message.
-"]
+/**
+ * The type returned when the command line does not conform to the
+ * expected format. Pass this value to <fail_str> to get an error message.
+ */
 enum fail_ {
     argument_missing(str),
     unrecognized_option(str),
@@ -160,7 +159,7 @@ enum fail_ {
     unexpected_argument(str),
 }
 
-#[doc = "Convert a `fail_` enum into an error string"]
+/// Convert a `fail_` enum into an error string
 fn fail_str(f: fail_) -> str {
     ret alt f {
           argument_missing(nm) { "Argument to option '" + nm + "' missing." }
@@ -175,19 +174,19 @@ fn fail_str(f: fail_) -> str {
         };
 }
 
-#[doc = "
-The result of parsing a command line with a set of options
-(result::t<match, fail_>)
-"]
+/**
+ * The result of parsing a command line with a set of options
+ * (result::t<match, fail_>)
+ */
 type result = result::result<match, fail_>;
 
-#[doc = "
-Parse command line arguments according to the provided options
-
-On success returns `ok(opt)`. Use functions such as `opt_present` `opt_str`,
-etc. to interrogate results.  Returns `err(fail_)` on failure. Use <fail_str>
-to get an error message.
-"]
+/**
+ * Parse command line arguments according to the provided options
+ *
+ * On success returns `ok(opt)`. Use functions such as `opt_present`
+ * `opt_str`, etc. to interrogate results.  Returns `err(fail_)` on failure.
+ * Use <fail_str> to get an error message.
+ */
 fn getopts(args: ~[str], opts: ~[opt]) -> result unsafe {
     let n_opts = vec::len::<opt>(opts);
     fn f(_x: uint) -> ~[optval] { ret ~[]; }
@@ -319,12 +318,12 @@ fn opt_vals(m: match, nm: str) -> ~[optval] {
 
 fn opt_val(m: match, nm: str) -> optval { ret opt_vals(m, nm)[0]; }
 
-#[doc = "Returns true if an option was matched"]
+/// Returns true if an option was matched
 fn opt_present(m: match, nm: str) -> bool {
     ret vec::len::<optval>(opt_vals(m, nm)) > 0u;
 }
 
-#[doc = "Returns true if any of several options were matched"]
+/// Returns true if any of several options were matched
 fn opts_present(m: match, names: ~[str]) -> bool {
     for vec::each(names) |nm| {
         alt find_opt(m.opts, mkname(nm)) {
@@ -336,21 +335,22 @@ fn opts_present(m: match, names: ~[str]) -> bool {
 }
 
 
-#[doc = "
-Returns the string argument supplied to a matching option
-
-Fails if the option was not matched or if the match did not take an argument
-"]
+/**
+ * Returns the string argument supplied to a matching option
+ *
+ * Fails if the option was not matched or if the match did not take an
+ * argument
+ */
 fn opt_str(m: match, nm: str) -> str {
     ret alt opt_val(m, nm) { val(s) { s } _ { fail } };
 }
 
-#[doc = "
-Returns the string argument supplied to one of several matching options
-
-Fails if the no option was provided from the given list, or if the no such
-option took an argument
-"]
+/**
+ * Returns the string argument supplied to one of several matching options
+ *
+ * Fails if the no option was provided from the given list, or if the no such
+ * option took an argument
+ */
 fn opts_str(m: match, names: ~[str]) -> str {
     for vec::each(names) |nm| {
         alt opt_val(m, nm) {
@@ -362,11 +362,12 @@ fn opts_str(m: match, names: ~[str]) -> str {
 }
 
 
-#[doc = "
-Returns a vector of the arguments provided to all matches of the given option.
-
-Used when an option accepts multiple values.
-"]
+/**
+ * Returns a vector of the arguments provided to all matches of the given
+ * option.
+ *
+ * Used when an option accepts multiple values.
+ */
 fn opt_strs(m: match, nm: str) -> ~[str] {
     let mut acc: ~[str] = ~[];
     for vec::each(opt_vals(m, nm)) |v| {
@@ -375,9 +376,7 @@ fn opt_strs(m: match, nm: str) -> ~[str] {
     ret acc;
 }
 
-#[doc = "
-Returns the string argument supplied to a matching option or none
-"]
+/// Returns the string argument supplied to a matching option or none
 fn opt_maybe_str(m: match, nm: str) -> option<str> {
     let vals = opt_vals(m, nm);
     if vec::len::<optval>(vals) == 0u { ret none::<str>; }
@@ -385,13 +384,13 @@ fn opt_maybe_str(m: match, nm: str) -> option<str> {
 }
 
 
-#[doc = "
-Returns the matching string, a default, or none
-
-Returns none if the option was not present, `def` if the option was
-present but no argument was provided, and the argument if the option was
-present and an argument was provided.
-"]
+/**
+ * Returns the matching string, a default, or none
+ *
+ * Returns none if the option was not present, `def` if the option was
+ * present but no argument was provided, and the argument if the option was
+ * present and an argument was provided.
+ */
 fn opt_default(m: match, nm: str, def: str) -> option<str> {
     let vals = opt_vals(m, nm);
     if vec::len::<optval>(vals) == 0u { ret none::<str>; }
diff --git a/src/libstd/json.rs b/src/libstd/json.rs
index 45983654eec..9f51ab157b7 100644
--- a/src/libstd/json.rs
+++ b/src/libstd/json.rs
@@ -1,7 +1,7 @@
 // Rust JSON serialization library
 // Copyright (c) 2011 Google Inc.
 
-#[doc = "json serialization"];
+//! json serialization
 
 import result::{result, ok, err};
 import io;
@@ -26,7 +26,7 @@ export list;
 export dict;
 export null;
 
-#[doc = "Represents a json value"]
+/// Represents a json value
 enum json {
     num(float),
     string(@str),
@@ -42,7 +42,7 @@ type error = {
     msg: @str,
 };
 
-#[doc = "Serializes a json value into a io::writer"]
+/// Serializes a json value into a io::writer
 fn to_writer(wr: io::writer, j: json) {
     alt j {
       num(n) { wr.write_str(float::to_str(n, 6u)); }
@@ -109,7 +109,7 @@ fn escape_str(s: str) -> str {
     escaped
 }
 
-#[doc = "Serializes a json value into a string"]
+/// Serializes a json value into a string
 fn to_str(j: json) -> str {
     io::with_str_writer(|wr| to_writer(wr, j))
 }
@@ -461,7 +461,7 @@ impl parser for parser {
     }
 }
 
-#[doc = "Deserializes a json value from an io::reader"]
+/// Deserializes a json value from an io::reader
 fn from_reader(rdr: io::reader) -> result<json, error> {
     let parser = {
         rdr: rdr,
@@ -473,12 +473,12 @@ fn from_reader(rdr: io::reader) -> result<json, error> {
     parser.parse()
 }
 
-#[doc = "Deserializes a json value from a string"]
+/// Deserializes a json value from a string
 fn from_str(s: str) -> result<json, error> {
     io::with_str_reader(s, from_reader)
 }
 
-#[doc = "Test if two json values are equal"]
+/// Test if two json values are equal
 fn eq(value0: json, value1: json) -> bool {
     alt (value0, value1) {
       (num(f0), num(f1)) { f0 == f1 }
diff --git a/src/libstd/list.rs b/src/libstd/list.rs
index 665b2d38f8f..3a7b0ffd79a 100644
--- a/src/libstd/list.rs
+++ b/src/libstd/list.rs
@@ -1,4 +1,4 @@
-#[doc = "A standard linked list"];
+//! A standard linked list
 
 import core::option;
 import option::*;
@@ -9,37 +9,37 @@ enum list<T> {
     nil,
 }
 
-#[doc = "Create a list from a vector"]
+/// Create a list from a vector
 fn from_vec<T: copy>(v: &[T]) -> @list<T> {
     vec::foldr(v, @nil::<T>, |h, t| @cons(h, t))
 }
 
-#[doc = "
-Left fold
-
-Applies `f` to `u` and the first element in the list, then applies `f` to the
-result of the previous call and the second element, and so on, returning the
-accumulated result.
-
-# Arguments
-
-* ls - The list to fold
-* z - The initial value
-* f - The function to apply
-"]
+/**
+ * Left fold
+ *
+ * Applies `f` to `u` and the first element in the list, then applies `f` to
+ * the result of the previous call and the second element, and so on,
+ * returning the accumulated result.
+ *
+ * # Arguments
+ *
+ * * ls - The list to fold
+ * * z - The initial value
+ * * f - The function to apply
+ */
 fn foldl<T: copy, U>(z: T, ls: @list<U>, f: fn(T, U) -> T) -> T {
     let mut accum: T = z;
     do iter(ls) |elt| { accum = f(accum, elt);}
     accum
 }
 
-#[doc = "
-Search for an element that matches a given predicate
-
-Apply function `f` to each element of `v`, starting from the first.
-When function `f` returns true then an option containing the element
-is returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Search for an element that matches a given predicate
+ *
+ * Apply function `f` to each element of `v`, starting from the first.
+ * When function `f` returns true then an option containing the element
+ * is returned. If `f` matches no elements then none is returned.
+ */
 fn find<T: copy>(ls: @list<T>, f: fn(T) -> bool) -> option<T> {
     let mut ls = ls;
     loop {
@@ -53,7 +53,7 @@ fn find<T: copy>(ls: @list<T>, f: fn(T) -> bool) -> option<T> {
     };
 }
 
-#[doc = "Returns true if a list contains an element with the given value"]
+/// Returns true if a list contains an element with the given value
 fn has<T: copy>(ls: @list<T>, elt: T) -> bool {
     for each(ls) |e| {
         if e == elt { ret true; }
@@ -61,7 +61,7 @@ fn has<T: copy>(ls: @list<T>, elt: T) -> bool {
     ret false;
 }
 
-#[doc = "Returns true if the list is empty"]
+/// Returns true if the list is empty
 pure fn is_empty<T: copy>(ls: @list<T>) -> bool {
     alt *ls {
         nil { true }
@@ -69,19 +69,19 @@ pure fn is_empty<T: copy>(ls: @list<T>) -> bool {
     }
 }
 
-#[doc = "Returns true if the list is not empty"]
+/// Returns true if the list is not empty
 pure fn is_not_empty<T: copy>(ls: @list<T>) -> bool {
     ret !is_empty(ls);
 }
 
-#[doc = "Returns the length of a list"]
+/// Returns the length of a list
 fn len<T>(ls: @list<T>) -> uint {
     let mut count = 0u;
     iter(ls, |_e| count += 1u);
     count
 }
 
-#[doc = "Returns all but the first element of a list"]
+/// Returns all but the first element of a list
 pure fn tail<T: copy>(ls: @list<T>) -> @list<T> {
     alt *ls {
         cons(_, tl) { ret tl; }
@@ -89,12 +89,12 @@ pure fn tail<T: copy>(ls: @list<T>) -> @list<T> {
     }
 }
 
-#[doc = "Returns the first element of a list"]
+/// Returns the first element of a list
 pure fn head<T: copy>(ls: @list<T>) -> T {
     alt check *ls { cons(hd, _) { hd } }
 }
 
-#[doc = "Appends one list to another"]
+/// Appends one list to another
 pure fn append<T: copy>(l: @list<T>, m: @list<T>) -> @list<T> {
     alt *l {
       nil { ret m; }
@@ -102,12 +102,12 @@ pure fn append<T: copy>(l: @list<T>, m: @list<T>) -> @list<T> {
     }
 }
 
-#[doc = "Push an element to the front of a list"]
+/// Push an element to the front of a list
 fn push<T: copy>(&l: list<T>, v: T) {
     l = cons(v, @l);
 }
 
-#[doc = "Iterate over a list"]
+/// Iterate over a list
 fn iter<T>(l: @list<T>, f: fn(T)) {
     let mut cur = l;
     loop {
@@ -121,7 +121,7 @@ fn iter<T>(l: @list<T>, f: fn(T)) {
     }
 }
 
-#[doc = "Iterate over a list"]
+/// Iterate over a list
 fn each<T>(l: @list<T>, f: fn(T) -> bool) {
     let mut cur = l;
     loop {
diff --git a/src/libstd/map.rs b/src/libstd/map.rs
index ddcf15257e0..46f2ca053ad 100644
--- a/src/libstd/map.rs
+++ b/src/libstd/map.rs
@@ -1,4 +1,4 @@
-#[doc = "A map type"];
+//! A map type
 
 import chained::hashmap;
 export hashmap, hashfn, eqfn, set, map, chained, hashmap, str_hash;
@@ -8,65 +8,65 @@ export hash_from_vec, hash_from_strs, hash_from_bytes;
 export hash_from_ints, hash_from_uints;
 export vec_from_set;
 
-#[doc = "
-A function that returns a hash of a value
-
-The hash should concentrate entropy in the lower bits.
-"]
+/**
+ * A function that returns a hash of a value
+ *
+ * The hash should concentrate entropy in the lower bits.
+ */
 type hashfn<K> = fn@(K) -> uint;
 
 type eqfn<K> = fn@(K, K) -> bool;
 
-#[doc = "A convenience type to treat a hashmap as a set"]
+/// A convenience type to treat a hashmap as a set
 type set<K> = hashmap<K, ()>;
 
 type hashmap<K, V> = chained::t<K, V>;
 
 iface map<K, V: copy> {
-    #[doc = "Return the number of elements in the map"]
+    /// Return the number of elements in the map
     fn size() -> uint;
 
-    #[doc = "
-    Add a value to the map.
-
-    If the map already contains a value for the specified key then the
-    original value is replaced.
-
-    Returns true if the key did not already exist in the map
-    "]
+    /**
+     * Add a value to the map.
+     *
+     * If the map already contains a value for the specified key then the
+     * original value is replaced.
+     *
+     * Returns true if the key did not already exist in the map
+     */
     fn insert(+K, +V) -> bool;
 
-    #[doc = "Returns true if the map contains a value for the specified key"]
+    /// Returns true if the map contains a value for the specified key
     fn contains_key(K) -> bool;
 
-    #[doc = "
-    Get the value for the specified key. Fails if the key does not exist in
-    the map.
-    "]
+    /**
+     * Get the value for the specified key. Fails if the key does not exist in
+     * the map.
+     */
     fn get(K) -> V;
 
-    #[doc = "Like get, but as an operator."]
+    /// Like get, but as an operator.
     fn [](K) -> V;
 
-    #[doc = "
-    Get the value for the specified key. If the key does not exist in
-    the map then returns none.
-    "]
+    /**
+     * Get the value for the specified key. If the key does not exist in
+     * the map then returns none.
+     */
     fn find(K) -> option<V>;
 
-    #[doc = "
-    Remove and return a value from the map. If the key does not exist
-    in the map then returns none.
-    "]
+    /**
+     * Remove and return a value from the map. If the key does not exist
+     * in the map then returns none.
+     */
     fn remove(K) -> option<V>;
 
-    #[doc = "Iterate over all the key/value pairs in the map"]
+    /// Iterate over all the key/value pairs in the map
     fn each(fn(K, V) -> bool);
 
-    #[doc = "Iterate over all the keys in the map"]
+    /// Iterate over all the keys in the map
     fn each_key(fn(K) -> bool);
 
-    #[doc = "Iterate over all the values in the map"]
+    /// Iterate over all the values in the map
     fn each_value(fn(V) -> bool);
 }
 
@@ -295,41 +295,37 @@ fn hashmap<K: const, V: copy>(hasher: hashfn<K>, eqer: eqfn<K>)
     chained::mk(hasher, eqer)
 }
 
-#[doc = "Construct a hashmap for string keys"]
+/// Construct a hashmap for string keys
 fn str_hash<V: copy>() -> hashmap<str, V> {
     ret hashmap(str::hash, str::eq);
 }
 
-#[doc = "Construct a hashmap for boxed string keys"]
+/// Construct a hashmap for boxed string keys
 fn box_str_hash<V: copy>() -> hashmap<@str, V> {
     ret hashmap(|x: @str| str::hash(*x), |x,y| str::eq(*x,*y));
 }
 
-#[doc = "Construct a hashmap for byte string keys"]
+/// Construct a hashmap for byte string keys
 fn bytes_hash<V: copy>() -> hashmap<~[u8], V> {
     ret hashmap(vec::u8::hash, vec::u8::eq);
 }
 
-#[doc = "Construct a hashmap for int keys"]
+/// Construct a hashmap for int keys
 fn int_hash<V: copy>() -> hashmap<int, V> {
     ret hashmap(int::hash, int::eq);
 }
 
-#[doc = "Construct a hashmap for uint keys"]
+/// Construct a hashmap for uint keys
 fn uint_hash<V: copy>() -> hashmap<uint, V> {
     ret hashmap(uint::hash, uint::eq);
 }
 
-#[doc = "
-Convenience function for adding keys to a hashmap with nil type keys
-"]
+/// Convenience function for adding keys to a hashmap with nil type keys
 fn set_add<K: const copy>(set: set<K>, key: K) -> bool {
     ret set.insert(key, ());
 }
 
-#[doc = "
-Convert a set into a vector.
-"]
+/// Convert a set into a vector.
 fn vec_from_set<T: copy>(s: set<T>) -> ~[T] {
     let mut v = ~[];
     do s.each_key() |k| {
@@ -339,7 +335,7 @@ fn vec_from_set<T: copy>(s: set<T>) -> ~[T] {
     v
 }
 
-#[doc = "Construct a hashmap from a vector"]
+/// Construct a hashmap from a vector
 fn hash_from_vec<K: const copy, V: copy>(hasher: hashfn<K>, eqer: eqfn<K>,
                                          items: ~[(K, V)]) -> hashmap<K, V> {
     let map = hashmap(hasher, eqer);
@@ -350,22 +346,22 @@ fn hash_from_vec<K: const copy, V: copy>(hasher: hashfn<K>, eqer: eqfn<K>,
     map
 }
 
-#[doc = "Construct a hashmap from a vector with string keys"]
+/// Construct a hashmap from a vector with string keys
 fn hash_from_strs<V: copy>(items: ~[(str, V)]) -> hashmap<str, V> {
     hash_from_vec(str::hash, str::eq, items)
 }
 
-#[doc = "Construct a hashmap from a vector with byte keys"]
+/// Construct a hashmap from a vector with byte keys
 fn hash_from_bytes<V: copy>(items: ~[(~[u8], V)]) -> hashmap<~[u8], V> {
     hash_from_vec(vec::u8::hash, vec::u8::eq, items)
 }
 
-#[doc = "Construct a hashmap from a vector with int keys"]
+/// Construct a hashmap from a vector with int keys
 fn hash_from_ints<V: copy>(items: ~[(int, V)]) -> hashmap<int, V> {
     hash_from_vec(int::hash, int::eq, items)
 }
 
-#[doc = "Construct a hashmap from a vector with uint keys"]
+/// Construct a hashmap from a vector with uint keys
 fn hash_from_uints<V: copy>(items: ~[(uint, V)]) -> hashmap<uint, V> {
     hash_from_vec(uint::hash, uint::eq, items)
 }
diff --git a/src/libstd/net.rs b/src/libstd/net.rs
index 11425c2b612..8b71de2632e 100644
--- a/src/libstd/net.rs
+++ b/src/libstd/net.rs
@@ -1,6 +1,4 @@
-#[doc="
-Top-level module for network-related functionality
-"];
+//! Top-level module for network-related functionality
 
 import tcp = net_tcp;
 export tcp;
diff --git a/src/libstd/net_ip.rs b/src/libstd/net_ip.rs
index bd1266e10d3..2353a983dc2 100644
--- a/src/libstd/net_ip.rs
+++ b/src/libstd/net_ip.rs
@@ -1,6 +1,4 @@
-#[doc="
-Types/fns concerning Internet Protocol (IP), versions 4 & 6
-"];
+//! Types/fns concerning Internet Protocol (IP), versions 4 & 6
 
 import vec;
 import uint;
@@ -28,27 +26,25 @@ export format_addr;
 export v4, v6;
 export get_addr;
 
-#[doc = "An IP address"]
+/// An IP address
 enum ip_addr {
-    #[doc="An IPv4 address"]
+    /// An IPv4 address
     ipv4(sockaddr_in),
     ipv6(sockaddr_in6)
 }
 
-#[doc="
-Human-friendly feedback on why a parse_addr attempt failed
-"]
+/// Human-friendly feedback on why a parse_addr attempt failed
 type parse_addr_err = {
     err_msg: str
 };
 
-#[doc="
-Convert a `ip_addr` to a str
-
-# Arguments
-
-* ip - a `std::net::ip::ip_addr`
-"]
+/**
+ * Convert a `ip_addr` to a str
+ *
+ * # Arguments
+ *
+ * * ip - a `std::net::ip::ip_addr`
+ */
 fn format_addr(ip: ip_addr) -> str {
     alt ip {
       ipv4(addr) {
@@ -72,27 +68,25 @@ fn format_addr(ip: ip_addr) -> str {
     }
 }
 
-#[doc="
-Represents errors returned from `net::ip::get_addr()`
-"]
+/// Represents errors returned from `net::ip::get_addr()`
 enum ip_get_addr_err {
     get_addr_unknown_error
 }
 
-#[doc="
-Attempts name resolution on the provided `node` string
-
-# Arguments
-
-* `node` - a string representing some host address
-* `iotask` - a `uv::iotask` used to interact with the underlying event loop
-
-# Returns
-
-A `result<[ip_addr]/~, ip_get_addr_err>` instance that will contain
-a vector of `ip_addr` results, in the case of success, or an error
-object in the case of failure
-"]
+/**
+ * Attempts name resolution on the provided `node` string
+ *
+ * # Arguments
+ *
+ * * `node` - a string representing some host address
+ * * `iotask` - a `uv::iotask` used to interact with the underlying event loop
+ *
+ * # Returns
+ *
+ * A `result<[ip_addr]/~, ip_get_addr_err>` instance that will contain
+ * a vector of `ip_addr` results, in the case of success, or an error
+ * object in the case of failure
+ */
 fn get_addr(++node: str, iotask: iotask)
         -> result::result<[ip_addr]/~, ip_get_addr_err> unsafe {
     do comm::listen |output_ch| {
@@ -127,21 +121,21 @@ fn get_addr(++node: str, iotask: iotask)
 }
 
 mod v4 {
-    #[doc = "
-    Convert a str to `ip_addr`
-
-    # Failure
-
-    Fails if the string is not a valid IPv4 address
-
-    # Arguments
-
-    * ip - a string of the format `x.x.x.x`
-
-    # Returns
-
-    * an `ip_addr` of the `ipv4` variant
-    "]
+    /**
+     * Convert a str to `ip_addr`
+     *
+     * # Failure
+     *
+     * Fails if the string is not a valid IPv4 address
+     *
+     * # Arguments
+     *
+     * * ip - a string of the format `x.x.x.x`
+     *
+     * # Returns
+     *
+     * * an `ip_addr` of the `ipv4` variant
+     */
     fn parse_addr(ip: str) -> ip_addr {
         alt try_parse_addr(ip) {
           result::ok(addr) { copy(addr) }
@@ -210,21 +204,21 @@ mod v4 {
     }
 }
 mod v6 {
-    #[doc = "
-    Convert a str to `ip_addr`
-
-    # Failure
-
-    Fails if the string is not a valid IPv6 address
-
-    # Arguments
-
-    * ip - an ipv6 string. See RFC2460 for spec.
-
-    # Returns
-
-    * an `ip_addr` of the `ipv6` variant
-    "]
+    /**
+     * Convert a str to `ip_addr`
+     *
+     * # Failure
+     *
+     * Fails if the string is not a valid IPv6 address
+     *
+     * # Arguments
+     *
+     * * ip - an ipv6 string. See RFC2460 for spec.
+     *
+     * # Returns
+     *
+     * * an `ip_addr` of the `ipv6` variant
+     */
     fn parse_addr(ip: str) -> ip_addr {
         alt try_parse_addr(ip) {
           result::ok(addr) { copy(addr) }
diff --git a/src/libstd/net_tcp.rs b/src/libstd/net_tcp.rs
index c29c3349f76..128490048db 100644
--- a/src/libstd/net_tcp.rs
+++ b/src/libstd/net_tcp.rs
@@ -1,6 +1,4 @@
-#[doc="
-High-level interface to libuv's TCP functionality
-"];
+//! High-level interface to libuv's TCP functionality
 
 import ip = net_ip;
 import uv::iotask;
@@ -34,13 +32,13 @@ extern mod rustrt {
     fn rust_uv_helper_uv_tcp_t_size() -> libc::c_uint;
 }
 
-#[doc="
-Encapsulates an open TCP/IP connection through libuv
-
-`tcp_socket` is non-copyable/sendable and automagically handles closing the
-underlying libuv data structures when it goes out of scope. This is the
-data structure that is used for read/write operations over a TCP stream.
-"]
+/**
+ * Encapsulates an open TCP/IP connection through libuv
+ *
+ * `tcp_socket` is non-copyable/sendable and automagically handles closing the
+ * underlying libuv data structures when it goes out of scope. This is the
+ * data structure that is used for read/write operations over a TCP stream.
+ */
 class tcp_socket {
   let socket_data: @tcp_socket_data;
   new(socket_data: @tcp_socket_data) { self.socket_data = socket_data; }
@@ -51,84 +49,76 @@ class tcp_socket {
   }
 }
 
-#[doc="
-A buffered wrapper for `net::tcp::tcp_socket`
-
-It is created with a call to `net::tcp::socket_buf()` and has impls that
-satisfy both the `io::reader` and `io::writer` ifaces.
-"]
+/**
+ * A buffered wrapper for `net::tcp::tcp_socket`
+ *
+ * It is created with a call to `net::tcp::socket_buf()` and has impls that
+ * satisfy both the `io::reader` and `io::writer` ifaces.
+ */
 class tcp_socket_buf {
   let data: @tcp_buffered_socket_data;
   new(data: @tcp_buffered_socket_data) { self.data = data; }
 }
 
-#[doc="
-Contains raw, string-based, error information returned from libuv
-"]
+/// Contains raw, string-based, error information returned from libuv
 type tcp_err_data = {
     err_name: str,
     err_msg: str
 };
-#[doc="
-Details returned as part of a `result::err` result from `tcp::listen`
-"]
+/// Details returned as part of a `result::err` result from `tcp::listen`
 enum tcp_listen_err_data {
-    #[doc="
-    Some unplanned-for error. The first and second fields correspond
-    to libuv's `err_name` and `err_msg` fields, respectively.
-    "]
+    /**
+     * Some unplanned-for error. The first and second fields correspond
+     * to libuv's `err_name` and `err_msg` fields, respectively.
+     */
     generic_listen_err(str, str),
-    #[doc="
-    Failed to bind to the requested IP/Port, because it is already in use.
-
-    # Possible Causes
-
-    * Attempting to bind to a port already bound to another listener
-    "]
+    /**
+     * Failed to bind to the requested IP/Port, because it is already in use.
+     *
+     * # Possible Causes
+     *
+     * * Attempting to bind to a port already bound to another listener
+     */
     address_in_use,
-    #[doc="
-    Request to bind to an IP/Port was denied by the system.
-
-    # Possible Causes
-
-    * Attemping to binding to an IP/Port as a non-Administrator
-      on Windows Vista+
-    * Attempting to bind, as a non-priv'd
-      user, to 'privileged' ports (< 1024) on *nix
-    "]
+    /**
+     * Request to bind to an IP/Port was denied by the system.
+     *
+     * # Possible Causes
+     *
+     * * Attemping to binding to an IP/Port as a non-Administrator
+     *   on Windows Vista+
+     * * Attempting to bind, as a non-priv'd
+     *   user, to 'privileged' ports (< 1024) on *nix
+     */
     access_denied
 }
-#[doc="
-Details returned as part of a `result::err` result from `tcp::connect`
-"]
+/// Details returned as part of a `result::err` result from `tcp::connect`
 enum tcp_connect_err_data {
-    #[doc="
-    Some unplanned-for error. The first and second fields correspond
-    to libuv's `err_name` and `err_msg` fields, respectively.
-    "]
+    /**
+     * Some unplanned-for error. The first and second fields correspond
+     * to libuv's `err_name` and `err_msg` fields, respectively.
+     */
     generic_connect_err(str, str),
-    #[doc="
-    Invalid IP or invalid port
-    "]
+    /// Invalid IP or invalid port
     connection_refused
 }
 
-#[doc="
-Initiate a client connection over TCP/IP
-
-# Arguments
-
-* `input_ip` - The IP address (versions 4 or 6) of the remote host
-* `port` - the unsigned integer of the desired remote host port
-* `iotask` - a `uv::iotask` that the tcp request will run on
-
-# Returns
-
-A `result` that, if the operation succeeds, contains a `net::net::tcp_socket`
-that can be used to send and receive data to/from the remote host. In the
-event of failure, a `net::tcp::tcp_connect_err_data` instance will be
-returned
-"]
+/**
+ * Initiate a client connection over TCP/IP
+ *
+ * # Arguments
+ *
+ * * `input_ip` - The IP address (versions 4 or 6) of the remote host
+ * * `port` - the unsigned integer of the desired remote host port
+ * * `iotask` - a `uv::iotask` that the tcp request will run on
+ *
+ * # Returns
+ *
+ * A `result` that, if the operation succeeds, contains a
+ * `net::net::tcp_socket` that can be used to send and receive data to/from
+ * the remote host. In the event of failure, a
+ * `net::tcp::tcp_connect_err_data` instance will be returned
+ */
 fn connect(-input_ip: ip::ip_addr, port: uint,
            iotask: iotask)
     -> result::result<tcp_socket, tcp_connect_err_data> unsafe {
@@ -252,56 +242,57 @@ fn connect(-input_ip: ip::ip_addr, port: uint,
     }
 }
 
-#[doc="
-Write binary data to a tcp stream; Blocks until operation completes
-
-# Arguments
-
-* sock - a `tcp_socket` to write to
-* raw_write_data - a vector of `[u8]/~` that will be written to the stream.
-This value must remain valid for the duration of the `write` call
-
-# Returns
-
-A `result` object with a `nil` value as the `ok` variant, or a `tcp_err_data`
-value as the `err` variant
-"]
+/**
+ * Write binary data to a tcp stream; Blocks until operation completes
+ *
+ * # Arguments
+ *
+ * * sock - a `tcp_socket` to write to
+ * * raw_write_data - a vector of `[u8]/~` that will be written to the stream.
+ * This value must remain valid for the duration of the `write` call
+ *
+ * # Returns
+ *
+ * A `result` object with a `nil` value as the `ok` variant, or a
+ * `tcp_err_data` value as the `err` variant
+ */
 fn write(sock: tcp_socket, raw_write_data: ~[u8])
     -> result::result<(), tcp_err_data> unsafe {
     let socket_data_ptr = ptr::addr_of(*(sock.socket_data));
     write_common_impl(socket_data_ptr, raw_write_data)
 }
 
-#[doc="
-Write binary data to tcp stream; Returns a `future::future` value immediately
-
-# Safety
-
-This function can produce unsafe results if:
-
-1. the call to `write_future` is made
-2. the `future::future` value returned is never resolved via
-`future::get`
-3. and then the `tcp_socket` passed in to `write_future` leaves
-scope and is destructed before the task that runs the libuv write
-operation completes.
-
-As such: If using `write_future`, always be sure to resolve the returned
-`future` so as to ensure libuv doesn't try to access a released write handle.
-Otherwise, use the blocking `tcp::write` function instead.
-
-# Arguments
-
-* sock - a `tcp_socket` to write to
-* raw_write_data - a vector of `[u8]/~` that will be written to the stream.
-This value must remain valid for the duration of the `write` call
-
-# Returns
-
-A `future` value that, once the `write` operation completes, resolves to a
-`result` object with a `nil` value as the `ok` variant, or a `tcp_err_data`
-value as the `err` variant
-"]
+/**
+ * Write binary data to tcp stream; Returns a `future::future` value
+ * immediately
+ *
+ * # Safety
+ *
+ * This function can produce unsafe results if:
+ *
+ * 1. the call to `write_future` is made
+ * 2. the `future::future` value returned is never resolved via
+ * `future::get`
+ * 3. and then the `tcp_socket` passed in to `write_future` leaves
+ * scope and is destructed before the task that runs the libuv write
+ * operation completes.
+ *
+ * As such: If using `write_future`, always be sure to resolve the returned
+ * `future` so as to ensure libuv doesn't try to access a released write
+ * handle. Otherwise, use the blocking `tcp::write` function instead.
+ *
+ * # Arguments
+ *
+ * * sock - a `tcp_socket` to write to
+ * * raw_write_data - a vector of `[u8]/~` that will be written to the stream.
+ * This value must remain valid for the duration of the `write` call
+ *
+ * # Returns
+ *
+ * A `future` value that, once the `write` operation completes, resolves to a
+ * `result` object with a `nil` value as the `ok` variant, or a `tcp_err_data`
+ * value as the `err` variant
+ */
 fn write_future(sock: tcp_socket, raw_write_data: ~[u8])
     -> future::future<result::result<(), tcp_err_data>> unsafe {
     let socket_data_ptr = ptr::addr_of(*(sock.socket_data));
@@ -311,19 +302,20 @@ fn write_future(sock: tcp_socket, raw_write_data: ~[u8])
     }
 }
 
-#[doc="
-Begin reading binary data from an open TCP connection; used with `read_stop`
-
-# Arguments
-
-* sock -- a `net::tcp::tcp_socket` for the connection to read from
-
-# Returns
-
-* A `result` instance that will either contain a
-`comm::port<tcp_read_result>` that the user can read (and optionally, loop
-on) from until `read_stop` is called, or a `tcp_err_data` record
-"]
+/**
+ * Begin reading binary data from an open TCP connection; used with
+ * `read_stop`
+ *
+ * # Arguments
+ *
+ * * sock -- a `net::tcp::tcp_socket` for the connection to read from
+ *
+ * # Returns
+ *
+ * * A `result` instance that will either contain a
+ * `comm::port<tcp_read_result>` that the user can read (and optionally, loop
+ * on) from until `read_stop` is called, or a `tcp_err_data` record
+ */
 fn read_start(sock: tcp_socket)
     -> result::result<comm::port<
         result::result<~[u8], tcp_err_data>>, tcp_err_data> unsafe {
@@ -331,13 +323,13 @@ fn read_start(sock: tcp_socket)
     read_start_common_impl(socket_data)
 }
 
-#[doc="
-Stop reading from an open TCP connection; used with `read_start`
-
-# Arguments
-
-* `sock` - a `net::tcp::tcp_socket` that you wish to stop reading on
-"]
+/**
+ * Stop reading from an open TCP connection; used with `read_start`
+ *
+ * # Arguments
+ *
+ * * `sock` - a `net::tcp::tcp_socket` that you wish to stop reading on
+ */
 fn read_stop(sock: tcp_socket,
              -read_port: comm::port<result::result<[u8]/~, tcp_err_data>>) ->
     result::result<(), tcp_err_data> unsafe {
@@ -346,54 +338,56 @@ fn read_stop(sock: tcp_socket,
     read_stop_common_impl(socket_data)
 }
 
-#[doc="
-Reads a single chunk of data from `tcp_socket`; block until data/error recv'd
-
-Does a blocking read operation for a single chunk of data from a `tcp_socket`
-until a data arrives or an error is received. The provided `timeout_msecs`
-value is used to raise an error if the timeout period passes without any
-data received.
-
-# Arguments
-
-* `sock` - a `net::tcp::tcp_socket` that you wish to read from
-* `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
-read attempt. Pass `0u` to wait indefinitely
-"]
+/**
+ * Reads a single chunk of data from `tcp_socket`; block until data/error
+ * recv'd
+ *
+ * Does a blocking read operation for a single chunk of data from a
+ * `tcp_socket` until a data arrives or an error is received. The provided
+ * `timeout_msecs` value is used to raise an error if the timeout period
+ * passes without any data received.
+ *
+ * # Arguments
+ *
+ * * `sock` - a `net::tcp::tcp_socket` that you wish to read from
+ * * `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
+ * read attempt. Pass `0u` to wait indefinitely
+ */
 fn read(sock: tcp_socket, timeout_msecs: uint)
     -> result::result<~[u8],tcp_err_data> {
     let socket_data = ptr::addr_of(*(sock.socket_data));
     read_common_impl(socket_data, timeout_msecs)
 }
 
-#[doc="
-Reads a single chunk of data; returns a `future::future<[u8]/~>` immediately
-
-Does a non-blocking read operation for a single chunk of data from a
-`tcp_socket` and immediately returns a `future` value representing the
-result. When resolving the returned `future`, it will block until data
-arrives or an error is received. The provided `timeout_msecs`
-value is used to raise an error if the timeout period passes without any
-data received.
-
-# Safety
-
-This function can produce unsafe results if the call to `read_future` is
-made, the `future::future` value returned is never resolved via
-`future::get`, and then the `tcp_socket` passed in to `read_future` leaves
-scope and is destructed before the task that runs the libuv read
-operation completes.
-
-As such: If using `read_future`, always be sure to resolve the returned
-`future` so as to ensure libuv doesn't try to access a released read handle.
-Otherwise, use the blocking `tcp::read` function instead.
-
-# Arguments
-
-* `sock` - a `net::tcp::tcp_socket` that you wish to read from
-* `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
-read attempt. Pass `0u` to wait indefinitely
-"]
+/**
+ * Reads a single chunk of data; returns a `future::future<[u8]/~>`
+ * immediately
+ *
+ * Does a non-blocking read operation for a single chunk of data from a
+ * `tcp_socket` and immediately returns a `future` value representing the
+ * result. When resolving the returned `future`, it will block until data
+ * arrives or an error is received. The provided `timeout_msecs`
+ * value is used to raise an error if the timeout period passes without any
+ * data received.
+ *
+ * # Safety
+ *
+ * This function can produce unsafe results if the call to `read_future` is
+ * made, the `future::future` value returned is never resolved via
+ * `future::get`, and then the `tcp_socket` passed in to `read_future` leaves
+ * scope and is destructed before the task that runs the libuv read
+ * operation completes.
+ *
+ * As such: If using `read_future`, always be sure to resolve the returned
+ * `future` so as to ensure libuv doesn't try to access a released read
+ * handle. Otherwise, use the blocking `tcp::read` function instead.
+ *
+ * # Arguments
+ *
+ * * `sock` - a `net::tcp::tcp_socket` that you wish to read from
+ * * `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
+ * read attempt. Pass `0u` to wait indefinitely
+ */
 fn read_future(sock: tcp_socket, timeout_msecs: uint)
     -> future::future<result::result<~[u8],tcp_err_data>> {
     let socket_data = ptr::addr_of(*(sock.socket_data));
@@ -402,75 +396,75 @@ fn read_future(sock: tcp_socket, timeout_msecs: uint)
     }
 }
 
-#[doc="
-Bind an incoming client connection to a `net::tcp::tcp_socket`
-
-# Notes
-
-It is safe to call `net::tcp::accept` _only_ within the context of the
-`new_connect_cb` callback provided as the final argument to the
-`net::tcp::listen` function.
-
-The `new_conn` opaque value is provided _only_ as the first argument to the
-`new_connect_cb` provided as a part of `net::tcp::listen`.
-It can be safely sent to another task but it _must_ be
-used (via `net::tcp::accept`) before the `new_connect_cb` call it was
-provided to returns.
-
-This implies that a port/chan pair must be used to make sure that the
-`new_connect_cb` call blocks until an attempt to create a
-`net::tcp::tcp_socket` is completed.
-
-# Example
-
-Here, the `new_conn` is used in conjunction with `accept` from within
-a task spawned by the `new_connect_cb` passed into `listen`
-
-~~~~~~~~~~~
-net::tcp::listen(remote_ip, remote_port, backlog)
-    // this callback is ran once after the connection is successfully
-    // set up
-    {|kill_ch|
-      // pass the kill_ch to your main loop or wherever you want
-      // to be able to externally kill the server from
-    }
-    // this callback is ran when a new connection arrives
-    {|new_conn, kill_ch|
-    let cont_po = comm::port::<option<tcp_err_data>>();
-    let cont_ch = comm::chan(cont_po);
-    task::spawn {||
-        let accept_result = net::tcp::accept(new_conn);
-        if accept_result.is_err() {
-            comm::send(cont_ch, result::get_err(accept_result));
-            // fail?
-        }
-        else {
-            let sock = result::get(accept_result);
-            comm::send(cont_ch, true);
-            // do work here
-        }
-    };
-    alt comm::recv(cont_po) {
-      // shut down listen()
-      some(err_data) { comm::send(kill_chan, some(err_data)) }
-      // wait for next connection
-      none {}
-    }
-};
-~~~~~~~~~~~
-
-# Arguments
-
-* `new_conn` - an opaque value used to create a new `tcp_socket`
-
-# Returns
-
-On success, this function will return a `net::tcp::tcp_socket` as the
-`ok` variant of a `result`. The `net::tcp::tcp_socket` is anchored within
-the task that `accept` was called within for its lifetime. On failure,
-this function will return a `net::tcp::tcp_err_data` record
-as the `err` variant of a `result`.
-"]
+/**
+ * Bind an incoming client connection to a `net::tcp::tcp_socket`
+ *
+ * # Notes
+ *
+ * It is safe to call `net::tcp::accept` _only_ within the context of the
+ * `new_connect_cb` callback provided as the final argument to the
+ * `net::tcp::listen` function.
+ *
+ * The `new_conn` opaque value is provided _only_ as the first argument to the
+ * `new_connect_cb` provided as a part of `net::tcp::listen`.
+ * It can be safely sent to another task but it _must_ be
+ * used (via `net::tcp::accept`) before the `new_connect_cb` call it was
+ * provided to returns.
+ *
+ * This implies that a port/chan pair must be used to make sure that the
+ * `new_connect_cb` call blocks until an attempt to create a
+ * `net::tcp::tcp_socket` is completed.
+ *
+ * # Example
+ *
+ * Here, the `new_conn` is used in conjunction with `accept` from within
+ * a task spawned by the `new_connect_cb` passed into `listen`
+ *
+ * ~~~~~~~~~~~
+ * net::tcp::listen(remote_ip, remote_port, backlog)
+ *     // this callback is ran once after the connection is successfully
+ *     // set up
+ *     {|kill_ch|
+ *       // pass the kill_ch to your main loop or wherever you want
+ *       // to be able to externally kill the server from
+ *     }
+ *     // this callback is ran when a new connection arrives
+ *     {|new_conn, kill_ch|
+ *     let cont_po = comm::port::<option<tcp_err_data>>();
+ *     let cont_ch = comm::chan(cont_po);
+ *     task::spawn {||
+ *         let accept_result = net::tcp::accept(new_conn);
+ *         if accept_result.is_err() {
+ *             comm::send(cont_ch, result::get_err(accept_result));
+ *             // fail?
+ *         }
+ *         else {
+ *             let sock = result::get(accept_result);
+ *             comm::send(cont_ch, true);
+ *             // do work here
+ *         }
+ *     };
+ *     alt comm::recv(cont_po) {
+ *       // shut down listen()
+ *       some(err_data) { comm::send(kill_chan, some(err_data)) }
+ *       // wait for next connection
+ *       none {}
+ *     }
+ * };
+ * ~~~~~~~~~~~
+ *
+ * # Arguments
+ *
+ * * `new_conn` - an opaque value used to create a new `tcp_socket`
+ *
+ * # Returns
+ *
+ * On success, this function will return a `net::tcp::tcp_socket` as the
+ * `ok` variant of a `result`. The `net::tcp::tcp_socket` is anchored within
+ * the task that `accept` was called within for its lifetime. On failure,
+ * this function will return a `net::tcp::tcp_err_data` record
+ * as the `err` variant of a `result`.
+ */
 fn accept(new_conn: tcp_new_connection)
     -> result::result<tcp_socket, tcp_err_data> unsafe {
 
@@ -545,34 +539,34 @@ fn accept(new_conn: tcp_new_connection)
     }
 }
 
-#[doc="
-Bind to a given IP/port and listen for new connections
-
-# Arguments
-
-* `host_ip` - a `net::ip::ip_addr` representing a unique IP
-(versions 4 or 6)
-* `port` - a uint representing the port to listen on
-* `backlog` - a uint representing the number of incoming connections
-to cache in memory
-* `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
-* `on_establish_cb` - a callback that is evaluated if/when the listener
-is successfully established. it takes no parameters
-* `new_connect_cb` - a callback to be evaluated, on the libuv thread,
-whenever a client attempts to conect on the provided ip/port. the
-callback's arguments are:
-    * `new_conn` - an opaque type that can be passed to
-    `net::tcp::accept` in order to be converted to a `tcp_socket`.
-    * `kill_ch` - channel of type `comm::chan<option<tcp_err_data>>`. this
-    channel can be used to send a message to cause `listen` to begin
-    closing the underlying libuv data structures.
-
-# returns
-
-a `result` instance containing empty data of type `()` on a
-successful/normal shutdown, and a `tcp_listen_err_data` enum in the event
-of listen exiting because of an error
-"]
+/**
+ * Bind to a given IP/port and listen for new connections
+ *
+ * # Arguments
+ *
+ * * `host_ip` - a `net::ip::ip_addr` representing a unique IP
+ * (versions 4 or 6)
+ * * `port` - a uint representing the port to listen on
+ * * `backlog` - a uint representing the number of incoming connections
+ * to cache in memory
+ * * `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
+ * * `on_establish_cb` - a callback that is evaluated if/when the listener
+ * is successfully established. it takes no parameters
+ * * `new_connect_cb` - a callback to be evaluated, on the libuv thread,
+ * whenever a client attempts to conect on the provided ip/port. the
+ * callback's arguments are:
+ *     * `new_conn` - an opaque type that can be passed to
+ *     `net::tcp::accept` in order to be converted to a `tcp_socket`.
+ *     * `kill_ch` - channel of type `comm::chan<option<tcp_err_data>>`. this
+ *     channel can be used to send a message to cause `listen` to begin
+ *     closing the underlying libuv data structures.
+ *
+ * # returns
+ *
+ * a `result` instance containing empty data of type `()` on a
+ * successful/normal shutdown, and a `tcp_listen_err_data` enum in the event
+ * of listen exiting because of an error
+ */
 fn listen(-host_ip: ip::ip_addr, port: uint, backlog: uint,
           iotask: iotask,
           on_establish_cb: fn~(comm::chan<option<tcp_err_data>>),
@@ -721,28 +715,26 @@ fn listen_common(-host_ip: ip::ip_addr, port: uint, backlog: uint,
     }
 }
 
-#[doc="
-Convert a `net::tcp::tcp_socket` to a `net::tcp::tcp_socket_buf`.
-
-This function takes ownership of a `net::tcp::tcp_socket`, returning it
-stored within a buffered wrapper, which can be converted to a `io::reader`
-or `io::writer`
-
-# Arguments
-
-* `sock` -- a `net::tcp::tcp_socket` that you want to buffer
-
-# Returns
-
-A buffered wrapper that you can cast as an `io::reader` or `io::writer`
-"]
+/**
+ * Convert a `net::tcp::tcp_socket` to a `net::tcp::tcp_socket_buf`.
+ *
+ * This function takes ownership of a `net::tcp::tcp_socket`, returning it
+ * stored within a buffered wrapper, which can be converted to a `io::reader`
+ * or `io::writer`
+ *
+ * # Arguments
+ *
+ * * `sock` -- a `net::tcp::tcp_socket` that you want to buffer
+ *
+ * # Returns
+ *
+ * A buffered wrapper that you can cast as an `io::reader` or `io::writer`
+ */
 fn socket_buf(-sock: tcp_socket) -> tcp_socket_buf {
     tcp_socket_buf(@{ sock: sock, mut buf: []/~ })
 }
 
-#[doc="
-Convenience methods extending `net::tcp::tcp_socket`
-"]
+/// Convenience methods extending `net::tcp::tcp_socket`
 impl tcp_socket for tcp_socket {
     fn read_start() -> result::result<comm::port<
         result::result<~[u8], tcp_err_data>>, tcp_err_data> {
@@ -771,9 +763,7 @@ impl tcp_socket for tcp_socket {
     }
 }
 
-#[doc="
-Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
-"]
+/// Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
 impl tcp_socket_buf of io::reader for @tcp_socket_buf {
     fn read_bytes(amt: uint) -> [u8]/~ {
         let has_amt_available =
@@ -819,9 +809,7 @@ impl tcp_socket_buf of io::reader for @tcp_socket_buf {
     }
 }
 
-#[doc="
-Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
-"]
+/// Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
 impl tcp_socket_buf of io::writer for @tcp_socket_buf {
     fn write(data: [const u8]/&) unsafe {
         let socket_data_ptr =
diff --git a/src/libstd/par.rs b/src/libstd/par.rs
index 167eded03cb..9bf6a021282 100644
--- a/src/libstd/par.rs
+++ b/src/libstd/par.rs
@@ -8,18 +8,22 @@ import core::vec::extensions;
 
 export map, mapi, alli, any, mapi_factory;
 
-#[doc="The maximum number of tasks this module will spawn for a single
-operation."]
+/**
+ * The maximum number of tasks this module will spawn for a single
+ * operation.
+ */
 const max_tasks : uint = 32u;
 
-#[doc="The minimum number of elements each task will process."]
+/// The minimum number of elements each task will process.
 const min_granularity : uint = 1024u;
 
-#[doc="An internal helper to map a function over a large vector and
-return the intermediate results.
-
-This is used to build most of the other parallel vector functions,
-like map or alli."]
+/**
+ * An internal helper to map a function over a large vector and
+ * return the intermediate results.
+ *
+ * This is used to build most of the other parallel vector functions,
+ * like map or alli.
+ */
 fn map_slices<A: copy send, B: copy send>(
     xs: ~[A],
     f: fn() -> fn~(uint, v: &[A]) -> B)
@@ -75,7 +79,7 @@ fn map_slices<A: copy send, B: copy send>(
     }
 }
 
-#[doc="A parallel version of map."]
+/// A parallel version of map.
 fn map<A: copy send, B: copy send>(xs: ~[A], f: fn~(A) -> B) -> ~[B] {
     vec::concat(map_slices(xs, || {
         fn~(_base: uint, slice : &[A], copy f) -> ~[B] {
@@ -84,7 +88,7 @@ fn map<A: copy send, B: copy send>(xs: ~[A], f: fn~(A) -> B) -> ~[B] {
     }))
 }
 
-#[doc="A parallel version of mapi."]
+/// A parallel version of mapi.
 fn mapi<A: copy send, B: copy send>(xs: ~[A],
                                     f: fn~(uint, A) -> B) -> ~[B] {
     let slices = map_slices(xs, || {
@@ -100,10 +104,12 @@ fn mapi<A: copy send, B: copy send>(xs: ~[A],
     r
 }
 
-#[doc="A parallel version of mapi.
-
-In this case, f is a function that creates functions to run over the
-inner elements. This is to skirt the need for copy constructors."]
+/**
+ * A parallel version of mapi.
+ *
+ * In this case, f is a function that creates functions to run over the
+ * inner elements. This is to skirt the need for copy constructors.
+ */
 fn mapi_factory<A: copy send, B: copy send>(
     xs: ~[A], f: fn() -> fn~(uint, A) -> B) -> ~[B] {
     let slices = map_slices(xs, || {
@@ -120,7 +126,7 @@ fn mapi_factory<A: copy send, B: copy send>(
     r
 }
 
-#[doc="Returns true if the function holds for all elements in the vector."]
+/// Returns true if the function holds for all elements in the vector.
 fn alli<A: copy send>(xs: ~[A], f: fn~(uint, A) -> bool) -> bool {
     do vec::all(map_slices(xs, || {
         fn~(base: uint, slice : &[A], copy f) -> bool {
@@ -131,7 +137,7 @@ fn alli<A: copy send>(xs: ~[A], f: fn~(uint, A) -> bool) -> bool {
     })) |x| { x }
 }
 
-#[doc="Returns true if the function holds for any elements in the vector."]
+/// Returns true if the function holds for any elements in the vector.
 fn any<A: copy send>(xs: ~[A], f: fn~(A) -> bool) -> bool {
     do vec::any(map_slices(xs, || {
         fn~(_base : uint, slice: &[A], copy f) -> bool {
diff --git a/src/libstd/rope.rs b/src/libstd/rope.rs
index a7d54daba9a..1a90612869b 100644
--- a/src/libstd/rope.rs
+++ b/src/libstd/rope.rs
@@ -1,84 +1,84 @@
-#[doc = "
-High-level text containers.
-
-Ropes are a high-level representation of text that offers
-much better performance than strings for common operations,
-and generally reduce memory allocations and copies, while only
-entailing a small degradation of less common operations.
-
-More precisely, where a string is represented as a memory buffer,
-a rope is a tree structure whose leaves are slices of immutable
-strings. Therefore, concatenation, appending, prepending, substrings,
-etc. are operations that require only trivial tree manipulation,
-generally without having to copy memory. In addition, the tree
-structure of ropes makes them suitable as a form of index to speed-up
-access to Unicode characters by index in long chunks of text.
-
-The following operations are algorithmically faster in ropes:
-
-* extracting a subrope is logarithmic (linear in strings);
-* appending/prepending is near-constant time (linear in strings);
-* concatenation is near-constant time (linear in strings);
-* char length is constant-time (linear in strings);
-* access to a character by index is logarithmic (linear in strings);
-"];
+/*!
+ * High-level text containers.
+ *
+ * Ropes are a high-level representation of text that offers
+ * much better performance than strings for common operations,
+ * and generally reduce memory allocations and copies, while only
+ * entailing a small degradation of less common operations.
+ *
+ * More precisely, where a string is represented as a memory buffer,
+ * a rope is a tree structure whose leaves are slices of immutable
+ * strings. Therefore, concatenation, appending, prepending, substrings,
+ * etc. are operations that require only trivial tree manipulation,
+ * generally without having to copy memory. In addition, the tree
+ * structure of ropes makes them suitable as a form of index to speed-up
+ * access to Unicode characters by index in long chunks of text.
+ *
+ * The following operations are algorithmically faster in ropes:
+ *
+ * * extracting a subrope is logarithmic (linear in strings);
+ * * appending/prepending is near-constant time (linear in strings);
+ * * concatenation is near-constant time (linear in strings);
+ * * char length is constant-time (linear in strings);
+ * * access to a character by index is logarithmic (linear in strings);
+ */
 
 
-#[doc = "The type of ropes."]
+/// The type of ropes.
 type rope = node::root;
 
 /*
  Section: Creating a rope
  */
 
-#[doc = "Create an empty rope"]
+/// Create an empty rope
 fn empty() -> rope {
    ret node::empty;
 }
 
-#[doc = "
-Adopt a string as a rope.
-
-# Arguments
-
-* str - A valid string.
-
-# Return value
-
-A rope representing the same string as `str`. Depending of the length
-of `str`, this rope may be empty, flat or complex.
-
-# Performance notes
-
-* this operation does not copy the string;
-* the function runs in linear time.
-"]
+/**
+ * Adopt a string as a rope.
+ *
+ * # Arguments
+ *
+ * * str - A valid string.
+ *
+ * # Return value
+ *
+ * A rope representing the same string as `str`. Depending of the length
+ * of `str`, this rope may be empty, flat or complex.
+ *
+ * # Performance notes
+ *
+ * * this operation does not copy the string;
+ * * the function runs in linear time.
+ */
 fn of_str(str: @str) -> rope {
     ret of_substr(str, 0u, str::len(*str));
 }
 
-#[doc = "
-As `of_str` but for a substring.
-
-# Arguments
-* byte_offset - The offset of `str` at which the rope starts.
-* byte_len - The number of bytes of `str` to use.
-
-# Return value
-
-A rope representing the same string as `str::substr(str, byte_offset,
-byte_len)`.  Depending on `byte_len`, this rope may be empty, flat or
-complex.
-
-# Performance note
-
-This operation does not copy the substring.
-
-# Safety notes
-
-* this function does _not_ check the validity of the substring;
-* this function fails if `byte_offset` or `byte_len` do not match `str`.
-"]
+/**
+ * As `of_str` but for a substring.
+ *
+ * # Arguments
+ * * byte_offset - The offset of `str` at which the rope starts.
+ * * byte_len - The number of bytes of `str` to use.
+ *
+ * # Return value
+ *
+ * A rope representing the same string as `str::substr(str, byte_offset,
+ * byte_len)`.  Depending on `byte_len`, this rope may be empty, flat or
+ * complex.
+ *
+ * # Performance note
+ *
+ * This operation does not copy the substring.
+ *
+ * # Safety notes
+ *
+ * * this function does _not_ check the validity of the substring;
+ * * this function fails if `byte_offset` or `byte_len` do not match `str`.
+ */
 fn of_substr(str: @str, byte_offset: uint, byte_len: uint) -> rope {
     if byte_len == 0u { ret node::empty; }
     if byte_offset + byte_len  > str::len(*str) { fail; }
@@ -89,49 +89,49 @@ fn of_substr(str: @str, byte_offset: uint, byte_len: uint) -> rope {
 Section: Adding things to a rope
  */
 
-#[doc = "
-Add one char to the end of the rope
-
-# Performance note
-
-* this function executes in near-constant time
-"]
+/**
+ * Add one char to the end of the rope
+ *
+ * # Performance note
+ *
+ * * this function executes in near-constant time
+ */
 fn append_char(rope: rope, char: char) -> rope {
     ret append_str(rope, @str::from_chars(~[char]));
 }
 
-#[doc = "
-Add one string to the end of the rope
-
-# Performance note
-
-* this function executes in near-linear time
-"]
+/**
+ * Add one string to the end of the rope
+ *
+ * # Performance note
+ *
+ * * this function executes in near-linear time
+ */
 fn append_str(rope: rope, str: @str) -> rope {
     ret append_rope(rope, of_str(str))
 }
 
-#[doc = "
-Add one char to the beginning of the rope
-
-# Performance note
-* this function executes in near-constant time
-"]
+/**
+ * Add one char to the beginning of the rope
+ *
+ * # Performance note
+ * * this function executes in near-constant time
+ */
 fn prepend_char(rope: rope, char: char) -> rope {
     ret prepend_str(rope, @str::from_chars(~[char]));
 }
 
-#[doc = "
-Add one string to the beginning of the rope
-
-# Performance note
-* this function executes in near-linear time
-"]
+/**
+ * Add one string to the beginning of the rope
+ *
+ * # Performance note
+ * * this function executes in near-linear time
+ */
 fn prepend_str(rope: rope, str: @str) -> rope {
     ret append_rope(of_str(str), rope)
 }
 
-#[doc = "Concatenate two ropes"]
+/// Concatenate two ropes
 fn append_rope(left: rope, right: rope) -> rope {
    alt(left) {
      node::empty { ret right; }
@@ -146,13 +146,13 @@ fn append_rope(left: rope, right: rope) -> rope {
    }
 }
 
-#[doc = "
-Concatenate many ropes.
-
-If the ropes are balanced initially and have the same height, the resulting
-rope remains balanced. However, this function does not take any further
-measure to ensure that the result is balanced.
-"]
+/**
+ * Concatenate many ropes.
+ *
+ * If the ropes are balanced initially and have the same height, the resulting
+ * rope remains balanced. However, this function does not take any further
+ * measure to ensure that the result is balanced.
+ */
 fn concat(v: ~[rope]) -> rope {
     //Copy `v` into a mut vector
     let mut len = vec::len(v);
@@ -185,17 +185,17 @@ Section: Keeping ropes healthy
  */
 
 
-#[doc = "
-Balance a rope.
-
-# Return value
-
-A copy of the rope in which small nodes have been grouped in memory,
-and with a reduced height.
-
-If you perform numerous rope concatenations, it is generally a good idea
-to rebalance your rope at some point, before using it for other purposes.
-"]
+/**
+ * Balance a rope.
+ *
+ * # Return value
+ *
+ * A copy of the rope in which small nodes have been grouped in memory,
+ * and with a reduced height.
+ *
+ * If you perform numerous rope concatenations, it is generally a good idea
+ * to rebalance your rope at some point, before using it for other purposes.
+ */
 fn bal(rope:rope) -> rope {
     alt(rope) {
       node::empty { ret rope }
@@ -213,19 +213,19 @@ Section: Transforming ropes
  */
 
 
-#[doc = "
-Extract a subrope from a rope.
-
-# Performance note
-
-* on a balanced rope, this operation takes algorithmic time;
-* this operation does not involve any copying
-
-# Safety note
-
-* this function fails if char_offset/char_len do not represent
-  valid positions in rope
-"]
+/**
+ * Extract a subrope from a rope.
+ *
+ * # Performance note
+ *
+ * * on a balanced rope, this operation takes algorithmic time;
+ * * this operation does not involve any copying
+ *
+ * # Safety note
+ *
+ * * this function fails if char_offset/char_len do not represent
+ *   valid positions in rope
+ */
 fn sub_chars(rope: rope, char_offset: uint, char_len: uint) -> rope {
     if char_len == 0u { ret node::empty; }
     alt(rope) {
@@ -239,19 +239,19 @@ fn sub_chars(rope: rope, char_offset: uint, char_len: uint) -> rope {
     }
 }
 
-#[doc = "
-Extract a subrope from a rope.
-
-# Performance note
-
-* on a balanced rope, this operation takes algorithmic time;
-* this operation does not involve any copying
-
-# Safety note
-
-* this function fails if byte_offset/byte_len do not represent
-  valid positions in rope
-"]
+/**
+ * Extract a subrope from a rope.
+ *
+ * # Performance note
+ *
+ * * on a balanced rope, this operation takes algorithmic time;
+ * * this operation does not involve any copying
+ *
+ * # Safety note
+ *
+ * * this function fails if byte_offset/byte_len do not represent
+ *   valid positions in rope
+ */
 fn sub_bytes(rope: rope, byte_offset: uint, byte_len: uint) -> rope {
     if byte_len == 0u { ret node::empty; }
     alt(rope) {
@@ -269,16 +269,16 @@ fn sub_bytes(rope: rope, byte_offset: uint, byte_len: uint) -> rope {
 Section: Comparing ropes
  */
 
-#[doc = "
-Compare two ropes by Unicode lexicographical order.
-
-This function compares only the contents of the rope, not their structure.
-
-# Return value
-
-A negative value if `left < right`, 0 if eq(left, right) or a positive
-value if `left > right`
-"]
+/**
+ * Compare two ropes by Unicode lexicographical order.
+ *
+ * This function compares only the contents of the rope, not their structure.
+ *
+ * # Return value
+ *
+ * A negative value if `left < right`, 0 if eq(left, right) or a positive
+ * value if `left > right`
+ */
 fn cmp(left: rope, right: rope) -> int {
     alt((left, right)) {
       (node::empty, node::empty) { ret 0; }
@@ -290,70 +290,70 @@ fn cmp(left: rope, right: rope) -> int {
     }
 }
 
-#[doc = "
-Returns `true` if both ropes have the same content (regardless of
-their structure), `false` otherwise
-"]
+/**
+ * Returns `true` if both ropes have the same content (regardless of
+ * their structure), `false` otherwise
+ */
 fn eq(left: rope, right: rope) -> bool {
     ret cmp(left, right) == 0;
 }
 
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
-`true` if `left <= right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ * `true` if `left <= right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
 fn le(left: rope, right: rope) -> bool {
     ret cmp(left, right) <= 0;
 }
 
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
-`true` if `left < right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ * `true` if `left < right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
 fn lt(left: rope, right: rope) -> bool {
     ret cmp(left, right) < 0;
 }
 
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
- `true` if `left >= right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ *  `true` if `left >= right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
 fn ge(left: rope, right: rope) -> bool {
     ret cmp(left, right) >= 0;
 }
 
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
-`true` if `left > right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ * `true` if `left > right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
 fn gt(left: rope, right: rope) -> bool {
     ret cmp(left, right) > 0;
 }
@@ -362,26 +362,26 @@ fn gt(left: rope, right: rope) -> bool {
 Section: Iterating
  */
 
-#[doc = "
-Loop through a rope, char by char
-
-While other mechanisms are available, this is generally the best manner
-of looping through the contents of a rope char by char. If you prefer a
-loop that iterates through the contents string by string (e.g. to print
-the contents of the rope or output it to the system), however,
-you should rather use `traverse_components`.
-
-# Arguments
-
-* rope - A rope to traverse. It may be empty.
-* it - A block to execute with each consecutive character of the rope.
-       Return `true` to continue, `false` to stop.
-
-# Return value
-
-`true` If execution proceeded correctly, `false` if it was interrupted,
-that is if `it` returned `false` at any point.
-"]
+/**
+ * Loop through a rope, char by char
+ *
+ * While other mechanisms are available, this is generally the best manner
+ * of looping through the contents of a rope char by char. If you prefer a
+ * loop that iterates through the contents string by string (e.g. to print
+ * the contents of the rope or output it to the system), however,
+ * you should rather use `traverse_components`.
+ *
+ * # Arguments
+ *
+ * * rope - A rope to traverse. It may be empty.
+ * * it - A block to execute with each consecutive character of the rope.
+ *        Return `true` to continue, `false` to stop.
+ *
+ * # Return value
+ *
+ * `true` If execution proceeded correctly, `false` if it was interrupted,
+ * that is if `it` returned `false` at any point.
+ */
 fn loop_chars(rope: rope, it: fn(char) -> bool) -> bool {
    alt(rope) {
       node::empty { ret true }
@@ -389,13 +389,13 @@ fn loop_chars(rope: rope, it: fn(char) -> bool) -> bool {
    }
 }
 
-#[doc = "
-Loop through a rope, char by char, until the end.
-
-# Arguments
-* rope - A rope to traverse. It may be empty
-* it - A block to execute with each consecutive character of the rope.
-"]
+/**
+ * Loop through a rope, char by char, until the end.
+ *
+ * # Arguments
+ * * rope - A rope to traverse. It may be empty
+ * * it - A block to execute with each consecutive character of the rope.
+ */
 fn iter_chars(rope: rope, it: fn(char)) {
     do loop_chars(rope) |x| {
         it(x);
@@ -403,28 +403,28 @@ fn iter_chars(rope: rope, it: fn(char)) {
     };
 }
 
-#[doc ="
-Loop through a rope, string by string
-
-While other mechanisms are available, this is generally the best manner of
-looping through the contents of a rope string by string, which may be useful
-e.g. to print strings as you see them (without having to copy their
-contents into a new string), to send them to then network, to write them to
-a file, etc.. If you prefer a loop that iterates through the contents
-char by char (e.g. to search for a char), however, you should rather
-use `traverse`.
-
-# Arguments
-
-* rope - A rope to traverse. It may be empty
-* it - A block to execute with each consecutive string component of the rope.
-       Return `true` to continue, `false` to stop
-
-# Return value
-
-`true` If execution proceeded correctly, `false` if it was interrupted,
-that is if `it` returned `false` at any point.
-"]
+/**
+ * Loop through a rope, string by string
+ *
+ * While other mechanisms are available, this is generally the best manner of
+ * looping through the contents of a rope string by string, which may be
+ * useful e.g. to print strings as you see them (without having to copy their
+ * contents into a new string), to send them to then network, to write them to
+ * a file, etc.. If you prefer a loop that iterates through the contents
+ * char by char (e.g. to search for a char), however, you should rather
+ * use `traverse`.
+ *
+ * # Arguments
+ *
+ * * rope - A rope to traverse. It may be empty
+ * * it - A block to execute with each consecutive string component of the
+ *        rope. Return `true` to continue, `false` to stop
+ *
+ * # Return value
+ *
+ * `true` If execution proceeded correctly, `false` if it was interrupted,
+ * that is if `it` returned `false` at any point.
+ */
 fn loop_leaves(rope: rope, it: fn(node::leaf) -> bool) -> bool{
    alt(rope) {
       node::empty { ret true }
@@ -461,17 +461,17 @@ mod iterator {
  Section: Rope properties
  */
 
-#[doc ="
-Returns the height of the rope.
-
-The height of the rope is a bound on the number of operations which
-must be performed during a character access before finding the leaf in
-which a character is contained.
-
-# Performance note
-
-Constant time.
-"]
+/**
+ * Returns the height of the rope.
+ *
+ * The height of the rope is a bound on the number of operations which
+ * must be performed during a character access before finding the leaf in
+ * which a character is contained.
+ *
+ * # Performance note
+ *
+ * Constant time.
+ */
 fn height(rope: rope) -> uint {
    alt(rope) {
       node::empty    { ret 0u; }
@@ -481,13 +481,13 @@ fn height(rope: rope) -> uint {
 
 
 
-#[doc ="
-The number of character in the rope
-
-# Performance note
-
-Constant time.
-"]
+/**
+ * The number of character in the rope
+ *
+ * # Performance note
+ *
+ * Constant time.
+ */
 pure fn char_len(rope: rope) -> uint {
    alt(rope) {
      node::empty           { ret 0u; }
@@ -495,13 +495,13 @@ pure fn char_len(rope: rope) -> uint {
    }
 }
 
-#[doc = "
-The number of bytes in the rope
-
-# Performance note
-
-Constant time.
-"]
+/**
+ * The number of bytes in the rope
+ *
+ * # Performance note
+ *
+ * Constant time.
+ */
 pure fn byte_len(rope: rope) -> uint {
    alt(rope) {
      node::empty           { ret 0u; }
@@ -509,22 +509,22 @@ pure fn byte_len(rope: rope) -> uint {
    }
 }
 
-#[doc = "
-The character at position `pos`
-
-# Arguments
-
-* pos - A position in the rope
-
-# Safety notes
-
-The function will fail if `pos` is not a valid position in the rope.
-
-# Performance note
-
-This function executes in a time proportional to the height of the
-rope + the (bounded) length of the largest leaf.
-"]
+/**
+ * The character at position `pos`
+ *
+ * # Arguments
+ *
+ * * pos - A position in the rope
+ *
+ * # Safety notes
+ *
+ * The function will fail if `pos` is not a valid position in the rope.
+ *
+ * # Performance note
+ *
+ * This function executes in a time proportional to the height of the
+ * rope + the (bounded) length of the largest leaf.
+ */
 fn char_at(rope: rope, pos: uint) -> char {
    alt(rope) {
       node::empty { fail }
@@ -538,31 +538,31 @@ fn char_at(rope: rope, pos: uint) -> char {
 */
 mod node {
 
-    #[doc = "Implementation of type `rope`"]
+    /// Implementation of type `rope`
     enum root {
-        #[doc = "An empty rope"]
+        /// An empty rope
         empty,
-        #[doc = "A non-empty rope"]
+        /// A non-empty rope
         content(@node),
     }
 
-    #[doc = "
-    A text component in a rope.
-
-    This is actually a slice in a rope, so as to ensure maximal sharing.
-
-    # Fields
-
-    * byte_offset = The number of bytes skippen in `content`
-    * byte_len - The number of bytes of `content` to use
-    * char_len - The number of chars in the leaf.
-    * content - Contents of the leaf.
-
-        Note that we can have `char_len < str::char_len(content)`, if
-        this leaf is only a subset of the string. Also note that the
-        string can be shared between several ropes, e.g. for indexing
-        purposes.
-    "]
+    /**
+     * A text component in a rope.
+     *
+     * This is actually a slice in a rope, so as to ensure maximal sharing.
+     *
+     * # Fields
+     *
+     * * byte_offset = The number of bytes skippen in `content`
+     * * byte_len - The number of bytes of `content` to use
+     * * char_len - The number of chars in the leaf.
+     * * content - Contents of the leaf.
+     *
+     *     Note that we can have `char_len < str::char_len(content)`, if
+     *     this leaf is only a subset of the string. Also note that the
+     *     string can be shared between several ropes, e.g. for indexing
+     *     purposes.
+     */
     type leaf = {
         byte_offset: uint,
         byte_len:    uint,
@@ -570,22 +570,23 @@ mod node {
         content:    @str
     };
 
-    #[doc = "
-    A node obtained from the concatenation of two other nodes
-
-    # Fields
-
-    * left - The node containing the beginning of the text.
-    * right - The node containing the end of the text.
-    * char_len - The number of chars contained in all leaves of this node.
-    * byte_len - The number of bytes in the subrope.
-
-        Used to pre-allocate the correct amount of storage for serialization.
-
-    * height - Height of the subrope.
-
-        Used for rebalancing and to allocate stacks for traversals.
-    "]
+    /**
+     * A node obtained from the concatenation of two other nodes
+     *
+     * # Fields
+     *
+     * * left - The node containing the beginning of the text.
+     * * right - The node containing the end of the text.
+     * * char_len - The number of chars contained in all leaves of this node.
+     * * byte_len - The number of bytes in the subrope.
+     *
+     *     Used to pre-allocate the correct amount of storage for
+     *     serialization.
+     *
+     * * height - Height of the subrope.
+     *
+     *     Used for rebalancing and to allocate stacks for traversals.
+     */
     type concat = {
         left:     @node,//TODO: Perhaps a `vec` instead of `left`/`right`
         right:    @node,
@@ -595,83 +596,83 @@ mod node {
     };
 
     enum node {
-        #[doc = "A leaf consisting in a `str`"]
+        /// A leaf consisting in a `str`
         leaf(leaf),
-        #[doc = "The concatenation of two ropes"]
+        /// The concatenation of two ropes
         concat(concat),
     }
 
-    #[doc = "
-    The maximal number of chars that _should_ be permitted in a single node.
-
-    This is not a strict value
-    "]
+    /**
+     * The maximal number of chars that _should_ be permitted in a single node
+     *
+     * This is not a strict value
+     */
     const hint_max_leaf_char_len: uint = 256u;
 
-    #[doc = "
-    The maximal height that _should_ be permitted in a tree.
-
-    This is not a strict value
-    "]
+    /**
+     * The maximal height that _should_ be permitted in a tree.
+     *
+     * This is not a strict value
+     */
     const hint_max_node_height:   uint = 16u;
 
-    #[doc = "
-    Adopt a string as a node.
-
-    If the string is longer than `max_leaf_char_len`, it is
-    logically split between as many leaves as necessary. Regardless,
-    the string itself is not copied.
-
-    Performance note: The complexity of this function is linear in
-    the length of `str`.
-    "]
+    /**
+     * Adopt a string as a node.
+     *
+     * If the string is longer than `max_leaf_char_len`, it is
+     * logically split between as many leaves as necessary. Regardless,
+     * the string itself is not copied.
+     *
+     * Performance note: The complexity of this function is linear in
+     * the length of `str`.
+     */
     fn of_str(str: @str) -> @node {
         ret of_substr(str, 0u, str::len(*str));
     }
 
-    #[doc ="
-    Adopt a slice of a string as a node.
-
-    If the slice is longer than `max_leaf_char_len`, it is logically split
-    between as many leaves as necessary. Regardless, the string itself
-    is not copied
-
-    # Arguments
-
-    * byte_start - The byte offset where the slice of `str` starts.
-    * byte_len   - The number of bytes from `str` to use.
-
-    # Safety note
-
-    Behavior is undefined if `byte_start` or `byte_len` do not represent
-    valid positions in `str`
-    "]
+    /**
+     * Adopt a slice of a string as a node.
+     *
+     * If the slice is longer than `max_leaf_char_len`, it is logically split
+     * between as many leaves as necessary. Regardless, the string itself
+     * is not copied
+     *
+     * # Arguments
+     *
+     * * byte_start - The byte offset where the slice of `str` starts.
+     * * byte_len   - The number of bytes from `str` to use.
+     *
+     * # Safety note
+     *
+     * Behavior is undefined if `byte_start` or `byte_len` do not represent
+     * valid positions in `str`
+     */
     fn of_substr(str: @str, byte_start: uint, byte_len: uint) -> @node {
         ret of_substr_unsafer(str, byte_start, byte_len,
                               str::count_chars(*str, byte_start, byte_len));
     }
 
-    #[doc = "
-    Adopt a slice of a string as a node.
-
-    If the slice is longer than `max_leaf_char_len`, it is logically split
-    between as many leaves as necessary. Regardless, the string itself
-    is not copied
-
-    # Arguments
-
-    * byte_start - The byte offset where the slice of `str` starts.
-    * byte_len - The number of bytes from `str` to use.
-    * char_len - The number of chars in `str` in the interval
-                 [byte_start, byte_start+byte_len)
-
-    # Safety notes
-
-    * Behavior is undefined if `byte_start` or `byte_len` do not represent
-      valid positions in `str`
-    * Behavior is undefined if `char_len` does not accurately represent the
-      number of chars between byte_start and byte_start+byte_len
-    "]
+    /**
+     * Adopt a slice of a string as a node.
+     *
+     * If the slice is longer than `max_leaf_char_len`, it is logically split
+     * between as many leaves as necessary. Regardless, the string itself
+     * is not copied
+     *
+     * # Arguments
+     *
+     * * byte_start - The byte offset where the slice of `str` starts.
+     * * byte_len - The number of bytes from `str` to use.
+     * * char_len - The number of chars in `str` in the interval
+     *              [byte_start, byte_start+byte_len)
+     *
+     * # Safety notes
+     *
+     * * Behavior is undefined if `byte_start` or `byte_len` do not represent
+     *   valid positions in `str`
+     * * Behavior is undefined if `char_len` does not accurately represent the
+     *   number of chars between byte_start and byte_start+byte_len
+     */
     fn of_substr_unsafer(str: @str, byte_start: uint, byte_len: uint,
                           char_len: uint) -> @node {
         assert(byte_start + byte_len <= str::len(*str));
@@ -744,14 +745,14 @@ mod node {
         }
     }
 
-    #[doc ="
-    Concatenate a forest of nodes into one tree.
-
-    # Arguments
-
-    * forest - The forest. This vector is progressively rewritten during
-               execution and should be discarded as meaningless afterwards.
-    "]
+    /**
+     * Concatenate a forest of nodes into one tree.
+     *
+     * # Arguments
+     *
+     * * forest - The forest. This vector is progressively rewritten during
+     *            execution and should be discarded as meaningless afterwards.
+     */
     fn tree_from_forest_destructive(forest: ~[mut @node]) -> @node {
         let mut i;
         let mut len = vec::len(forest);
@@ -820,13 +821,13 @@ mod node {
         ret unsafe::transmute(buf);
     }
 
-    #[doc ="
-    Replace a subtree by a single leaf with the same contents.
-
-    * Performance note
-
-    This function executes in linear time.
-    "]
+    /**
+     * Replace a subtree by a single leaf with the same contents.
+     *
+     * * Performance note
+     *
+     * This function executes in linear time.
+     */
     fn flatten(node: @node) -> @node unsafe {
         alt(*node) {
           leaf(_) { ret node }
@@ -841,21 +842,21 @@ mod node {
         }
     }
 
-    #[doc ="
-    Balance a node.
-
-    # Algorithm
-
-    * if the node height is smaller than `hint_max_node_height`, do nothing
-    * otherwise, gather all leaves as a forest, rebuild a balanced node,
-      concatenating small leaves along the way
-
-    # Return value
-
-    * `option::none` if no transformation happened
-    * `option::some(x)` otherwise, in which case `x` has the same contents
-       as `node` bot lower height and/or fragmentation.
-    "]
+    /**
+     * Balance a node.
+     *
+     * # Algorithm
+     *
+     * * if the node height is smaller than `hint_max_node_height`, do nothing
+     * * otherwise, gather all leaves as a forest, rebuild a balanced node,
+     *   concatenating small leaves along the way
+     *
+     * # Return value
+     *
+     * * `option::none` if no transformation happened
+     * * `option::some(x)` otherwise, in which case `x` has the same contents
+     *    as `node` bot lower height and/or fragmentation.
+     */
     fn bal(node: @node) -> option<@node> {
         if height(node) < hint_max_node_height { ret option::none; }
         //1. Gather all leaves as a forest
@@ -873,25 +874,25 @@ mod node {
 
     }
 
-    #[doc ="
-    Compute the subnode of a node.
-
-    # Arguments
-
-    * node        - A node
-    * byte_offset - A byte offset in `node`
-    * byte_len    - The number of bytes to return
-
-    # Performance notes
-
-    * this function performs no copying;
-    * this function executes in a time proportional to the height of `node`.
-
-    # Safety notes
-
-    This function fails if `byte_offset` or `byte_len` do not represent
-    valid positions in `node`.
-    "]
+    /**
+     * Compute the subnode of a node.
+     *
+     * # Arguments
+     *
+     * * node        - A node
+     * * byte_offset - A byte offset in `node`
+     * * byte_len    - The number of bytes to return
+     *
+     * # Performance notes
+     *
+     * * this function performs no copying;
+     * * this function executes in a time proportional to the height of `node`
+     *
+     * # Safety notes
+     *
+     * This function fails if `byte_offset` or `byte_len` do not represent
+     * valid positions in `node`.
+     */
     fn sub_bytes(node: @node, byte_offset: uint, byte_len: uint) -> @node {
         let mut node        = node;
         let mut byte_offset = byte_offset;
@@ -934,25 +935,25 @@ mod node {
         };
     }
 
-    #[doc ="
-    Compute the subnode of a node.
-
-    # Arguments
-
-    * node        - A node
-    * char_offset - A char offset in `node`
-    * char_len    - The number of chars to return
-
-    # Performance notes
-
-    * this function performs no copying;
-    * this function executes in a time proportional to the height of `node`.
-
-    # Safety notes
-
-    This function fails if `char_offset` or `char_len` do not represent
-    valid positions in `node`.
-    "]
+    /**
+     * Compute the subnode of a node.
+     *
+     * # Arguments
+     *
+     * * node        - A node
+     * * char_offset - A char offset in `node`
+     * * char_len    - The number of chars to return
+     *
+     * # Performance notes
+     *
+     * * this function performs no copying;
+     * * this function executes in a time proportional to the height of `node`
+     *
+     * # Safety notes
+     *
+     * This function fails if `char_offset` or `char_len` do not represent
+     * valid positions in `node`.
+     */
     fn sub_chars(node: @node, char_offset: uint, char_len: uint) -> @node {
         let mut node        = node;
         let mut char_offset = char_offset;
@@ -1045,20 +1046,20 @@ mod node {
         });
     }
 
-    #[doc ="
-    Loop through a node, leaf by leaf
-
-    # Arguments
-
-    * rope - A node to traverse.
-    * it - A block to execute with each consecutive leaf of the node.
-           Return `true` to continue, `false` to stop
-
-    # Arguments
-
-    `true` If execution proceeded correctly, `false` if it was interrupted,
-    that is if `it` returned `false` at any point.
-    "]
+    /**
+     * Loop through a node, leaf by leaf
+     *
+     * # Arguments
+     *
+     * * rope - A node to traverse.
+     * * it - A block to execute with each consecutive leaf of the node.
+     *        Return `true` to continue, `false` to stop
+     *
+     * # Arguments
+     *
+     * `true` If execution proceeded correctly, `false` if it was interrupted,
+     * that is if `it` returned `false` at any point.
+     */
     fn loop_leaves(node: @node, it: fn(leaf) -> bool) -> bool{
         let mut current = node;
         loop {
@@ -1077,23 +1078,23 @@ mod node {
         };
     }
 
-    #[doc ="
-    # Arguments
-
-    * pos - A position in the rope
-
-    # Return value
-
-    The character at position `pos`
-
-    # Safety notes
-
-    The function will fail if `pos` is not a valid position in the rope.
-
-    Performance note: This function executes in a time
-    proportional to the height of the rope + the (bounded)
-    length of the largest leaf.
-    "]
+    /**
+     * # Arguments
+     *
+     * * pos - A position in the rope
+     *
+     * # Return value
+     *
+     * The character at position `pos`
+     *
+     * # Safety notes
+     *
+     * The function will fail if `pos` is not a valid position in the rope.
+     *
+     * Performance note: This function executes in a time
+     * proportional to the height of the rope + the (bounded)
+     * length of the largest leaf.
+     */
     fn char_at(node: @node, pos: uint) -> char {
         let mut node    = node;
         let mut pos     = pos;
diff --git a/src/libstd/serialization.rs b/src/libstd/serialization.rs
index 14da0fa86e1..aafe31ec011 100644
--- a/src/libstd/serialization.rs
+++ b/src/libstd/serialization.rs
@@ -1,4 +1,4 @@
-#[doc = "Support code for serialization."];
+//! Support code for serialization.
 
 use core;
 
diff --git a/src/libstd/sha1.rs b/src/libstd/sha1.rs
index 6aed645283d..607388bd559 100644
--- a/src/libstd/sha1.rs
+++ b/src/libstd/sha1.rs
@@ -1,16 +1,16 @@
-#[doc ="
-An implementation of the SHA-1 cryptographic hash.
-
-First create a `sha1` object using the `sha1` constructor, then
-feed it input using the `input` or `input_str` methods, which may be
-called any number of times.
-
-After the entire input has been fed to the hash read the result using
-the `result` or `result_str` methods.
-
-The `sha1` object may be reused to create multiple hashes by calling
-the `reset` method.
-"];
+/*!
+ * An implementation of the SHA-1 cryptographic hash.
+ *
+ * First create a `sha1` object using the `sha1` constructor, then
+ * feed it input using the `input` or `input_str` methods, which may be
+ * called any number of times.
+ *
+ * After the entire input has been fed to the hash read the result using
+ * the `result` or `result_str` methods.
+ *
+ * The `sha1` object may be reused to create multiple hashes by calling
+ * the `reset` method.
+ */
 
 /*
  * A SHA-1 implementation derived from Paul E. Jones's reference
@@ -19,23 +19,23 @@ the `reset` method.
  */
 export sha1;
 
-#[doc = "The SHA-1 interface"]
+/// The SHA-1 interface
 iface sha1 {
-    #[doc = "Provide message input as bytes"]
+    /// Provide message input as bytes
     fn input(~[u8]);
-    #[doc = "Provide message input as string"]
+    /// Provide message input as string
     fn input_str(str);
-    #[doc = "
-    Read the digest as a vector of 20 bytes. After calling this no further
-    input may be provided until reset is called.
-    "]
+    /**
+     * Read the digest as a vector of 20 bytes. After calling this no further
+     * input may be provided until reset is called.
+     */
     fn result() -> ~[u8];
-    #[doc = "
-    Read the digest as a hex string. After calling this no further
-    input may be provided until reset is called.
-    "]
+    /**
+     * Read the digest as a hex string. After calling this no further
+     * input may be provided until reset is called.
+     */
     fn result_str() -> str;
-    #[doc = "Reset the SHA-1 state for reuse"]
+    /// Reset the SHA-1 state for reuse
     fn reset();
 }
 
@@ -49,7 +49,7 @@ const k2: u32 = 0x8F1BBCDCu32;
 const k3: u32 = 0xCA62C1D6u32;
 
 
-#[doc = "Construct a `sha` object"]
+/// Construct a `sha` object
 fn sha1() -> sha1 {
     type sha1state =
         {h: ~[mut u32],
diff --git a/src/libstd/smallintmap.rs b/src/libstd/smallintmap.rs
index 6583d97908d..9fb4be4804d 100644
--- a/src/libstd/smallintmap.rs
+++ b/src/libstd/smallintmap.rs
@@ -1,7 +1,7 @@
-#[doc = "
-A simple map based on a vector for small integer keys. Space requirements
-are O(highest integer key).
-"];
+/*!
+ * A simple map based on a vector for small integer keys. Space requirements
+ * are O(highest integer key).
+ */
 import core::option;
 import core::option::{some, none};
 import dvec::{dvec, extensions};
@@ -10,36 +10,36 @@ import dvec::{dvec, extensions};
 // requires this to be.
 type smallintmap<T: copy> = @{v: dvec<option<T>>};
 
-#[doc = "Create a smallintmap"]
+/// Create a smallintmap
 fn mk<T: copy>() -> smallintmap<T> {
     ret @{v: dvec()};
 }
 
-#[doc = "
-Add a value to the map. If the map already contains a value for
-the specified key then the original value is replaced.
-"]
+/**
+ * Add a value to the map. If the map already contains a value for
+ * the specified key then the original value is replaced.
+ */
 #[inline(always)]
 fn insert<T: copy>(self: smallintmap<T>, key: uint, val: T) {
     self.v.grow_set_elt(key, none, some(val));
 }
 
-#[doc = "
-Get the value for the specified key. If the key does not exist
-in the map then returns none
-"]
+/**
+ * Get the value for the specified key. If the key does not exist
+ * in the map then returns none
+ */
 fn find<T: copy>(self: smallintmap<T>, key: uint) -> option<T> {
     if key < self.v.len() { ret self.v.get_elt(key); }
     ret none::<T>;
 }
 
-#[doc = "
-Get the value for the specified key
-
-# Failure
-
-If the key does not exist in the map
-"]
+/**
+ * Get the value for the specified key
+ *
+ * # Failure
+ *
+ * If the key does not exist in the map
+ */
 fn get<T: copy>(self: smallintmap<T>, key: uint) -> T {
     alt find(self, key) {
       none { #error("smallintmap::get(): key not present"); fail; }
@@ -47,14 +47,12 @@ fn get<T: copy>(self: smallintmap<T>, key: uint) -> T {
     }
 }
 
-#[doc = "
-Returns true if the map contains a value for the specified key
-"]
+/// Returns true if the map contains a value for the specified key
 fn contains_key<T: copy>(self: smallintmap<T>, key: uint) -> bool {
     ret !option::is_none(find(self, key));
 }
 
-#[doc = "Implements the map::map interface for smallintmap"]
+/// Implements the map::map interface for smallintmap
 impl <V: copy> of map::map<uint, V> for smallintmap<V> {
     fn size() -> uint {
         let mut sz = 0u;
@@ -106,7 +104,7 @@ impl <V: copy> of map::map<uint, V> for smallintmap<V> {
     }
 }
 
-#[doc = "Cast the given smallintmap to a map::map"]
+/// Cast the given smallintmap to a map::map
 fn as_map<V: copy>(s: smallintmap<V>) -> map::map<uint, V> {
     s as map::map::<uint, V>
 }
diff --git a/src/libstd/sort.rs b/src/libstd/sort.rs
index 7de8f0cfab8..d0092e97cb3 100644
--- a/src/libstd/sort.rs
+++ b/src/libstd/sort.rs
@@ -1,4 +1,4 @@
-#[doc = "Sorting methods"];
+//! Sorting methods
 import vec::{len, push};
 import int::{eq, ord};
 
@@ -9,12 +9,12 @@ export quick_sort3;
 
 type le<T> = fn(T, T) -> bool;
 
-#[doc = "
-Merge sort. Returns a new vector containing the sorted list.
-
-Has worst case O(n log n) performance, best case O(n), but
-is not space efficient. This is a stable sort.
-"]
+/**
+ * Merge sort. Returns a new vector containing the sorted list.
+ *
+ * Has worst case O(n log n) performance, best case O(n), but
+ * is not space efficient. This is a stable sort.
+ */
 fn merge_sort<T: copy>(le: le<T>, v: ~[const T]) -> ~[T] {
     type slice = (uint, uint);
 
@@ -84,12 +84,12 @@ fn qsort<T: copy>(compare_func: le<T>, arr: ~[mut T], left: uint,
     }
 }
 
-#[doc = "
-Quicksort. Sorts a mut vector in place.
-
-Has worst case O(n^2) performance, average case O(n log n).
-This is an unstable sort.
-"]
+/**
+ * Quicksort. Sorts a mut vector in place.
+ *
+ * Has worst case O(n^2) performance, average case O(n log n).
+ * This is an unstable sort.
+ */
 fn quick_sort<T: copy>(compare_func: le<T>, arr: ~[mut T]) {
     if len::<T>(arr) == 0u { ret; }
     qsort::<T>(compare_func, arr, 0u, len::<T>(arr) - 1u);
@@ -143,16 +143,16 @@ fn qsort3<T: copy>(compare_func_lt: le<T>, compare_func_eq: le<T>,
     qsort3::<T>(compare_func_lt, compare_func_eq, arr, i, right);
 }
 
-#[doc = "
-Fancy quicksort. Sorts a mut vector in place.
-
-Based on algorithm presented by [Sedgewick and Bentley]/~
-(http://www.cs.princeton.edu/~rs/talks/QuicksortIsOptimal.pdf).
-According to these slides this is the algorithm of choice for
-'randomly ordered keys, abstract compare' & 'small number of key values'.
-
-This is an unstable sort.
-"]
+/**
+ * Fancy quicksort. Sorts a mut vector in place.
+ *
+ * Based on algorithm presented by [Sedgewick and Bentley]/~
+ * (http://www.cs.princeton.edu/~rs/talks/QuicksortIsOptimal.pdf).
+ * According to these slides this is the algorithm of choice for
+ * 'randomly ordered keys, abstract compare' & 'small number of key values'.
+ *
+ * This is an unstable sort.
+ */
 fn quick_sort3<T: copy ord eq>(arr: ~[mut T]) {
     if len::<T>(arr) == 0u { ret; }
     qsort3::<T>(|x, y| x.lt(y), |x, y| x.eq(y), arr, 0,
diff --git a/src/libstd/std.rc b/src/libstd/std.rc
index 34707271217..e30e9fc4774 100644
--- a/src/libstd/std.rc
+++ b/src/libstd/std.rc
@@ -6,7 +6,7 @@
 #[comment = "The Rust standard library"];
 #[license = "MIT"];
 #[crate_type = "lib"];
-#[doc = "The Rust standard library"];
+//! The Rust standard library
 
 #[no_core];
 
diff --git a/src/libstd/tempfile.rs b/src/libstd/tempfile.rs
index 11956ff8a25..536f633f8a7 100644
--- a/src/libstd/tempfile.rs
+++ b/src/libstd/tempfile.rs
@@ -1,4 +1,4 @@
-#[doc = "Temporary files and directories"];
+//! Temporary files and directories
 
 import core::option;
 import option::{none, some};
diff --git a/src/libstd/term.rs b/src/libstd/term.rs
index 43e1765f50b..fb134e85295 100644
--- a/src/libstd/term.rs
+++ b/src/libstd/term.rs
@@ -1,4 +1,4 @@
-#[doc = "Simple ANSI color library"];
+//! Simple ANSI color library
 
 import core::option;
 
@@ -25,13 +25,13 @@ const color_bright_white: u8 = 15u8;
 
 fn esc(writer: io::writer) { writer.write([0x1bu8, '[' as u8]/~); }
 
-#[doc = "Reset the foreground and background colors to default"]
+/// Reset the foreground and background colors to default
 fn reset(writer: io::writer) {
     esc(writer);
     writer.write(~['0' as u8, 'm' as u8]);
 }
 
-#[doc = "Returns true if the terminal supports color"]
+/// Returns true if the terminal supports color
 fn color_supported() -> bool {
     let supported_terms = ~["xterm-color", "xterm",
                            "screen-bce", "xterm-256color"];
@@ -54,12 +54,12 @@ fn set_color(writer: io::writer, first_char: u8, color: u8) {
     writer.write(~[first_char, ('0' as u8) + color, 'm' as u8]);
 }
 
-#[doc = "Set the foreground color"]
+/// Set the foreground color
 fn fg(writer: io::writer, color: u8) {
     ret set_color(writer, '3' as u8, color);
 }
 
-#[doc = "Set the background color"]
+/// Set the background color
 fn bg(writer: io::writer, color: u8) {
     ret set_color(writer, '4' as u8, color);
 }
diff --git a/src/libstd/time.rs b/src/libstd/time.rs
index ba53bdbf014..3f3749cb064 100644
--- a/src/libstd/time.rs
+++ b/src/libstd/time.rs
@@ -29,13 +29,13 @@ extern mod rustrt {
     fn rust_mktime(&&tm: tm, &sec: i64);
 }
 
-#[doc = "A record specifying a time value in seconds and microseconds."]
+/// A record specifying a time value in seconds and microseconds.
 type timespec = {sec: i64, nsec: i32};
 
-#[doc = "
-Returns the current time as a `timespec` containing the seconds and
-microseconds since 1970-01-01T00:00:00Z.
-"]
+/**
+ * Returns the current time as a `timespec` containing the seconds and
+ * microseconds since 1970-01-01T00:00:00Z.
+ */
 fn get_time() -> timespec {
     let mut sec = 0i64;
     let mut nsec = 0i32;
@@ -43,20 +43,20 @@ fn get_time() -> timespec {
     ret {sec: sec, nsec: nsec};
 }
 
-#[doc = "
-Returns the current value of a high-resolution performance counter
-in nanoseconds since an unspecified epoch.
-"]
+/**
+ * Returns the current value of a high-resolution performance counter
+ * in nanoseconds since an unspecified epoch.
+ */
 fn precise_time_ns() -> u64 {
     let mut ns = 0u64;
     rustrt::precise_time_ns(ns);
     ns
 }
 
-#[doc = "
-Returns the current value of a high-resolution performance counter
-in seconds since an unspecified epoch.
-"]
+/**
+ * Returns the current value of a high-resolution performance counter
+ * in seconds since an unspecified epoch.
+ */
 fn precise_time_s() -> float {
     ret (precise_time_ns() as float) / 1000000000.;
 }
@@ -97,7 +97,7 @@ fn empty_tm() -> tm {
     }
 }
 
-#[doc = "Returns the specified time in UTC"]
+/// Returns the specified time in UTC
 fn at_utc(clock: timespec) -> tm {
     let mut {sec, nsec} = clock;
     let mut tm = empty_tm();
@@ -105,12 +105,12 @@ fn at_utc(clock: timespec) -> tm {
     tm
 }
 
-#[doc = "Returns the current time in UTC"]
+/// Returns the current time in UTC
 fn now_utc() -> tm {
     at_utc(get_time())
 }
 
-#[doc = "Returns the specified time in the local timezone"]
+/// Returns the specified time in the local timezone
 fn at(clock: timespec) -> tm {
     let mut {sec, nsec} = clock;
     let mut tm = empty_tm();
@@ -118,12 +118,12 @@ fn at(clock: timespec) -> tm {
     tm
 }
 
-#[doc = "Returns the current time in the local timezone"]
+/// Returns the current time in the local timezone
 fn now() -> tm {
     at(get_time())
 }
 
-#[doc = "Parses the time from the string according to the format string."]
+/// Parses the time from the string according to the format string.
 fn strptime(s: str, format: str) -> result<tm, str> {
     type tm_mut = {
        mut tm_sec: i32,
@@ -751,7 +751,7 @@ fn strftime(format: str, tm: tm) -> str {
 }
 
 impl tm for tm {
-    #[doc = "Convert time to the seconds from January 1, 1970"]
+    /// Convert time to the seconds from January 1, 1970
     fn to_timespec() -> timespec {
         let mut sec = 0i64;
         if self.tm_gmtoff == 0_i32 {
@@ -762,31 +762,31 @@ impl tm for tm {
         { sec: sec, nsec: self.tm_nsec }
     }
 
-    #[doc = "Convert time to the local timezone"]
+    /// Convert time to the local timezone
     fn to_local() -> tm {
         at(self.to_timespec())
     }
 
-    #[doc = "Convert time to the UTC"]
+    /// Convert time to the UTC
     fn to_utc() -> tm {
         at_utc(self.to_timespec())
     }
 
-    #[doc = "
-    Return a string of the current time in the form
-    \"Thu Jan  1 00:00:00 1970\".
-    "]
+    /**
+     * Return a string of the current time in the form
+     * "Thu Jan  1 00:00:00 1970".
+     */
     fn ctime() -> str { self.strftime("%c") }
 
-    #[doc = "Formats the time according to the format string."]
+    /// Formats the time according to the format string.
     fn strftime(format: str) -> str { strftime(format, self) }
 
-    #[doc = "
-    Returns a time string formatted according to RFC 822.
-
-    local: \"Thu, 22 Mar 2012 07:53:18 PST\"
-    utc:   \"Thu, 22 Mar 2012 14:53:18 UTC\"
-    "]
+    /**
+     * Returns a time string formatted according to RFC 822.
+     *
+     * local: "Thu, 22 Mar 2012 07:53:18 PST"
+     * utc:   "Thu, 22 Mar 2012 14:53:18 UTC"
+     */
     fn rfc822() -> str {
         if self.tm_gmtoff == 0_i32 {
             self.strftime("%a, %d %b %Y %T GMT")
@@ -795,22 +795,22 @@ impl tm for tm {
         }
     }
 
-    #[doc = "
-    Returns a time string formatted according to RFC 822 with Zulu time.
-
-    local: \"Thu, 22 Mar 2012 07:53:18 -0700\"
-    utc:   \"Thu, 22 Mar 2012 14:53:18 -0000\"
-    "]
+    /**
+     * Returns a time string formatted according to RFC 822 with Zulu time.
+     *
+     * local: "Thu, 22 Mar 2012 07:53:18 -0700"
+     * utc:   "Thu, 22 Mar 2012 14:53:18 -0000"
+     */
     fn rfc822z() -> str {
         self.strftime("%a, %d %b %Y %T %z")
     }
 
-    #[doc = "
-    Returns a time string formatted according to ISO 8601.
-
-    local: \"2012-02-22T07:53:18-07:00\"
-    utc:   \"2012-02-22T14:53:18Z\"
-    "]
+    /**
+     * Returns a time string formatted according to ISO 8601.
+     *
+     * local: "2012-02-22T07:53:18-07:00"
+     * utc:   "2012-02-22T14:53:18Z"
+     */
     fn rfc3339() -> str {
         if self.tm_gmtoff == 0_i32 {
             self.strftime("%Y-%m-%dT%H:%M:%SZ")
diff --git a/src/libstd/timer.rs b/src/libstd/timer.rs
index f8440443e6e..87d7dd67577 100644
--- a/src/libstd/timer.rs
+++ b/src/libstd/timer.rs
@@ -1,28 +1,26 @@
-#[doc ="
-Utilities that leverage libuv's `uv_timer_*` API
-"];
+//! Utilities that leverage libuv's `uv_timer_*` API
 
 import uv = uv;
 import uv::iotask;
 import iotask::iotask;
 export delayed_send, sleep, recv_timeout;
 
-#[doc = "
-Wait for timeout period then send provided value over a channel
-
-This call returns immediately. Useful as the building block for a number
-of higher-level timer functions.
-
-Is not guaranteed to wait for exactly the specified time, but will wait
-for *at least* that period of time.
-
-# Arguments
-
-* `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
-* msecs - a timeout period, in milliseconds, to wait
-* ch - a channel of type T to send a `val` on
-* val - a value of type T to send over the provided `ch`
-"]
+/**
+ * Wait for timeout period then send provided value over a channel
+ *
+ * This call returns immediately. Useful as the building block for a number
+ * of higher-level timer functions.
+ *
+ * Is not guaranteed to wait for exactly the specified time, but will wait
+ * for *at least* that period of time.
+ *
+ * # Arguments
+ *
+ * * `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
+ * * msecs - a timeout period, in milliseconds, to wait
+ * * ch - a channel of type T to send a `val` on
+ * * val - a value of type T to send over the provided `ch`
+ */
 fn delayed_send<T: copy send>(iotask: iotask,
                               msecs: uint, ch: comm::chan<T>, val: T) {
         unsafe {
@@ -60,17 +58,17 @@ fn delayed_send<T: copy send>(iotask: iotask,
     };
 }
 
-#[doc = "
-Blocks the current task for (at least) the specified time period.
-
-Is not guaranteed to sleep for exactly the specified time, but will sleep
-for *at least* that period of time.
-
-# Arguments
-
-* `iotask` - a `uv::iotask` that the tcp request will run on
-* msecs - an amount of time, in milliseconds, for the current task to block
-"]
+/**
+ * Blocks the current task for (at least) the specified time period.
+ *
+ * Is not guaranteed to sleep for exactly the specified time, but will sleep
+ * for *at least* that period of time.
+ *
+ * # Arguments
+ *
+ * * `iotask` - a `uv::iotask` that the tcp request will run on
+ * * msecs - an amount of time, in milliseconds, for the current task to block
+ */
 fn sleep(iotask: iotask, msecs: uint) {
     let exit_po = comm::port::<()>();
     let exit_ch = comm::chan(exit_po);
@@ -78,25 +76,26 @@ fn sleep(iotask: iotask, msecs: uint) {
     comm::recv(exit_po);
 }
 
-#[doc = "
-Receive on a port for (up to) a specified time, then return an `option<T>`
-
-This call will block to receive on the provided port for up to the specified
-timeout. Depending on whether the provided port receives in that time period,
-`recv_timeout` will return an `option<T>` representing the result.
-
-# Arguments
-
-* `iotask' - `uv::iotask` that the tcp request will run on
-* msecs - an mount of time, in milliseconds, to wait to receive
-* wait_port - a `comm::port<T>` to receive on
-
-# Returns
-
-An `option<T>` representing the outcome of the call. If the call `recv`'d on
-the provided port in the allotted timeout period, then the result will be a
-`some(T)`. If not, then `none` will be returned.
-"]
+/**
+ * Receive on a port for (up to) a specified time, then return an `option<T>`
+ *
+ * This call will block to receive on the provided port for up to the
+ * specified timeout. Depending on whether the provided port receives in that
+ * time period, `recv_timeout` will return an `option<T>` representing the
+ * result.
+ *
+ * # Arguments
+ *
+ * * `iotask' - `uv::iotask` that the tcp request will run on
+ * * msecs - an mount of time, in milliseconds, to wait to receive
+ * * wait_port - a `comm::port<T>` to receive on
+ *
+ * # Returns
+ *
+ * An `option<T>` representing the outcome of the call. If the call `recv`'d
+ * on the provided port in the allotted timeout period, then the result will
+ * be a `some(T)`. If not, then `none` will be returned.
+ */
 fn recv_timeout<T: copy send>(iotask: iotask,
                               msecs: uint,
                               wait_po: comm::port<T>) -> option<T> {
diff --git a/src/libstd/treemap.rs b/src/libstd/treemap.rs
index 066d2a6501f..1fde1c4fd6a 100644
--- a/src/libstd/treemap.rs
+++ b/src/libstd/treemap.rs
@@ -1,10 +1,10 @@
-#[doc = "
-A key,value store that works on anything.
-
-This works using a binary search tree. In the first version, it's a
-very naive algorithm, but it will probably be updated to be a
-red-black tree or something else.
-"];
+/*!
+ * A key,value store that works on anything.
+ *
+ * This works using a binary search tree. In the first version, it's a
+ * very naive algorithm, but it will probably be updated to be a
+ * red-black tree or something else.
+ */
 
 import core::option::{some, none};
 import option = core::option;
@@ -25,10 +25,10 @@ enum tree_node<K, V> = {
     mut right: tree_edge<K, V>
 };
 
-#[doc = "Create a treemap"]
+/// Create a treemap
 fn treemap<K, V>() -> treemap<K, V> { @mut none }
 
-#[doc = "Insert a value into the map"]
+/// Insert a value into the map
 fn insert<K: copy, V: copy>(m: &mut tree_edge<K, V>, k: K, v: V) {
     alt copy *m {
       none {
@@ -50,7 +50,7 @@ fn insert<K: copy, V: copy>(m: &mut tree_edge<K, V>, k: K, v: V) {
     };
 }
 
-#[doc = "Find a value based on the key"]
+/// Find a value based on the key
 fn find<K: copy, V: copy>(m: &const tree_edge<K, V>, k: K) -> option<V> {
     alt copy *m {
       none { none }
@@ -68,7 +68,7 @@ fn find<K: copy, V: copy>(m: &const tree_edge<K, V>, k: K) -> option<V> {
     }
 }
 
-#[doc = "Visit all pairs in the map in order."]
+/// Visit all pairs in the map in order.
 fn traverse<K, V: copy>(m: &const tree_edge<K, V>, f: fn(K, V)) {
     alt copy *m {
       none { }
diff --git a/src/libstd/util.rs b/src/libstd/util.rs
index fc0a326dee7..1101be170ba 100644
--- a/src/libstd/util.rs
+++ b/src/libstd/util.rs
@@ -1,9 +1,9 @@
-#[doc = "The identity function"]
+/// The identity function
 pure fn id<T: copy>(x: T) -> T { x }
 
 /* FIXME (issue #141):  See test/run-pass/constrained-type.rs.  Uncomment
  * the constraint once fixed. */
-#[doc = "A rational number"]
+/// A rational number
 type rational = {num: int, den: int}; // : int::positive(*.den);
 
 pure fn rational_leq(x: rational, y: rational) -> bool {
diff --git a/src/libstd/uv.rs b/src/libstd/uv.rs
index c2e4c55d61e..50f5d9704fa 100644
--- a/src/libstd/uv.rs
+++ b/src/libstd/uv.rs
@@ -1,27 +1,27 @@
-#[doc = "
-Rust bindings to libuv
-
-This is the base-module for various levels of bindings to
-the libuv library.
-
-These modules are seeing heavy work, currently, and the final
-API layout should not be inferred from its current form.
-
-This base module currently contains a historical, rust-based
-implementation of a few libuv operations that hews closely to
-the patterns of the libuv C-API. It was used, mostly, to explore
-some implementation details and will most likely be deprecated
-in the near future.
-
-The `ll` module contains low-level mappings for working directly
-with the libuv C-API.
-
-The `hl` module contains a set of tools library developers can
-use for interacting with an active libuv loop. This modules's
-API is meant to be used to write high-level,
-rust-idiomatic abstractions for utilizes libuv's asynchronous IO
-facilities.
-"];
+/*!
+ * Rust bindings to libuv
+ *
+ * This is the base-module for various levels of bindings to
+ * the libuv library.
+ *
+ * These modules are seeing heavy work, currently, and the final
+ * API layout should not be inferred from its current form.
+ *
+ * This base module currently contains a historical, rust-based
+ * implementation of a few libuv operations that hews closely to
+ * the patterns of the libuv C-API. It was used, mostly, to explore
+ * some implementation details and will most likely be deprecated
+ * in the near future.
+ *
+ * The `ll` module contains low-level mappings for working directly
+ * with the libuv C-API.
+ *
+ * The `hl` module contains a set of tools library developers can
+ * use for interacting with an active libuv loop. This modules's
+ * API is meant to be used to write high-level,
+ * rust-idiomatic abstractions for utilizes libuv's asynchronous IO
+ * facilities.
+ */
 
 import ll = uv_ll;
 export ll;
diff --git a/src/libstd/uv_global_loop.rs b/src/libstd/uv_global_loop.rs
index 6384e5b6864..a099d4f8b18 100644
--- a/src/libstd/uv_global_loop.rs
+++ b/src/libstd/uv_global_loop.rs
@@ -1,6 +1,4 @@
-#[doc="
-A process-wide libuv event loop for library use.
-"];
+//! A process-wide libuv event loop for library use.
 
 export get;
 
@@ -16,18 +14,18 @@ extern mod rustrt {
     fn rust_uv_get_kernel_global_chan_ptr() -> *libc::uintptr_t;
 }
 
-#[doc ="
-Race-free helper to get access to a global task where a libuv
-loop is running.
-
-Use `uv::hl::interact` to do operations against the global
-loop that this function returns.
-
-# Return
-
-* A `hl::high_level_loop` that encapsulates communication with the global
-loop.
-"]
+/**
+ * Race-free helper to get access to a global task where a libuv
+ * loop is running.
+ *
+ * Use `uv::hl::interact` to do operations against the global
+ * loop that this function returns.
+ *
+ * # Return
+ *
+ * * A `hl::high_level_loop` that encapsulates communication with the global
+ * loop.
+ */
 fn get() -> iotask {
     ret get_monitor_task_gl();
 }
diff --git a/src/libstd/uv_iotask.rs b/src/libstd/uv_iotask.rs
index fce69691bde..35e4446f8d8 100644
--- a/src/libstd/uv_iotask.rs
+++ b/src/libstd/uv_iotask.rs
@@ -1,11 +1,9 @@
-#[doc = "
-
-A task-based interface to the uv loop
-
-The I/O task runs in its own single-threaded scheduler.  By using the
-`interact` function you can execute code in a uv callback.
-
-"];
+/*!
+ * A task-based interface to the uv loop
+ *
+ * The I/O task runs in its own single-threaded scheduler.  By using the
+ * `interact` function you can execute code in a uv callback.
+ */
 
 export iotask;
 export spawn_iotask;
@@ -17,9 +15,7 @@ import ptr::addr_of;
 import comm::{port, chan, methods, listen};
 import ll = uv_ll;
 
-#[doc = "
-Used to abstract-away direct interaction with a libuv loop.
-"]
+/// Used to abstract-away direct interaction with a libuv loop.
 enum iotask {
     iotask_({
         async_handle: *ll::uv_async_t,
@@ -52,40 +48,40 @@ fn spawn_iotask(-builder: task::builder) -> iotask {
 }
 
 
-#[doc = "
-Provide a callback to be processed by `iotask`
-
-The primary way to do operations again a running `iotask` that
-doesn't involve creating a uv handle via `safe_handle`
-
-# Warning
-
-This function is the only safe way to interact with _any_ `iotask`.
-Using functions in the `uv::ll` module outside of the `cb` passed into
-this function is _very dangerous_.
-
-# Arguments
-
-* iotask - a uv I/O task that you want to do operations against
-* cb - a function callback to be processed on the running loop's
-thread. The only parameter passed in is an opaque pointer representing the
-running `uv_loop_t*`. In the context of this callback, it is safe to use
-this pointer to do various uv_* API calls contained within the `uv::ll`
-module. It is not safe to send the `loop_ptr` param to this callback out
-via ports/chans.
-"]
+/**
+ * Provide a callback to be processed by `iotask`
+ *
+ * The primary way to do operations again a running `iotask` that
+ * doesn't involve creating a uv handle via `safe_handle`
+ *
+ * # Warning
+ *
+ * This function is the only safe way to interact with _any_ `iotask`.
+ * Using functions in the `uv::ll` module outside of the `cb` passed into
+ * this function is _very dangerous_.
+ *
+ * # Arguments
+ *
+ * * iotask - a uv I/O task that you want to do operations against
+ * * cb - a function callback to be processed on the running loop's
+ * thread. The only parameter passed in is an opaque pointer representing the
+ * running `uv_loop_t*`. In the context of this callback, it is safe to use
+ * this pointer to do various uv_* API calls contained within the `uv::ll`
+ * module. It is not safe to send the `loop_ptr` param to this callback out
+ * via ports/chans.
+ */
 unsafe fn interact(iotask: iotask,
                    -cb: fn~(*c_void)) {
     send_msg(iotask, interaction(cb));
 }
 
-#[doc="
-Shut down the I/O task
-
-Is used to signal to the loop that it should close the internally-held
-async handle and do a sanity check to make sure that all other handles are
-closed, causing a failure otherwise.
-"]
+/**
+ * Shut down the I/O task
+ *
+ * Is used to signal to the loop that it should close the internally-held
+ * async handle and do a sanity check to make sure that all other handles are
+ * closed, causing a failure otherwise.
+ */
 fn exit(iotask: iotask) unsafe {
     send_msg(iotask, teardown_loop);
 }
@@ -98,9 +94,7 @@ enum iotask_msg {
     teardown_loop
 }
 
-#[doc = "
-Run the loop and begin handling messages
-"]
+/// Run the loop and begin handling messages
 fn run_loop(iotask_ch: chan<iotask>) unsafe {
 
     let loop_ptr = ll::loop_new();
@@ -147,7 +141,7 @@ fn send_msg(iotask: iotask,
     ll::async_send(iotask.async_handle);
 }
 
-#[doc ="Dispatch all pending messages"]
+/// Dispatch all pending messages
 extern fn wake_up_cb(async_handle: *ll::uv_async_t,
                     status: int) unsafe {
 
diff --git a/src/libstd/uv_ll.rs b/src/libstd/uv_ll.rs
index b302c9103a0..dfb64fc430b 100644
--- a/src/libstd/uv_ll.rs
+++ b/src/libstd/uv_ll.rs
@@ -1,24 +1,24 @@
-#[doc = "
-Low-level bindings to the libuv library.
-
-This module contains a set of direct, 'bare-metal' wrappers around
-the libuv C-API.
-
-Also contained herein are a set of rust records that map, in
-approximate memory-size, to the libuv data structures. The record
-implementations are adjusted, per-platform, to match their respective
-representations.
-
-There are also a collection of helper functions to ease interacting
-with the low-level API (such as a function to return the latest
-libuv error as a rust-formatted string).
-
-As new functionality, existant in uv.h, is added to the rust stdlib,
-the mappings should be added in this module.
-
-This module's implementation will hopefully be, eventually, replaced
-with per-platform, generated source files from rust-bindgen.
-"];
+/*!
+ * Low-level bindings to the libuv library.
+ *
+ * This module contains a set of direct, 'bare-metal' wrappers around
+ * the libuv C-API.
+ *
+ * Also contained herein are a set of rust records that map, in
+ * approximate memory-size, to the libuv data structures. The record
+ * implementations are adjusted, per-platform, to match their respective
+ * representations.
+ *
+ * There are also a collection of helper functions to ease interacting
+ * with the low-level API (such as a function to return the latest
+ * libuv error as a rust-formatted string).
+ *
+ * As new functionality, existant in uv.h, is added to the rust stdlib,
+ * the mappings should be added in this module.
+ *
+ * This module's implementation will hopefully be, eventually, replaced
+ * with per-platform, generated source files from rust-bindgen.
+ */
 
 import libc::size_t;