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

40 files changed, 2709 insertions, 2712 deletions

diff --git a/src/libcore/arc.rs b/src/libcore/arc.rs
index dc2d8da7b7f..04a8751045b 100644
--- a/src/libcore/arc.rs
+++ b/src/libcore/arc.rs
@@ -1,5 +1,7 @@
-#[doc = "An atomically reference counted wrapper that can be used to
-share immutable data between tasks."]
+/**
+ * An atomically reference counted wrapper that can be used to
+ * share immutable data between tasks.
+ */
 
 import comm::{port, chan, methods};
 import sys::methods;
@@ -41,7 +43,7 @@ class arc_destruct<T> {
 
 type arc<T: const> = arc_destruct<T>;
 
-#[doc="Create an atomically reference counted wrapper."]
+/// Create an atomically reference counted wrapper.
 fn arc<T: const>(-data: T) -> arc<T> {
     let data = ~{mut count: 1, data: data};
     unsafe {
@@ -50,8 +52,10 @@ fn arc<T: const>(-data: T) -> arc<T> {
     }
 }
 
-#[doc="Access the underlying data in an atomically reference counted
- wrapper."]
+/**
+ * Access the underlying data in an atomically reference counted
+ * wrapper.
+ */
 fn get<T: const>(rc: &a.arc<T>) -> &a.T {
     unsafe {
         let ptr: ~arc_data<T> = unsafe::reinterpret_cast((*rc).data);
@@ -62,11 +66,13 @@ fn get<T: const>(rc: &a.arc<T>) -> &a.T {
     }
 }
 
-#[doc="Duplicate an atomically reference counted wrapper.
-
-The resulting two `arc` objects will point to the same underlying data
-object. However, one of the `arc` objects can be sent to another task,
-allowing them to share the underlying data."]
+/**
+ * Duplicate an atomically reference counted wrapper.
+ *
+ * The resulting two `arc` objects will point to the same underlying data
+ * object. However, one of the `arc` objects can be sent to another task,
+ * allowing them to share the underlying data.
+ */
 fn clone<T: const>(rc: &arc<T>) -> arc<T> {
     unsafe {
         let ptr: ~arc_data<T> = unsafe::reinterpret_cast((*rc).data);
diff --git a/src/libcore/bool.rs b/src/libcore/bool.rs
index cf7689c57ac..1f0d9174c73 100644
--- a/src/libcore/bool.rs
+++ b/src/libcore/bool.rs
@@ -1,45 +1,43 @@
 // -*- rust -*-
 
-#[doc = "Boolean logic"];
+//! Boolean logic
 
 export not, and, or, xor, implies;
 export eq, ne, is_true, is_false;
 export from_str, to_str, all_values, to_bit;
 
-#[doc = "Negation / inverse"]
+/// Negation / inverse
 pure fn not(v: bool) -> bool { !v }
 
-#[doc = "Conjunction"]
+/// Conjunction
 pure fn and(a: bool, b: bool) -> bool { a && b }
 
-#[doc = "Disjunction"]
+/// Disjunction
 pure fn or(a: bool, b: bool) -> bool { a || b }
 
-#[doc = "
-Exclusive or
-
-Identical to `or(and(a, not(b)), and(not(a), b))`
-"]
+/**
+ * Exclusive or
+ *
+ * Identical to `or(and(a, not(b)), and(not(a), b))`
+ */
 pure fn xor(a: bool, b: bool) -> bool { (a && !b) || (!a && b) }
 
-#[doc = "Implication in the logic, i.e. from `a` follows `b`"]
+/// Implication in the logic, i.e. from `a` follows `b`
 pure fn implies(a: bool, b: bool) -> bool { !a || b }
 
-#[doc = "
-true if truth values `a` and `b` are indistinguishable in the logic
-"]
+/// true if truth values `a` and `b` are indistinguishable in the logic
 pure fn eq(a: bool, b: bool) -> bool { a == b }
 
-#[doc = "true if truth values `a` and `b` are distinguishable in the logic"]
+/// true if truth values `a` and `b` are distinguishable in the logic
 pure fn ne(a: bool, b: bool) -> bool { a != b }
 
-#[doc = "true if `v` represents truth in the logic"]
+/// true if `v` represents truth in the logic
 pure fn is_true(v: bool) -> bool { v }
 
-#[doc = "true if `v` represents falsehood in the logic"]
+/// true if `v` represents falsehood in the logic
 pure fn is_false(v: bool) -> bool { !v }
 
-#[doc = "Parse logic value from `s`"]
+/// Parse logic value from `s`
 pure fn from_str(s: str) -> option<bool> {
     alt check s {
       "true" { some(true) }
@@ -48,19 +46,19 @@ pure fn from_str(s: str) -> option<bool> {
     }
 }
 
-#[doc = "Convert `v` into a string"]
+/// Convert `v` into a string
 pure fn to_str(v: bool) -> str { if v { "true" } else { "false" } }
 
-#[doc = "
-Iterates over all truth values by passing them to `blk` in an unspecified
-order
-"]
+/**
+ * Iterates over all truth values by passing them to `blk` in an unspecified
+ * order
+ */
 fn all_values(blk: fn(v: bool)) {
     blk(true);
     blk(false);
 }
 
-#[doc = "converts truth value to an 8 bit byte"]
+/// converts truth value to an 8 bit byte
 pure fn to_bit(v: bool) -> u8 { if v { 1u8 } else { 0u8 } }
 
 #[test]
diff --git a/src/libcore/box.rs b/src/libcore/box.rs
index 881d736d2ba..bbafc87774d 100644
--- a/src/libcore/box.rs
+++ b/src/libcore/box.rs
@@ -1,9 +1,9 @@
-#[doc = "Operations on shared box types"];
+//! Operations on shared box types
 
 export ptr_eq;
 
 pure fn ptr_eq<T>(a: @T, b: @T) -> bool {
-    #[doc = "Determine if two shared boxes point to the same object"];
+    //! Determine if two shared boxes point to the same object
     unsafe { ptr::addr_of(*a) == ptr::addr_of(*b) }
 }
 
diff --git a/src/libcore/char.rs b/src/libcore/char.rs
index 8e204d89f3f..28645df1b46 100644
--- a/src/libcore/char.rs
+++ b/src/libcore/char.rs
@@ -1,4 +1,4 @@
-#[doc = "Utilities for manipulating the char type"];
+//! Utilities for manipulating the char type
 
 /*
     Lu  Uppercase_Letter    an uppercase letter
@@ -46,27 +46,27 @@ import is_XID_start = unicode::derived_property::XID_Start;
 import is_XID_continue = unicode::derived_property::XID_Continue;
 
 
-#[doc = "
-Indicates whether a character is in lower case, defined
-in terms of the Unicode General Category 'Ll'
-"]
+/**
+ * Indicates whether a character is in lower case, defined
+ * in terms of the Unicode General Category 'Ll'
+ */
 pure fn is_lowercase(c: char) -> bool {
     ret unicode::general_category::Ll(c);
 }
 
-#[doc = "
-Indicates whether a character is in upper case, defined
-in terms of the Unicode General Category 'Lu'.
-"]
+/**
+ * Indicates whether a character is in upper case, defined
+ * in terms of the Unicode General Category 'Lu'.
+ */
 pure fn is_uppercase(c: char) -> bool {
     ret unicode::general_category::Lu(c);
 }
 
-#[doc = "
-Indicates whether a character is whitespace, defined in
-terms of the Unicode General Categories 'Zs', 'Zl', 'Zp'
-additional 'Cc'-category control codes in the range [0x09, 0x0d]/~
-"]
+/**
+ * Indicates whether a character is whitespace, defined in
+ * terms of the Unicode General Categories 'Zs', 'Zl', 'Zp'
+ * additional 'Cc'-category control codes in the range [0x09, 0x0d]
+ */
 pure fn is_whitespace(c: char) -> bool {
     ret ('\x09' <= c && c <= '\x0d')
         || unicode::general_category::Zs(c)
@@ -74,11 +74,11 @@ pure fn is_whitespace(c: char) -> bool {
         || unicode::general_category::Zp(c);
 }
 
-#[doc = "
-Indicates whether a character is alphanumeric, defined
-in terms of the Unicode General Categories 'Nd',
-'Nl', 'No' and the Derived Core Property 'Alphabetic'.
-"]
+/**
+ * Indicates whether a character is alphanumeric, defined
+ * in terms of the Unicode General Categories 'Nd',
+ * 'Nl', 'No' and the Derived Core Property 'Alphabetic'.
+ */
 pure fn is_alphanumeric(c: char) -> bool {
     ret unicode::derived_property::Alphabetic(c) ||
         unicode::general_category::Nd(c) ||
@@ -86,32 +86,32 @@ pure fn is_alphanumeric(c: char) -> bool {
         unicode::general_category::No(c);
 }
 
-#[doc = "Indicates whether the character is an ASCII character"]
+/// Indicates whether the character is an ASCII character
 pure fn is_ascii(c: char) -> bool {
    c - ('\x7F' & c) == '\x00'
 }
 
-#[doc = "Indicates whether the character is numeric (Nd, Nl, or No)"]
+/// Indicates whether the character is numeric (Nd, Nl, or No)
 pure fn is_digit(c: char) -> bool {
     ret unicode::general_category::Nd(c) ||
         unicode::general_category::Nl(c) ||
         unicode::general_category::No(c);
 }
 
-#[doc = "
-Convert a char to the corresponding digit.
-
-# Safety note
-
-This function fails if `c` is not a valid char
-
-# Return value
-
-If `c` is between '0' and '9', the corresponding value
-between 0 and 9. If `c` is 'a' or 'A', 10. If `c` is
-'b' or 'B', 11, etc. Returns none if the char does not
-refer to a digit in the given radix.
-"]
+/**
+ * Convert a char to the corresponding digit.
+ *
+ * # Safety note
+ *
+ * This function fails if `c` is not a valid char
+ *
+ * # Return value
+ *
+ * If `c` is between '0' and '9', the corresponding value
+ * between 0 and 9. If `c` is 'a' or 'A', 10. If `c` is
+ * 'b' or 'B', 11, etc. Returns none if the char does not
+ * refer to a digit in the given radix.
+ */
 pure fn to_digit(c: char, radix: uint) -> option<uint> {
     let val = alt c {
       '0' to '9' { c as uint - ('0' as uint) }
@@ -123,15 +123,15 @@ pure fn to_digit(c: char, radix: uint) -> option<uint> {
     else { none }
 }
 
-#[doc = "
-Return the hexadecimal unicode escape of a char.
-
-The rules are as follows:
-
-  - chars in [0,0xff]/~ get 2-digit escapes: `\\xNN`
-  - chars in [0x100,0xffff]/~ get 4-digit escapes: `\\uNNNN`
-  - chars above 0x10000 get 8-digit escapes: `\\UNNNNNNNN`
-"]
+/**
+ * Return the hexadecimal unicode escape of a char.
+ *
+ * The rules are as follows:
+ *
+ *   - chars in [0,0xff] get 2-digit escapes: `\\xNN`
+ *   - chars in [0x100,0xffff] get 4-digit escapes: `\\uNNNN`
+ *   - chars above 0x10000 get 8-digit escapes: `\\UNNNNNNNN`
+ */
 fn escape_unicode(c: char) -> str {
     let s = u32::to_str(c as u32, 16u);
     let (c, pad) = (if c <= '\xff' { ('x', 2u) }
@@ -145,18 +145,18 @@ fn escape_unicode(c: char) -> str {
     ret out;
 }
 
-#[doc = "
-Return a 'default' ASCII and C++11-like char-literal escape of a char.
-
-The default is chosen with a bias toward producing literals that are
-legal in a variety of languages, including C++11 and similar C-family
-languages. The exact rules are:
-
-  - Tab, CR and LF are escaped as '\t', '\r' and '\n' respectively.
-  - Single-quote, double-quote and backslash chars are backslash-escaped.
-  - Any other chars in the range [0x20,0x7e]/~ are not escaped.
-  - Any other chars are given hex unicode escapes; see `escape_unicode`.
-"]
+/**
+ * Return a 'default' ASCII and C++11-like char-literal escape of a char.
+ *
+ * The default is chosen with a bias toward producing literals that are
+ * legal in a variety of languages, including C++11 and similar C-family
+ * languages. The exact rules are:
+ *
+ *   - Tab, CR and LF are escaped as '\t', '\r' and '\n' respectively.
+ *   - Single-quote, double-quote and backslash chars are backslash-escaped.
+ *   - Any other chars in the range [0x20,0x7e] are not escaped.
+ *   - Any other chars are given hex unicode escapes; see `escape_unicode`.
+ */
 fn escape_default(c: char) -> str {
     alt c {
       '\t' { "\\t" }
@@ -170,13 +170,13 @@ fn escape_default(c: char) -> str {
     }
 }
 
-#[doc = "
-Compare two chars
-
-# Return value
-
--1 if a < b, 0 if a == b, +1 if a > b
-"]
+/**
+ * Compare two chars
+ *
+ * # Return value
+ *
+ * -1 if a < b, 0 if a == b, +1 if a > b
+ */
 pure fn cmp(a: char, b: char) -> int {
     ret  if b > a { -1 }
     else if b < a { 1 }
diff --git a/src/libcore/cmp.rs b/src/libcore/cmp.rs
index aea97cf1649..1bdf3b9909a 100644
--- a/src/libcore/cmp.rs
+++ b/src/libcore/cmp.rs
@@ -1,4 +1,4 @@
-#[doc="Interfaces used for comparison."]
+/// Interfaces used for comparison.
 
 iface ord {
     fn lt(&&other: self) -> bool;
diff --git a/src/libcore/comm.rs b/src/libcore/comm.rs
index 6190752059e..7276bea5b1c 100644
--- a/src/libcore/comm.rs
+++ b/src/libcore/comm.rs
@@ -1,28 +1,28 @@
-#[doc = "
-Communication between tasks
-
-Communication between tasks is facilitated by ports (in the receiving
-task), and channels (in the sending task). Any number of channels may
-feed into a single port.  Ports and channels may only transmit values
-of unique types; that is, values that are statically guaranteed to be
-accessed by a single 'owner' at a time.  Unique types include scalars,
-vectors, strings, and records, tags, tuples and unique boxes (`~T`)
-thereof. Most notably, shared boxes (`@T`) may not be transmitted
-across channels.
-
-# Example
-
-~~~
-let po = comm::port();
-let ch = comm::chan(po);
-
-task::spawn {||
-    comm::send(ch, \"Hello, World\");
-});
-
-io::println(comm::recv(p));
-~~~
-"];
+/*!
+ * Communication between tasks
+ *
+ * Communication between tasks is facilitated by ports (in the receiving
+ * task), and channels (in the sending task). Any number of channels may
+ * feed into a single port.  Ports and channels may only transmit values
+ * of unique types; that is, values that are statically guaranteed to be
+ * accessed by a single 'owner' at a time.  Unique types include scalars,
+ * vectors, strings, and records, tags, tuples and unique boxes (`~T`)
+ * thereof. Most notably, shared boxes (`@T`) may not be transmitted
+ * across channels.
+ *
+ * # Example
+ *
+ * ~~~
+ * let po = comm::port();
+ * let ch = comm::chan(po);
+ *
+ * task::spawn {||
+ *     comm::send(ch, "Hello, World");
+ * });
+ *
+ * io::println(comm::recv(p));
+ * ~~~
+ */
 
 import either::either;
 import libc::size_t;
@@ -38,34 +38,34 @@ export methods;
 export listen;
 
 
-#[doc = "
-A communication endpoint that can receive messages
-
-Each port has a unique per-task identity and may not be replicated or
-transmitted. If a port value is copied, both copies refer to the same
-port.  Ports may be associated with multiple `chan`s.
-"]
+/**
+ * A communication endpoint that can receive messages
+ *
+ * Each port has a unique per-task identity and may not be replicated or
+ * transmitted. If a port value is copied, both copies refer to the same
+ * port.  Ports may be associated with multiple `chan`s.
+ */
 enum port<T: send> {
     port_t(@port_ptr<T>)
 }
 
 // It's critical that this only have one variant, so it has a record
 // layout, and will work in the rust_task structure in task.rs.
-#[doc = "
-A communication endpoint that can send messages
-
-Each channel is bound to a port when the channel is constructed, so
-the destination port for a channel must exist before the channel
-itself.  Channels are weak: a channel does not keep the port it is
-bound to alive. If a channel attempts to send data to a dead port that
-data will be silently dropped.  Channels may be duplicated and
-themselves transmitted over other channels.
-"]
+/**
+ * A communication endpoint that can send messages
+ *
+ * Each channel is bound to a port when the channel is constructed, so
+ * the destination port for a channel must exist before the channel
+ * itself.  Channels are weak: a channel does not keep the port it is
+ * bound to alive. If a channel attempts to send data to a dead port that
+ * data will be silently dropped.  Channels may be duplicated and
+ * themselves transmitted over other channels.
+ */
 enum chan<T: send> {
     chan_t(port_id)
 }
 
-#[doc = "Constructs a port"]
+/// Constructs a port
 fn port<T: send>() -> port<T> {
     port_t(@port_ptr(rustrt::new_port(sys::size_of::<T>() as size_t)))
 }
@@ -88,7 +88,7 @@ impl methods<T: send> for chan<T> {
 
 }
 
-#[doc = "Open a new receiving channel for the duration of a function"]
+/// Open a new receiving channel for the duration of a function
 fn listen<T: send, U>(f: fn(chan<T>) -> U) -> U {
     let po = port();
     f(po.chan())
@@ -119,14 +119,14 @@ class port_ptr<T:send> {
   }
 }
 
-#[doc = "
-Internal function for converting from a channel to a port
-
-# Failure
-
-Fails if the port is detached or dead. Fails if the port
-is owned by a different task.
-"]
+/**
+ * Internal function for converting from a channel to a port
+ *
+ * # Failure
+ *
+ * Fails if the port is detached or dead. Fails if the port
+ * is owned by a different task.
+ */
 fn as_raw_port<T: send, U>(ch: comm::chan<T>, f: fn(*rust_port) -> U) -> U {
 
     class portref {
@@ -150,18 +150,18 @@ fn as_raw_port<T: send, U>(ch: comm::chan<T>, f: fn(*rust_port) -> U) -> U {
     f(p.p)
 }
 
-#[doc = "
-Constructs a channel. The channel is bound to the port used to
-construct it.
-"]
+/**
+ * Constructs a channel. The channel is bound to the port used to
+ * construct it.
+ */
 fn chan<T: send>(p: port<T>) -> chan<T> {
     chan_t(rustrt::get_port_id((**p).po))
 }
 
-#[doc = "
-Sends data over a channel. The sent data is moved into the channel,
-whereupon the caller loses access to it.
-"]
+/**
+ * Sends data over a channel. The sent data is moved into the channel,
+ * whereupon the caller loses access to it.
+ */
 fn send<T: send>(ch: chan<T>, -data: T) {
     let chan_t(p) = ch;
     let data_ptr = ptr::addr_of(data) as *();
@@ -173,13 +173,13 @@ fn send<T: send>(ch: chan<T>, -data: T) {
     task::yield();
 }
 
-#[doc = "
-Receive from a port.  If no data is available on the port then the
-task will block until data becomes available.
-"]
+/**
+ * Receive from a port.  If no data is available on the port then the
+ * task will block until data becomes available.
+ */
 fn recv<T: send>(p: port<T>) -> T { recv_((**p).po) }
 
-#[doc = "Returns true if there are messages available"]
+/// Returns true if there are messages available
 fn peek<T: send>(p: port<T>) -> bool { peek_((**p).po) }
 
 #[doc(hidden)]
@@ -191,7 +191,7 @@ fn peek_chan<T: send>(ch: comm::chan<T>) -> bool {
     as_raw_port(ch, |x|peek_(x))
 }
 
-#[doc = "Receive on a raw port pointer"]
+/// Receive on a raw port pointer
 fn recv_<T: send>(p: *rust_port) -> T {
     let yield = 0u;
     let yieldp = ptr::addr_of(yield);
@@ -214,7 +214,7 @@ fn peek_(p: *rust_port) -> bool {
     rustrt::rust_port_size(p) != 0u as libc::size_t
 }
 
-#[doc = "Receive on one of two ports"]
+/// Receive on one of two ports
 fn select2<A: send, B: send>(p_a: port<A>, p_b: port<B>)
     -> either<A, B> {
     let ports = ~[(**p_a).po, (**p_b).po];
diff --git a/src/libcore/core.rc b/src/libcore/core.rc
index fd1d20f9d6e..58f2281daf3 100644
--- a/src/libcore/core.rc
+++ b/src/libcore/core.rc
@@ -7,26 +7,26 @@
 #[license = "MIT"];
 #[crate_type = "lib"];
 
-#[doc = "
-The Rust core library provides functionality that is closely tied to the Rust
-built-in types and runtime services, or that is used in nearly every
-non-trivial program.
-
-`core` includes modules corresponding to each of the integer types, each of
-the floating point types, the `bool` type, tuples, characters, strings,
-vectors (`vec`), shared boxes (`box`), and unsafe pointers (`ptr`).
-Additionally, `core` provides very commonly used built-in types and
-operations, concurrency primitives, platform abstractions, I/O, and complete
-bindings to the C standard library.
-
-`core` is linked by default to all crates and the contents imported.
-Implicitly, all crates behave as if they included the following prologue:
-
-    use core;
-    import core::*;
-
-This behavior can be disabled with the `#[no_core]` crate attribute.
-"];
+/*!
+ * The Rust core library provides functionality that is closely tied to the
+ * Rust built-in types and runtime services, or that is used in nearly every
+ * non-trivial program.
+ *
+ * `core` includes modules corresponding to each of the integer types, each of
+ * the floating point types, the `bool` type, tuples, characters, strings,
+ * vectors (`vec`), shared boxes (`box`), and unsafe pointers (`ptr`).
+ * Additionally, `core` provides very commonly used built-in types and
+ * operations, concurrency primitives, platform abstractions, I/O, and
+ * complete bindings to the C standard library.
+ *
+ * `core` is linked by default to all crates and the contents imported.
+ * Implicitly, all crates behave as if they included the following prologue:
+ *
+ *     use core;
+ *     import core::*;
+ *
+ * This behavior can be disabled with the `#[no_core]` crate attribute.
+ */
 
 // Don't link to core. We are core.
 #[no_core];
@@ -58,7 +58,7 @@ export priv;
 
 // Built-in-type support modules
 
-#[doc = "Operations and constants for `int`"]
+/// Operations and constants for `int`
 #[path = "int-template"]
 mod int {
     import inst::{ hash, pow };
@@ -67,35 +67,35 @@ mod int {
     mod inst;
 }
 
-#[doc = "Operations and constants for `i8`"]
+/// Operations and constants for `i8`
 #[path = "int-template"]
 mod i8 {
     #[path = "i8.rs"]
     mod inst;
 }
 
-#[doc = "Operations and constants for `i16`"]
+/// Operations and constants for `i16`
 #[path = "int-template"]
 mod i16 {
     #[path = "i16.rs"]
     mod inst;
 }
 
-#[doc = "Operations and constants for `i32`"]
+/// Operations and constants for `i32`
 #[path = "int-template"]
 mod i32 {
     #[path = "i32.rs"]
     mod inst;
 }
 
-#[doc = "Operations and constants for `i64`"]
+/// Operations and constants for `i64`
 #[path = "int-template"]
 mod i64 {
     #[path = "i64.rs"]
     mod inst;
 }
 
-#[doc = "Operations and constants for `uint`"]
+/// Operations and constants for `uint`
 #[path = "uint-template"]
 mod uint {
     import inst::{
@@ -109,7 +109,7 @@ mod uint {
     mod inst;
 }
 
-#[doc = "Operations and constants for `u8`"]
+/// Operations and constants for `u8`
 #[path = "uint-template"]
 mod u8 {
     import inst::is_ascii;
@@ -119,21 +119,21 @@ mod u8 {
     mod inst;
 }
 
-#[doc = "Operations and constants for `u16`"]
+/// Operations and constants for `u16`
 #[path = "uint-template"]
 mod u16 {
     #[path = "u16.rs"]
     mod inst;
 }
 
-#[doc = "Operations and constants for `u32`"]
+/// Operations and constants for `u32`
 #[path = "uint-template"]
 mod u32 {
     #[path = "u32.rs"]
     mod inst;
 }
 
-#[doc = "Operations and constants for `u64`"]
+/// Operations and constants for `u64`
 #[path = "uint-template"]
 mod u64 {
     #[path = "u64.rs"]
diff --git a/src/libcore/core.rs b/src/libcore/core.rs
index ed61c587116..f97d2727194 100644
--- a/src/libcore/core.rs
+++ b/src/libcore/core.rs
@@ -37,13 +37,13 @@ export num;
 
 export error, warn, info, debug;
 
-#[doc = "The error log level"]
+/// The error log level
 const error : u32 = 0_u32;
-#[doc = "The warning log level"]
+/// The warning log level
 const warn : u32 = 1_u32;
-#[doc = "The info log level"]
+/// The info log level
 const info : u32 = 2_u32;
-#[doc = "The debug log level"]
+/// The debug log level
 const debug : u32 = 3_u32;
 
 // A curious inner-module that's not exported that contains the binding
@@ -63,11 +63,11 @@ mod std {
     import std::test;
 }
 
-#[doc = "
-A standard function to use to indicate unreachable code. Because the
-function is guaranteed to fail typestate will correctly identify
-any code paths following the appearance of this function as unreachable.
-"]
+/**
+ * A standard function to use to indicate unreachable code. Because the
+ * function is guaranteed to fail typestate will correctly identify
+ * any code paths following the appearance of this function as unreachable.
+ */
 fn unreachable() -> ! {
     fail "Internal error: entered unreachable code";
 }
diff --git a/src/libcore/dlist.rs b/src/libcore/dlist.rs
index aae0ffb2519..f80972d50b3 100644
--- a/src/libcore/dlist.rs
+++ b/src/libcore/dlist.rs
@@ -1,8 +1,8 @@
-#[doc = "
-A doubly-linked list. Supports O(1) head, tail, count, push, pop, etc.
-
-Do not use ==, !=, <, etc on doubly-linked lists -- it may not terminate.
-"]
+/**
+ * A doubly-linked list. Supports O(1) head, tail, count, push, pop, etc.
+ *
+ * Do not use ==, !=, <, etc on doubly-linked lists -- it may not terminate.
+ */
 
 import dlist_iter::extensions;
 
@@ -57,24 +57,24 @@ impl private_methods<T> for dlist_node<T> {
 }
 
 impl extensions<T> for dlist_node<T> {
-    #[doc = "Get the next node in the list, if there is one."]
+    /// Get the next node in the list, if there is one.
     pure fn next_link() -> option<dlist_node<T>> {
         self.assert_links();
         self.next
     }
-    #[doc = "Get the next node in the list, failing if there isn't one."]
+    /// Get the next node in the list, failing if there isn't one.
     pure fn next_node() -> dlist_node<T> {
         alt self.next_link() {
             some(nobe) { nobe }
             none       { fail "This dlist node has no next neighbour." }
         }
     }
-    #[doc = "Get the previous node in the list, if there is one."]
+    /// Get the previous node in the list, if there is one.
     pure fn prev_link() -> option<dlist_node<T>> {
         self.assert_links();
         self.prev
     }
-    #[doc = "Get the previous node in the list, failing if there isn't one."]
+    /// Get the previous node in the list, failing if there isn't one.
     pure fn prev_node() -> dlist_node<T> {
         alt self.prev_link() {
             some(nobe) { nobe }
@@ -82,7 +82,7 @@ impl extensions<T> for dlist_node<T> {
         }
     }
 
-    #[doc = "Remove a node from whatever dlist it's on (failing if none)."]
+    /// Remove a node from whatever dlist it's on (failing if none).
     fn remove() {
         if option::is_some(self.root) {
             option::get(self.root).remove(self);
@@ -92,17 +92,17 @@ impl extensions<T> for dlist_node<T> {
     }
 }
 
-#[doc = "Creates a new dlist node with the given data."]
+/// Creates a new dlist node with the given data.
 pure fn create_node<T>(+data: T) -> dlist_node<T> {
     dlist_node(@{data: data, mut root: none, mut prev: none, mut next: none})
 }
 
-#[doc = "Creates a new, empty dlist."]
+/// Creates a new, empty dlist.
 pure fn create<T>() -> dlist<T> {
     dlist(@{mut size: 0, mut hd: none, mut tl: none})
 }
 
-#[doc = "Creates a new dlist with a single element"]
+/// Creates a new dlist with a single element
 fn from_elt<T>(+data: T) -> dlist<T> {
     let list = create();
     list.push(data);
@@ -184,97 +184,113 @@ impl private_methods<T> for dlist<T> {
 }
 
 impl extensions<T> for dlist<T> {
-    #[doc = "Get the size of the list. O(1)."]
+    /// Get the size of the list. O(1).
     pure fn len()          -> uint { self.size }
-    #[doc = "Returns true if the list is empty. O(1)."]
+    /// Returns true if the list is empty. O(1).
     pure fn is_empty()     -> bool { self.len() == 0 }
-    #[doc = "Returns true if the list is not empty. O(1)."]
+    /// Returns true if the list is not empty. O(1).
     pure fn is_not_empty() -> bool { self.len() != 0 }
 
-    #[doc = "Add data to the head of the list. O(1)."]
+    /// Add data to the head of the list. O(1).
     fn push_head(+data: T) {
         self.add_head(self.new_link(data));
     }
-    #[doc = "Add data to the head of the list, and get the new containing
-             node. O(1)."]
+    /**
+     * Add data to the head of the list, and get the new containing
+     * node. O(1).
+     */
     fn push_head_n(+data: T) -> dlist_node<T> {
         let mut nobe = self.new_link(data);
         self.add_head(nobe);
         option::get(nobe)
     }
-    #[doc = "Add data to the tail of the list. O(1)."]
+    /// Add data to the tail of the list. O(1).
     fn push(+data: T) {
         self.add_tail(self.new_link(data));
     }
-    #[doc = "Add data to the tail of the list, and get the new containing
-             node. O(1)."]
+    /**
+     * Add data to the tail of the list, and get the new containing
+     * node. O(1).
+     */
     fn push_n(+data: T) -> dlist_node<T> {
         let mut nobe = self.new_link(data);
         self.add_tail(nobe);
         option::get(nobe)
     }
-    #[doc = "Insert data into the middle of the list, left of the given node.
-             O(1)."]
+    /**
+     * Insert data into the middle of the list, left of the given node.
+     * O(1).
+     */
     fn insert_before(+data: T, neighbour: dlist_node<T>) {
         self.insert_left(self.new_link(data), neighbour);
     }
-    #[doc = "Insert an existing node in the middle of the list, left of the
-             given node. O(1)."]
+    /**
+     * Insert an existing node in the middle of the list, left of the
+     * given node. O(1).
+     */
     fn insert_n_before(nobe: dlist_node<T>, neighbour: dlist_node<T>) {
         self.make_mine(nobe);
         self.insert_left(some(nobe), neighbour);
     }
-    #[doc = "Insert data in the middle of the list, left of the given node,
-             and get its containing node. O(1)."]
+    /**
+     * Insert data in the middle of the list, left of the given node,
+     * and get its containing node. O(1).
+     */
     fn insert_before_n(+data: T, neighbour: dlist_node<T>) -> dlist_node<T> {
         let mut nobe = self.new_link(data);
         self.insert_left(nobe, neighbour);
         option::get(nobe)
     }
-    #[doc = "Insert data into the middle of the list, right of the given node.
-             O(1)."]
+    /**
+     * Insert data into the middle of the list, right of the given node.
+     * O(1).
+     */
     fn insert_after(+data: T, neighbour: dlist_node<T>) {
         self.insert_right(neighbour, self.new_link(data));
     }
-    #[doc = "Insert an existing node in the middle of the list, right of the
-             given node. O(1)."]
+    /**
+     * Insert an existing node in the middle of the list, right of the
+     * given node. O(1).
+     */
     fn insert_n_after(nobe: dlist_node<T>, neighbour: dlist_node<T>) {
         self.make_mine(nobe);
         self.insert_right(neighbour, some(nobe));
     }
-    #[doc = "Insert data in the middle of the list, right of the given node,
-             and get its containing node. O(1)."]
+    /**
+     * Insert data in the middle of the list, right of the given node,
+     * and get its containing node. O(1).
+     */
     fn insert_after_n(+data: T, neighbour: dlist_node<T>) -> dlist_node<T> {
         let mut nobe = self.new_link(data);
         self.insert_right(neighbour, nobe);
         option::get(nobe)
     }
 
-    #[doc = "Remove a node from the head of the list. O(1)."]
+    /// Remove a node from the head of the list. O(1).
     fn pop_n() -> option<dlist_node<T>> {
         let hd = self.peek_n();
         hd.map(|nobe| self.unlink(nobe));
         hd
     }
-    #[doc = "Remove a node from the tail of the list. O(1)."]
+    /// Remove a node from the tail of the list. O(1).
     fn pop_tail_n() -> option<dlist_node<T>> {
         let tl = self.peek_tail_n();
         tl.map(|nobe| self.unlink(nobe));
         tl
     }
-    #[doc = "Get the node at the list's head. O(1)."]
+    /// Get the node at the list's head. O(1).
     pure fn peek_n() -> option<dlist_node<T>> { self.hd }
-    #[doc = "Get the node at the list's tail. O(1)."]
+    /// Get the node at the list's tail. O(1).
     pure fn peek_tail_n() -> option<dlist_node<T>> { self.tl }
 
-    #[doc = "Get the node at the list's head, failing if empty. O(1)."]
+    /// Get the node at the list's head, failing if empty. O(1).
     pure fn head_n() -> dlist_node<T> {
         alt self.hd {
             some(nobe) { nobe }
             none       { fail "Attempted to get the head of an empty dlist." }
         }
     }
-    #[doc = "Get the node at the list's tail, failing if empty. O(1)."]
+    /// Get the node at the list's tail, failing if empty. O(1).
     pure fn tail_n() -> dlist_node<T> {
         alt self.tl {
             some(nobe) { nobe }
@@ -282,10 +298,10 @@ impl extensions<T> for dlist<T> {
         }
     }
 
-    #[doc = "Remove a node from anywhere in the list. O(1)."]
+    /// Remove a node from anywhere in the list. O(1).
     fn remove(nobe: dlist_node<T>) { self.unlink(nobe); }
 
-    #[doc = "Check data structure integrity. O(n)."]
+    /// Check data structure integrity. O(n).
     fn assert_consistent() {
         if option::is_none(self.hd) || option::is_none(self.tl) {
             assert option::is_none(self.hd) && option::is_none(self.tl);
@@ -333,17 +349,17 @@ impl extensions<T> for dlist<T> {
 }
 
 impl extensions<T: copy> for dlist<T> {
-    #[doc = "Remove data from the head of the list. O(1)."]
+    /// Remove data from the head of the list. O(1).
     fn pop()       -> option<T> { self.pop_n().map       (|nobe| nobe.data) }
-    #[doc = "Remove data from the tail of the list. O(1)."]
+    /// Remove data from the tail of the list. O(1).
     fn pop_tail()  -> option<T> { self.pop_tail_n().map  (|nobe| nobe.data) }
-    #[doc = "Get data at the list's head. O(1)."]
+    /// Get data at the list's head. O(1).
     fn peek()      -> option<T> { self.peek_n().map      (|nobe| nobe.data) }
-    #[doc = "Get data at the list's tail. O(1)."]
+    /// Get data at the list's tail. O(1).
     fn peek_tail() -> option<T> { self.peek_tail_n().map (|nobe| nobe.data) }
-    #[doc = "Get data at the list's head, failing if empty. O(1)."]
+    /// Get data at the list's head, failing if empty. O(1).
     pure fn head() -> T         { self.head_n().data }
-    #[doc = "Get data at the list's tail, failing if empty. O(1)."]
+    /// Get data at the list's tail, failing if empty. O(1).
     pure fn tail() -> T         { self.tail_n().data }
 }
 
diff --git a/src/libcore/dvec.rs b/src/libcore/dvec.rs
index aad8825a52b..9c1d6cae36b 100644
--- a/src/libcore/dvec.rs
+++ b/src/libcore/dvec.rs
@@ -15,59 +15,57 @@ export from_vec;
 export extensions;
 export unwrap;
 
-#[doc = "
-
-A growable, modifiable vector type that accumulates elements into a
-unique vector.
-
-# Limitations on recursive use
-
-This class works by swapping the unique vector out of the data
-structure whenever it is to be used.  Therefore, recursive use is not
-permitted.  That is, while iterating through a vector, you cannot
-access the vector in any other way or else the program will fail.  If
-you wish, you can use the `swap()` method to gain access to the raw
-vector and transform it or use it any way you like.  Eventually, we
-may permit read-only access during iteration or other use.
-
-# WARNING
-
-For maximum performance, this type is implemented using some rather
-unsafe code.  In particular, this innocent looking `[mut A]/~` pointer
-*may be null!*  Therefore, it is important you not reach into the
-data structure manually but instead use the provided extensions.
-
-The reason that I did not use an unsafe pointer in the structure
-itself is that I wanted to ensure that the vector would be freed when
-the dvec is dropped.  The reason that I did not use an `option<T>`
-instead of a nullable pointer is that I found experimentally that it
-becomes approximately 50% slower. This can probably be improved
-through optimization.  You can run your own experiments using
-`src/test/bench/vec-append.rs`. My own tests found that using null
-pointers achieved about 103 million pushes/second.  Using an option
-type could only produce 47 million pushes/second.
-
-"]
+/**
+ * A growable, modifiable vector type that accumulates elements into a
+ * unique vector.
+ *
+ * # Limitations on recursive use
+ *
+ * This class works by swapping the unique vector out of the data
+ * structure whenever it is to be used.  Therefore, recursive use is not
+ * permitted.  That is, while iterating through a vector, you cannot
+ * access the vector in any other way or else the program will fail.  If
+ * you wish, you can use the `swap()` method to gain access to the raw
+ * vector and transform it or use it any way you like.  Eventually, we
+ * may permit read-only access during iteration or other use.
+ *
+ * # WARNING
+ *
+ * For maximum performance, this type is implemented using some rather
+ * unsafe code.  In particular, this innocent looking `[mut A]/~` pointer
+ * *may be null!*  Therefore, it is important you not reach into the
+ * data structure manually but instead use the provided extensions.
+ *
+ * The reason that I did not use an unsafe pointer in the structure
+ * itself is that I wanted to ensure that the vector would be freed when
+ * the dvec is dropped.  The reason that I did not use an `option<T>`
+ * instead of a nullable pointer is that I found experimentally that it
+ * becomes approximately 50% slower. This can probably be improved
+ * through optimization.  You can run your own experiments using
+ * `src/test/bench/vec-append.rs`. My own tests found that using null
+ * pointers achieved about 103 million pushes/second.  Using an option
+ * type could only produce 47 million pushes/second.
+ */
 type dvec<A> = {
     mut data: ~[mut A]
 };
 
-#[doc = "Creates a new, empty dvec"]
+/// Creates a new, empty dvec
 fn dvec<A>() -> dvec<A> {
     {mut data: ~[mut]}
 }
 
-#[doc = "Creates a new dvec with a single element"]
+/// Creates a new dvec with a single element
 fn from_elt<A>(+e: A) -> dvec<A> {
     {mut data: ~[mut e]}
 }
 
-#[doc = "Creates a new dvec with the contents of a vector"]
+/// Creates a new dvec with the contents of a vector
 fn from_vec<A>(+v: ~[mut A]) -> dvec<A> {
     {mut data: v}
 }
 
-#[doc = "Consumes the vector and returns its contents"]
+/// Consumes the vector and returns its contents
 fn unwrap<A>(-d: dvec<A>) -> ~[mut A] {
     let {data: v} <- d;
     ret v;
@@ -106,19 +104,17 @@ impl private_methods<A> for dvec<A> {
 // almost nothing works without the copy bound due to limitations
 // around closures.
 impl extensions<A> for dvec<A> {
-    #[doc = "
-
-    Swaps out the current vector and hands it off to a user-provided
-    function `f`.  The function should transform it however is desired
-    and return a new vector to replace it with.
-
-    "]
+    /**
+     * Swaps out the current vector and hands it off to a user-provided
+     * function `f`.  The function should transform it however is desired
+     * and return a new vector to replace it with.
+     */
     #[inline(always)]
     fn swap(f: fn(-~[mut A]) -> ~[mut A]) {
         self.borrow(|v| self.return(f(v)))
     }
 
-    #[doc = "Returns the number of elements currently in the dvec"]
+    /// Returns the number of elements currently in the dvec
     fn len() -> uint {
         do self.borrow |v| {
             let l = v.len();
@@ -127,13 +123,13 @@ impl extensions<A> for dvec<A> {
         }
     }
 
-    #[doc = "Overwrite the current contents"]
+    /// Overwrite the current contents
     fn set(+w: ~[mut A]) {
         self.check_not_borrowed();
         self.data <- w;
     }
 
-    #[doc = "Remove and return the last element"]
+    /// Remove and return the last element
     fn pop() -> A {
         do self.borrow |v| {
             let mut v <- v;
@@ -143,7 +139,7 @@ impl extensions<A> for dvec<A> {
         }
     }
 
-    #[doc = "Insert a single item at the front of the list"]
+    /// Insert a single item at the front of the list
     fn unshift(-t: A) {
         unsafe {
             let mut data = unsafe::reinterpret_cast(null::<()>());
@@ -157,13 +153,13 @@ impl extensions<A> for dvec<A> {
         }
     }
 
-    #[doc = "Append a single item to the end of the list"]
+    /// Append a single item to the end of the list
     fn push(+t: A) {
         self.check_not_borrowed();
         vec::push(self.data, t);
     }
 
-    #[doc = "Remove and return the first element"]
+    /// Remove and return the first element
     fn shift() -> A {
         do self.borrow |v| {
             let mut v = vec::from_mut(v);
@@ -175,18 +171,16 @@ impl extensions<A> for dvec<A> {
 }
 
 impl extensions<A:copy> for dvec<A> {
-    #[doc = "
-        Append all elements of a vector to the end of the list
-
-        Equivalent to `append_iter()` but potentially more efficient.
-    "]
+    /**
+     * Append all elements of a vector to the end of the list
+     *
+     * Equivalent to `append_iter()` but potentially more efficient.
+     */
     fn push_all(ts: &[const A]) {
         self.push_slice(ts, 0u, vec::len(ts));
     }
 
-    #[doc = "
-        Appends elements from `from_idx` to `to_idx` (exclusive)
-    "]
+    /// Appends elements from `from_idx` to `to_idx` (exclusive)
     fn push_slice(ts: &[const A], from_idx: uint, to_idx: uint) {
         do self.swap |v| {
             let mut v <- v;
@@ -202,12 +196,12 @@ impl extensions<A:copy> for dvec<A> {
     }
 
     /*
-    #[doc = "
-        Append all elements of an iterable.
-
-        Failure will occur if the iterable's `each()` method
-        attempts to access this vector.
-    "]
+    /**
+     * Append all elements of an iterable.
+     *
+     * Failure will occur if the iterable's `each()` method
+     * attempts to access this vector.
+     */
     fn append_iter<A, I:iter::base_iter<A>>(ts: I) {
         do self.swap |v| {
            let mut v = alt ts.size_hint() {
@@ -226,11 +220,11 @@ impl extensions<A:copy> for dvec<A> {
     }
     */
 
-    #[doc = "
-        Gets a copy of the current contents.
-
-        See `unwrap()` if you do not wish to copy the contents.
-    "]
+    /**
+     * Gets a copy of the current contents.
+     *
+     * See `unwrap()` if you do not wish to copy the contents.
+     */
     fn get() -> ~[A] {
         do self.borrow |v| {
             let w = vec::from_mut(copy v);
@@ -239,28 +233,30 @@ impl extensions<A:copy> for dvec<A> {
         }
     }
 
-    #[doc = "Copy out an individual element"]
+    /// Copy out an individual element
     #[inline(always)]
     fn [](idx: uint) -> A {
         self.get_elt(idx)
     }
 
-    #[doc = "Copy out an individual element"]
+    /// Copy out an individual element
     #[inline(always)]
     fn get_elt(idx: uint) -> A {
         self.check_not_borrowed();
         ret self.data[idx];
     }
 
-    #[doc = "Overwrites the contents of the element at `idx` with `a`"]
+    /// Overwrites the contents of the element at `idx` with `a`
     fn set_elt(idx: uint, a: A) {
         self.check_not_borrowed();
         self.data[idx] = a;
     }
 
-    #[doc = "Overwrites the contents of the element at `idx` with `a`,
-    growing the vector if necessary.  New elements will be initialized
-    with `initval`"]
+    /**
+     * Overwrites the contents of the element at `idx` with `a`,
+     * growing the vector if necessary.  New elements will be initialized
+     * with `initval`
+     */
     fn grow_set_elt(idx: uint, initval: A, val: A) {
         do self.swap |v| {
             let mut v <- v;
@@ -269,7 +265,7 @@ impl extensions<A:copy> for dvec<A> {
         }
     }
 
-    #[doc = "Returns the last element, failing if the vector is empty"]
+    /// Returns the last element, failing if the vector is empty
     #[inline(always)]
     fn last() -> A {
         self.check_not_borrowed();
@@ -282,7 +278,7 @@ impl extensions<A:copy> for dvec<A> {
         ret self.data[length - 1u];
     }
 
-    #[doc="Iterates over the elements in reverse order"]
+    /// Iterates over the elements in reverse order
     #[inline(always)]
     fn reach(f: fn(A) -> bool) {
         let length = self.len();
diff --git a/src/libcore/either.rs b/src/libcore/either.rs
index 9dadd848415..d1ea214ef0a 100644
--- a/src/libcore/either.rs
+++ b/src/libcore/either.rs
@@ -1,8 +1,8 @@
-#[doc = "A type that represents one of two alternatives"];
+//! A type that represents one of two alternatives
 
 import result::result;
 
-#[doc = "The either type"]
+/// The either type
 enum either<T, U> {
     left(T),
     right(U)
@@ -10,19 +10,19 @@ enum either<T, U> {
 
 fn either<T, U, V>(f_left: fn(T) -> V,
                    f_right: fn(U) -> V, value: either<T, U>) -> V {
-    #[doc = "
-    Applies a function based on the given either value
-
-    If `value` is left(T) then `f_left` is applied to its contents, if `value`
-    is right(U) then `f_right` is applied to its contents, and the result is
-    returned.
-    "];
+    /*!
+     * Applies a function based on the given either value
+     *
+     * If `value` is left(T) then `f_left` is applied to its contents, if
+     * `value` is right(U) then `f_right` is applied to its contents, and the
+     * result is returned.
+     */
 
     alt value { left(l) { f_left(l) } right(r) { f_right(r) } }
 }
 
 fn lefts<T: copy, U>(eithers: ~[either<T, U>]) -> ~[T] {
-    #[doc = "Extracts from a vector of either all the left values"];
+    //! Extracts from a vector of either all the left values
 
     let mut result: ~[T] = ~[];
     for vec::each(eithers) |elt| {
@@ -32,7 +32,7 @@ fn lefts<T: copy, U>(eithers: ~[either<T, U>]) -> ~[T] {
 }
 
 fn rights<T, U: copy>(eithers: ~[either<T, U>]) -> ~[U] {
-    #[doc = "Extracts from a vector of either all the right values"];
+    //! Extracts from a vector of either all the right values
 
     let mut result: ~[U] = ~[];
     for vec::each(eithers) |elt| {
@@ -43,12 +43,12 @@ fn rights<T, U: copy>(eithers: ~[either<T, U>]) -> ~[U] {
 
 fn partition<T: copy, U: copy>(eithers: ~[either<T, U>])
     -> {lefts: ~[T], rights: ~[U]} {
-    #[doc = "
-    Extracts from a vector of either all the left values and right values
-
-    Returns a structure containing a vector of left values and a vector of
-    right values.
-    "];
+    /*!
+     * Extracts from a vector of either all the left values and right values
+     *
+     * Returns a structure containing a vector of left values and a vector of
+     * right values.
+     */
 
     let mut lefts: ~[T] = ~[];
     let mut rights: ~[U] = ~[];
@@ -62,7 +62,7 @@ fn partition<T: copy, U: copy>(eithers: ~[either<T, U>])
 }
 
 pure fn flip<T: copy, U: copy>(eith: either<T, U>) -> either<U, T> {
-    #[doc = "Flips between left and right of a given either"];
+    //! Flips between left and right of a given either
 
     alt eith {
       right(r) { left(r) }
@@ -72,12 +72,12 @@ pure fn flip<T: copy, U: copy>(eith: either<T, U>) -> either<U, T> {
 
 pure fn to_result<T: copy, U: copy>(
     eith: either<T, U>) -> result<U, T> {
-    #[doc = "
-    Converts either::t to a result::t
-
-    Converts an `either` type to a `result` type, making the \"right\" choice
-    an ok result, and the \"left\" choice a fail
-    "];
+    /*!
+     * Converts either::t to a result::t
+     *
+     * Converts an `either` type to a `result` type, making the "right" choice
+     * an ok result, and the "left" choice a fail
+     */
 
     alt eith {
       right(r) { result::ok(r) }
@@ -86,13 +86,13 @@ pure fn to_result<T: copy, U: copy>(
 }
 
 pure fn is_left<T, U>(eith: either<T, U>) -> bool {
-    #[doc = "Checks whether the given value is a left"];
+    //! Checks whether the given value is a left
 
     alt eith { left(_) { true } _ { false } }
 }
 
 pure fn is_right<T, U>(eith: either<T, U>) -> bool {
-    #[doc = "Checks whether the given value is a right"];
+    //! Checks whether the given value is a right
 
     alt eith { right(_) { true } _ { false } }
 }
diff --git a/src/libcore/f32.rs b/src/libcore/f32.rs
index d84438f4845..c72aa6e3aef 100644
--- a/src/libcore/f32.rs
+++ b/src/libcore/f32.rs
@@ -1,4 +1,4 @@
-#[doc = "Operations and constants for `f32`"];
+//! Operations and constants for `f32`
 
 // PORT
 
@@ -56,49 +56,43 @@ pure fn gt(x: f32, y: f32) -> bool { ret x > y; }
 // FIXME (#1999): replace the predicates below with llvm intrinsics or
 // calls to the libmath macros in the rust runtime for performance.
 
-#[doc = "
-Returns true if `x` is a positive number, including +0.0f320 and +Infinity
-"]
+/// Returns true if `x` is a positive number, including +0.0f320 and +Infinity
 pure fn is_positive(x: f32) -> bool
     { ret x > 0.0f32 || (1.0f32/x) == infinity; }
 
-#[doc = "
-Returns true if `x` is a negative number, including -0.0f320 and -Infinity
-"]
+/// Returns true if `x` is a negative number, including -0.0f320 and -Infinity
 pure fn is_negative(x: f32) -> bool
     { ret x < 0.0f32 || (1.0f32/x) == neg_infinity; }
 
-#[doc = "
-Returns true if `x` is a negative number, including -0.0f320 and -Infinity
-
-This is the same as `f32::is_negative`.
-"]
+/**
+ * Returns true if `x` is a negative number, including -0.0f320 and -Infinity
+ *
+ * This is the same as `f32::is_negative`.
+ */
 pure fn is_nonpositive(x: f32) -> bool {
   ret x < 0.0f32 || (1.0f32/x) == neg_infinity;
 }
 
-#[doc = "
-Returns true if `x` is a positive number, including +0.0f320 and +Infinity
-
-This is the same as `f32::is_positive`.)
-"]
+/**
+ * Returns true if `x` is a positive number, including +0.0f320 and +Infinity
+ *
+ * This is the same as `f32::is_positive`.)
+ */
 pure fn is_nonnegative(x: f32) -> bool {
   ret x > 0.0f32 || (1.0f32/x) == infinity;
 }
 
-#[doc = "
-Returns true if `x` is a zero number (positive or negative zero)
-"]
+/// Returns true if `x` is a zero number (positive or negative zero)
 pure fn is_zero(x: f32) -> bool {
     ret x == 0.0f32 || x == -0.0f32;
 }
 
-#[doc = "Returns true if `x`is an infinite number"]
+/// Returns true if `x`is an infinite number
 pure fn is_infinite(x: f32) -> bool {
     ret x == infinity || x == neg_infinity;
 }
 
-#[doc = "Returns true if `x`is a finite number"]
+/// Returns true if `x`is a finite number
 pure fn is_finite(x: f32) -> bool {
     ret !(is_NaN(x) || is_infinite(x));
 }
@@ -110,43 +104,43 @@ mod consts {
 
     // FIXME (requires Issue #1433 to fix): replace with mathematical
     // constants from cmath.
-    #[doc = "Archimedes' constant"]
+    /// Archimedes' constant
     const pi: f32 = 3.14159265358979323846264338327950288_f32;
 
-    #[doc = "pi/2.0"]
+    /// pi/2.0
     const frac_pi_2: f32 = 1.57079632679489661923132169163975144_f32;
 
-    #[doc = "pi/4.0"]
+    /// pi/4.0
     const frac_pi_4: f32 = 0.785398163397448309615660845819875721_f32;
 
-    #[doc = "1.0/pi"]
+    /// 1.0/pi
     const frac_1_pi: f32 = 0.318309886183790671537767526745028724_f32;
 
-    #[doc = "2.0/pi"]
+    /// 2.0/pi
     const frac_2_pi: f32 = 0.636619772367581343075535053490057448_f32;
 
-    #[doc = "2.0/sqrt(pi)"]
+    /// 2.0/sqrt(pi)
     const frac_2_sqrtpi: f32 = 1.12837916709551257389615890312154517_f32;
 
-    #[doc = "sqrt(2.0)"]
+    /// sqrt(2.0)
     const sqrt2: f32 = 1.41421356237309504880168872420969808_f32;
 
-    #[doc = "1.0/sqrt(2.0)"]
+    /// 1.0/sqrt(2.0)
     const frac_1_sqrt2: f32 = 0.707106781186547524400844362104849039_f32;
 
-    #[doc = "Euler's number"]
+    /// Euler's number
     const e: f32 = 2.71828182845904523536028747135266250_f32;
 
-    #[doc = "log2(e)"]
+    /// log2(e)
     const log2_e: f32 = 1.44269504088896340735992468100189214_f32;
 
-    #[doc = "log10(e)"]
+    /// log10(e)
     const log10_e: f32 = 0.434294481903251827651128918916605082_f32;
 
-    #[doc = "ln(2.0)"]
+    /// ln(2.0)
     const ln_2: f32 = 0.693147180559945309417232121458176568_f32;
 
-    #[doc = "ln(10.0)"]
+    /// ln(10.0)
     const ln_10: f32 = 2.30258509299404568401799145468436421_f32;
 }
 
diff --git a/src/libcore/f64.rs b/src/libcore/f64.rs
index 72f1b6b866a..40488d9f8f4 100644
--- a/src/libcore/f64.rs
+++ b/src/libcore/f64.rs
@@ -1,4 +1,4 @@
-#[doc = "Operations and constants for `f64`"];
+//! Operations and constants for `f64`
 
 // PORT
 
@@ -83,47 +83,43 @@ pure fn sqrt(x: f64) -> f64 {
     cmath::c_double::sqrt(x as libc::c_double) as f64
 }
 
-#[doc = "
-Returns true if `x` is a positive number, including +0.0f640 and +Infinity.
-"]
+/// Returns true if `x` is a positive number, including +0.0f640 and +Infinity
 pure fn is_positive(x: f64) -> bool
     { ret x > 0.0f64 || (1.0f64/x) == infinity; }
 
-#[doc = "
-Returns true if `x` is a negative number, including -0.0f640 and -Infinity
-"]
+/// Returns true if `x` is a negative number, including -0.0f640 and -Infinity
 pure fn is_negative(x: f64) -> bool
     { ret x < 0.0f64 || (1.0f64/x) == neg_infinity; }
 
-#[doc = "
-Returns true if `x` is a negative number, including -0.0f640 and -Infinity
-
-This is the same as `f64::is_negative`.
-"]
+/**
+ * Returns true if `x` is a negative number, including -0.0f640 and -Infinity
+ *
+ * This is the same as `f64::is_negative`.
+ */
 pure fn is_nonpositive(x: f64) -> bool {
   ret x < 0.0f64 || (1.0f64/x) == neg_infinity;
 }
 
-#[doc = "
-Returns true if `x` is a positive number, including +0.0f640 and +Infinity
-
-This is the same as `f64::positive`.
-"]
+/**
+ * Returns true if `x` is a positive number, including +0.0f640 and +Infinity
+ *
+ * This is the same as `f64::positive`.
+ */
 pure fn is_nonnegative(x: f64) -> bool {
   ret x > 0.0f64 || (1.0f64/x) == infinity;
 }
 
-#[doc = "Returns true if `x` is a zero number (positive or negative zero)"]
+/// Returns true if `x` is a zero number (positive or negative zero)
 pure fn is_zero(x: f64) -> bool {
     ret x == 0.0f64 || x == -0.0f64;
 }
 
-#[doc = "Returns true if `x`is an infinite number"]
+/// Returns true if `x`is an infinite number
 pure fn is_infinite(x: f64) -> bool {
     ret x == infinity || x == neg_infinity;
 }
 
-#[doc = "Returns true if `x`is a finite number"]
+/// Returns true if `x`is a finite number
 pure fn is_finite(x: f64) -> bool {
     ret !(is_NaN(x) || is_infinite(x));
 }
@@ -135,43 +131,43 @@ mod consts {
 
     // FIXME (requires Issue #1433 to fix): replace with mathematical
     // constants from cmath.
-    #[doc = "Archimedes' constant"]
+    /// Archimedes' constant
     const pi: f64 = 3.14159265358979323846264338327950288_f64;
 
-    #[doc = "pi/2.0"]
+    /// pi/2.0
     const frac_pi_2: f64 = 1.57079632679489661923132169163975144_f64;
 
-    #[doc = "pi/4.0"]
+    /// pi/4.0
     const frac_pi_4: f64 = 0.785398163397448309615660845819875721_f64;
 
-    #[doc = "1.0/pi"]
+    /// 1.0/pi
     const frac_1_pi: f64 = 0.318309886183790671537767526745028724_f64;
 
-    #[doc = "2.0/pi"]
+    /// 2.0/pi
     const frac_2_pi: f64 = 0.636619772367581343075535053490057448_f64;
 
-    #[doc = "2.0/sqrt(pi)"]
+    /// 2.0/sqrt(pi)
     const frac_2_sqrtpi: f64 = 1.12837916709551257389615890312154517_f64;
 
-    #[doc = "sqrt(2.0)"]
+    /// sqrt(2.0)
     const sqrt2: f64 = 1.41421356237309504880168872420969808_f64;
 
-    #[doc = "1.0/sqrt(2.0)"]
+    /// 1.0/sqrt(2.0)
     const frac_1_sqrt2: f64 = 0.707106781186547524400844362104849039_f64;
 
-    #[doc = "Euler's number"]
+    /// Euler's number
     const e: f64 = 2.71828182845904523536028747135266250_f64;
 
-    #[doc = "log2(e)"]
+    /// log2(e)
     const log2_e: f64 = 1.44269504088896340735992468100189214_f64;
 
-    #[doc = "log10(e)"]
+    /// log10(e)
     const log10_e: f64 = 0.434294481903251827651128918916605082_f64;
 
-    #[doc = "ln(2.0)"]
+    /// ln(2.0)
     const ln_2: f64 = 0.693147180559945309417232121458176568_f64;
 
-    #[doc = "ln(10.0)"]
+    /// ln(10.0)
     const ln_10: f64 = 2.30258509299404568401799145468436421_f64;
 }
 
diff --git a/src/libcore/float.rs b/src/libcore/float.rs
index fcca8e420e4..7d13602ecc0 100644
--- a/src/libcore/float.rs
+++ b/src/libcore/float.rs
@@ -1,4 +1,4 @@
-#[doc = "Operations and constants for `float`"];
+//! Operations and constants for `float`
 
 // Even though this module exports everything defined in it,
 // because it contains re-exports, we also have to explicitly
@@ -49,43 +49,43 @@ mod consts {
 
     // FIXME (requires Issue #1433 to fix): replace with mathematical
     // constants from cmath.
-    #[doc = "Archimedes' constant"]
+    /// Archimedes' constant
     const pi: float = 3.14159265358979323846264338327950288;
 
-    #[doc = "pi/2.0"]
+    /// pi/2.0
     const frac_pi_2: float = 1.57079632679489661923132169163975144;
 
-    #[doc = "pi/4.0"]
+    /// pi/4.0
     const frac_pi_4: float = 0.785398163397448309615660845819875721;
 
-    #[doc = "1.0/pi"]
+    /// 1.0/pi
     const frac_1_pi: float = 0.318309886183790671537767526745028724;
 
-    #[doc = "2.0/pi"]
+    /// 2.0/pi
     const frac_2_pi: float = 0.636619772367581343075535053490057448;
 
-    #[doc = "2.0/sqrt(pi)"]
+    /// 2.0/sqrt(pi)
     const frac_2_sqrtpi: float = 1.12837916709551257389615890312154517;
 
-    #[doc = "sqrt(2.0)"]
+    /// sqrt(2.0)
     const sqrt2: float = 1.41421356237309504880168872420969808;
 
-    #[doc = "1.0/sqrt(2.0)"]
+    /// 1.0/sqrt(2.0)
     const frac_1_sqrt2: float = 0.707106781186547524400844362104849039;
 
-    #[doc = "Euler's number"]
+    /// Euler's number
     const e: float = 2.71828182845904523536028747135266250;
 
-    #[doc = "log2(e)"]
+    /// log2(e)
     const log2_e: float = 1.44269504088896340735992468100189214;
 
-    #[doc = "log10(e)"]
+    /// log10(e)
     const log10_e: float = 0.434294481903251827651128918916605082;
 
-    #[doc = "ln(2.0)"]
+    /// ln(2.0)
     const ln_2: float = 0.693147180559945309417232121458176568;
 
-    #[doc = "ln(10.0)"]
+    /// ln(10.0)
     const ln_10: float = 2.30258509299404568401799145468436421;
 }
 
@@ -93,15 +93,15 @@ mod consts {
  * Section: String Conversions
  */
 
-#[doc = "
-Converts a float to a string
-
-# Arguments
-
-* num - The float value
-* digits - The number of significant digits
-* exact - Whether to enforce the exact number of significant digits
-"]
+/**
+ * Converts a float to a string
+ *
+ * # Arguments
+ *
+ * * num - The float value
+ * * digits - The number of significant digits
+ * * exact - Whether to enforce the exact number of significant digits
+ */
 fn to_str_common(num: float, digits: uint, exact: bool) -> str {
     if is_NaN(num) { ret "NaN"; }
     if num == infinity { ret "inf"; }
@@ -179,15 +179,15 @@ fn to_str_common(num: float, digits: uint, exact: bool) -> str {
     ret acc;
 }
 
-#[doc = "
-Converts a float to a string with exactly the number of
-provided significant digits
-
-# Arguments
-
-* num - The float value
-* digits - The number of significant digits
-"]
+/**
+ * Converts a float to a string with exactly the number of
+ * provided significant digits
+ *
+ * # Arguments
+ *
+ * * num - The float value
+ * * digits - The number of significant digits
+ */
 fn to_str_exact(num: float, digits: uint) -> str {
     to_str_common(num, digits, true)
 }
@@ -199,45 +199,45 @@ fn test_to_str_exact_do_decimal() {
 }
 
 
-#[doc = "
-Converts a float to a string with a maximum number of
-significant digits
-
-# Arguments
-
-* num - The float value
-* digits - The number of significant digits
-"]
+/**
+ * Converts a float to a string with a maximum number of
+ * significant digits
+ *
+ * # Arguments
+ *
+ * * num - The float value
+ * * digits - The number of significant digits
+ */
 fn to_str(num: float, digits: uint) -> str {
     to_str_common(num, digits, false)
 }
 
-#[doc = "
-Convert a string to a float
-
-This function accepts strings such as
-
-* '3.14'
-* '+3.14', equivalent to '3.14'
-* '-3.14'
-* '2.5E10', or equivalently, '2.5e10'
-* '2.5E-10'
-* '', or, equivalently, '.' (understood as 0)
-* '5.'
-* '.5', or, equivalently,  '0.5'
-* 'inf', '-inf', 'NaN'
-
-Leading and trailing whitespace are ignored.
-
-# Arguments
-
-* num - A string
-
-# Return value
-
-`none` if the string did not represent a valid number.  Otherwise, `some(n)`
-where `n` is the floating-point number represented by `[num]/~`.
-"]
+/**
+ * Convert a string to a float
+ *
+ * This function accepts strings such as
+ *
+ * * '3.14'
+ * * '+3.14', equivalent to '3.14'
+ * * '-3.14'
+ * * '2.5E10', or equivalently, '2.5e10'
+ * * '2.5E-10'
+ * * '', or, equivalently, '.' (understood as 0)
+ * * '5.'
+ * * '.5', or, equivalently,  '0.5'
+ * * 'inf', '-inf', 'NaN'
+ *
+ * Leading and trailing whitespace are ignored.
+ *
+ * # Arguments
+ *
+ * * num - A string
+ *
+ * # Return value
+ *
+ * `none` if the string did not represent a valid number.  Otherwise,
+ * `some(n)` where `n` is the floating-point number represented by `[num]/~`.
+ */
 fn from_str(num: str) -> option<float> {
    if num == "inf" {
        ret some(infinity as float);
@@ -371,18 +371,18 @@ fn from_str(num: str) -> option<float> {
  * Section: Arithmetics
  */
 
-#[doc = "
-Compute the exponentiation of an integer by another integer as a float
-
-# Arguments
-
-* x - The base
-* pow - The exponent
-
-# Return value
-
-`NaN` if both `x` and `pow` are `0u`, otherwise `x^pow`
-"]
+/**
+ * Compute the exponentiation of an integer by another integer as a float
+ *
+ * # Arguments
+ *
+ * * x - The base
+ * * pow - The exponent
+ *
+ * # Return value
+ *
+ * `NaN` if both `x` and `pow` are `0u`, otherwise `x^pow`
+ */
 fn pow_with_uint(base: uint, pow: uint) -> float {
     if base == 0u {
         if pow == 0u {
diff --git a/src/libcore/future.rs b/src/libcore/future.rs
index 61ce3b059da..322b75da7da 100644
--- a/src/libcore/future.rs
+++ b/src/libcore/future.rs
@@ -1,15 +1,15 @@
-#[doc = "
-A type representing values that may be computed concurrently and
-operations for working with them.
-
-# Example
-
-~~~
-let delayed_fib = future::spawn {|| fib(5000) };
-make_a_sandwich();
-io::println(#fmt(\"fib(5000) = %?\", delayed_fib.get()))
-~~~
-"];
+/*!
+ * A type representing values that may be computed concurrently and
+ * operations for working with them.
+ *
+ * # Example
+ *
+ * ~~~
+ * let delayed_fib = future::spawn {|| fib(5000) };
+ * make_a_sandwich();
+ * io::println(#fmt("fib(5000) = %?", delayed_fib.get()))
+ * ~~~
+ */
 
 import either::either;
 
@@ -22,34 +22,34 @@ export get;
 export with;
 export spawn;
 
-#[doc = "The future type"]
+/// The future type
 enum future<A> = {
     mut v: either<@A, fn@() -> A>
 };
 
-#[doc = "Methods on the `future` type"]
+/// Methods on the `future` type
 impl extensions<A:copy send> for future<A> {
 
     fn get() -> A {
-        #[doc = "Get the value of the future"];
+        //! Get the value of the future
 
         get(self)
     }
 
     fn with<B>(blk: fn(A) -> B) -> B {
-        #[doc = "Work with the value without copying it"];
+        //! Work with the value without copying it
 
         with(self, blk)
     }
 }
 
 fn from_value<A>(+val: A) -> future<A> {
-    #[doc = "
-    Create a future from a value
-
-    The value is immediately available and calling `get` later will
-    not block.
-    "];
+    /*!
+     * Create a future from a value
+     *
+     * The value is immediately available and calling `get` later will
+     * not block.
+     */
 
     future({
         mut v: either::left(@val)
@@ -57,12 +57,12 @@ fn from_value<A>(+val: A) -> future<A> {
 }
 
 fn from_port<A:send>(-port: comm::port<A>) -> future<A> {
-    #[doc = "
-    Create a future from a port
-
-    The first time that the value is requested the task will block
-    waiting for the result to be received on the port.
-    "];
+    /*!
+     * Create a future from a port
+     *
+     * The first time that the value is requested the task will block
+     * waiting for the result to be received on the port.
+     */
 
     do from_fn {
         comm::recv(port)
@@ -70,13 +70,13 @@ fn from_port<A:send>(-port: comm::port<A>) -> future<A> {
 }
 
 fn from_fn<A>(f: fn@() -> A) -> future<A> {
-    #[doc = "
-    Create a future from a function.
-
-    The first time that the value is requested it will be retreived by
-    calling the function.  Note that this function is a local
-    function. It is not spawned into another task.
-    "];
+    /*!
+     * Create a future from a function.
+     *
+     * The first time that the value is requested it will be retreived by
+     * calling the function.  Note that this function is a local
+     * function. It is not spawned into another task.
+     */
 
     future({
         mut v: either::right(f)
@@ -84,12 +84,12 @@ fn from_fn<A>(f: fn@() -> A) -> future<A> {
 }
 
 fn spawn<A:send>(+blk: fn~() -> A) -> future<A> {
-    #[doc = "
-    Create a future from a unique closure.
-
-    The closure will be run in a new task and its result used as the
-    value of the future.
-    "];
+    /*!
+     * Create a future from a unique closure.
+     *
+     * The closure will be run in a new task and its result used as the
+     * value of the future.
+     */
 
     let mut po = comm::port();
     let ch = comm::chan(po);
@@ -100,13 +100,13 @@ fn spawn<A:send>(+blk: fn~() -> A) -> future<A> {
 }
 
 fn get<A:copy>(future: future<A>) -> A {
-    #[doc = "Get the value of the future"];
+    //! Get the value of the future
 
     do with(future) |v| { v }
 }
 
 fn with<A,B>(future: future<A>, blk: fn(A) -> B) -> B {
-    #[doc = "Work with the value without copying it"];
+    //! Work with the value without copying it
 
     let v = alt copy future.v {
       either::left(v) { v }
diff --git a/src/libcore/int-template.rs b/src/libcore/int-template.rs
index ac11f2f1102..407b810e95d 100644
--- a/src/libcore/int-template.rs
+++ b/src/libcore/int-template.rs
@@ -38,7 +38,7 @@ pure fn is_nonpositive(x: T) -> bool { x <= 0 as T }
 pure fn is_nonnegative(x: T) -> bool { x >= 0 as T }
 
 #[inline(always)]
-#[doc = "Iterate over the range [`lo`..`hi`)"]
+/// Iterate over the range [`lo`..`hi`)
 fn range(lo: T, hi: T, it: fn(T) -> bool) {
     let mut i = lo;
     while i < hi {
@@ -47,25 +47,25 @@ fn range(lo: T, hi: T, it: fn(T) -> bool) {
     }
 }
 
-#[doc = "Computes the bitwise complement"]
+/// Computes the bitwise complement
 pure fn compl(i: T) -> T {
     -1 as T ^ i
 }
 
-#[doc = "Computes the absolute value"]
+/// Computes the absolute value
 // FIXME: abs should return an unsigned int (#2353)
 pure fn abs(i: T) -> T {
     if is_negative(i) { -i } else { i }
 }
 
-#[doc = "
-Parse a buffer of bytes
-
-# Arguments
-
-* buf - A byte buffer
-* radix - The base of the number
-"]
+/**
+ * Parse a buffer of bytes
+ *
+ * # Arguments
+ *
+ * * buf - A byte buffer
+ * * radix - The base of the number
+ */
 fn parse_buf(buf: ~[u8], radix: uint) -> option<T> {
     if vec::len(buf) == 0u { ret none; }
     let mut i = vec::len(buf) - 1u;
@@ -88,10 +88,10 @@ fn parse_buf(buf: ~[u8], radix: uint) -> option<T> {
     };
 }
 
-#[doc = "Parse a string to an int"]
+/// Parse a string to an int
 fn from_str(s: str) -> option<T> { parse_buf(str::bytes(s), 10u) }
 
-#[doc = "Convert to a string in a given base"]
+/// Convert to a string in a given base
 fn to_str(n: T, radix: uint) -> str {
     do to_str_bytes(n, radix) |slice| {
         do vec::unpack_slice(slice) |p, len| {
@@ -108,7 +108,7 @@ fn to_str_bytes<U>(n: T, radix: uint, f: fn(v: &[u8]) -> U) -> U {
     }
 }
 
-#[doc = "Convert to a string"]
+/// Convert to a string
 fn str(i: T) -> str { ret to_str(i, 10u); }
 
 impl ord of ord for T {
diff --git a/src/libcore/int-template/int.rs b/src/libcore/int-template/int.rs
index 51149d7e1fb..07acb4be8ce 100644
--- a/src/libcore/int-template/int.rs
+++ b/src/libcore/int-template/int.rs
@@ -6,10 +6,10 @@ const bits: T = 32 as T;
 #[cfg(target_arch = "x86_64")]
 const bits: T = 64 as T;
 
-#[doc = "Produce a uint suitable for use in a hash table"]
+/// Produce a uint suitable for use in a hash table
 pure fn hash(&&x: int) -> uint { ret x as uint; }
 
-#[doc = "Returns `base` raised to the power of `exponent`"]
+/// Returns `base` raised to the power of `exponent`
 fn pow(base: int, exponent: uint) -> int {
     if exponent == 0u { ret 1; } //Not mathemtically true if ~[base == 0]
     if base     == 0  { ret 0; }
diff --git a/src/libcore/iter-trait/dlist.rs b/src/libcore/iter-trait/dlist.rs
index f97dce5854d..d34ea38034d 100644
--- a/src/libcore/iter-trait/dlist.rs
+++ b/src/libcore/iter-trait/dlist.rs
@@ -1,12 +1,12 @@
 type IMPL_T<A> = dlist::dlist<A>;
 
-#[doc = "
-Iterates through the current contents.
-
-Attempts to access this dlist during iteration are allowed (to allow for e.g.
-breadth-first search with in-place enqueues), but removing the current node
-is forbidden.
-"]
+/**
+ * Iterates through the current contents.
+ *
+ * Attempts to access this dlist during iteration are allowed (to allow for
+ * e.g. breadth-first search with in-place enqueues), but removing the current
+ * node is forbidden.
+ */
 fn EACH<A>(self: IMPL_T<A>, f: fn(A) -> bool) {
     import dlist::extensions;
 
diff --git a/src/libcore/iter-trait/dvec.rs b/src/libcore/iter-trait/dvec.rs
index 3f1f4db6a4d..efab0b70b57 100644
--- a/src/libcore/iter-trait/dvec.rs
+++ b/src/libcore/iter-trait/dvec.rs
@@ -1,10 +1,10 @@
 type IMPL_T<A> = dvec::dvec<A>;
 
-#[doc = "
-Iterates through the current contents.
-
-Attempts to access this dvec during iteration will fail.
-"]
+/**
+ * Iterates through the current contents.
+ *
+ * Attempts to access this dvec during iteration will fail.
+ */
 fn EACH<A>(self: IMPL_T<A>, f: fn(A) -> bool) {
     import dvec::extensions;
     self.swap(|v| { vec::each(v, f); v })
diff --git a/src/libcore/libc.rs b/src/libcore/libc.rs
index 4ccc9f2010d..740a78a6d9c 100644
--- a/src/libcore/libc.rs
+++ b/src/libcore/libc.rs
@@ -1,38 +1,38 @@
-#[doc = "
-Bindings for libc.
-
-We consider the following specs reasonably normative with respect
-to interoperating with the C standard library (libc/msvcrt):
-
-* ISO 9899:1990 ('C95', 'ANSI C', 'Standard C'), NA1, 1995.
-* ISO 9899:1999 ('C99' or 'C9x').
-* ISO 9945:1988 / IEEE 1003.1-1988 ('POSIX.1').
-* ISO 9945:2001 / IEEE 1003.1-2001 ('POSIX:2001', 'SUSv3').
-* ISO 9945:2008 / IEEE 1003.1-2008 ('POSIX:2008', 'SUSv4').
-
-Despite having several names each, these are *reasonably* coherent
-point-in-time, list-of-definition sorts of specs. You can get each under a
-variety of names but will wind up with the same definition in each case.
-
-Our interface to these libraries is complicated by the non-universality of
-conformance to any of them. About the only thing universally supported is
-the first (C95), beyond that definitions quickly become absent on various
-platforms.
-
-We therefore wind up dividing our module-space up (mostly for the sake of
-sanity while editing, filling-in-details and eliminating duplication) into
-definitions common-to-all (held in modules named c95, c99, posix88, posix01
-and posix08) and definitions that appear only on *some* platforms (named
-'extra'). This would be things like significant OSX foundation kit, or
-win32 library kernel32.dll, or various fancy glibc, linux or BSD
-extensions.
-
-In addition to the per-platform 'extra' modules, we define a module of
-'common BSD' libc routines that never quite made it into POSIX but show up
-in multiple derived systems. This is the 4.4BSD r2 / 1995 release, the
-final one from Berkeley after the lawsuits died down and the CSRG
-dissolved.
-"];
+/*!
+ * Bindings for libc.
+ *
+ * We consider the following specs reasonably normative with respect
+ * to interoperating with the C standard library (libc/msvcrt):
+ *
+ * * ISO 9899:1990 ('C95', 'ANSI C', 'Standard C'), NA1, 1995.
+ * * ISO 9899:1999 ('C99' or 'C9x').
+ * * ISO 9945:1988 / IEEE 1003.1-1988 ('POSIX.1').
+ * * ISO 9945:2001 / IEEE 1003.1-2001 ('POSIX:2001', 'SUSv3').
+ * * ISO 9945:2008 / IEEE 1003.1-2008 ('POSIX:2008', 'SUSv4').
+ *
+ * Despite having several names each, these are *reasonably* coherent
+ * point-in-time, list-of-definition sorts of specs. You can get each under a
+ * variety of names but will wind up with the same definition in each case.
+ *
+ * Our interface to these libraries is complicated by the non-universality of
+ * conformance to any of them. About the only thing universally supported is
+ * the first (C95), beyond that definitions quickly become absent on various
+ * platforms.
+ *
+ * We therefore wind up dividing our module-space up (mostly for the sake of
+ * sanity while editing, filling-in-details and eliminating duplication) into
+ * definitions common-to-all (held in modules named c95, c99, posix88, posix01
+ * and posix08) and definitions that appear only on *some* platforms (named
+ * 'extra'). This would be things like significant OSX foundation kit, or
+ * win32 library kernel32.dll, or various fancy glibc, linux or BSD
+ * extensions.
+ *
+ * In addition to the per-platform 'extra' modules, we define a module of
+ * 'common BSD' libc routines that never quite made it into POSIX but show up
+ * in multiple derived systems. This is the 4.4BSD r2 / 1995 release, the
+ * final one from Berkeley after the lawsuits died down and the CSRG
+ * dissolved.
+ */
 
 // Initial glob-exports mean that all the contents of all the modules
 // wind up exported, if you're interested in writing platform-specific code.
diff --git a/src/libcore/logging.rs b/src/libcore/logging.rs
index 261a18f6f7d..1e233dfe8d5 100644
--- a/src/libcore/logging.rs
+++ b/src/libcore/logging.rs
@@ -1,4 +1,4 @@
-#[doc = "Logging"];
+//! Logging
 
 export console_on, console_off;
 
@@ -8,18 +8,18 @@ extern mod rustrt {
     fn rust_log_console_off();
 }
 
-#[doc = "Turns on logging to stdout globally"]
+/// Turns on logging to stdout globally
 fn console_on() {
     rustrt::rust_log_console_on();
 }
 
-#[doc = "
-Turns off logging to stdout globally
-
-Turns off the console unless the user has overridden the
-runtime environment's logging spec, e.g. by setting
-the RUST_LOG environment variable
-"]
+/**
+ * Turns off logging to stdout globally
+ *
+ * Turns off the console unless the user has overridden the
+ * runtime environment's logging spec, e.g. by setting
+ * the RUST_LOG environment variable
+ */
 fn console_off() {
     rustrt::rust_log_console_off();
 }
\ No newline at end of file
diff --git a/src/libcore/newcomm.rs b/src/libcore/newcomm.rs
index 79ace3af1e5..e78b8551c6d 100644
--- a/src/libcore/newcomm.rs
+++ b/src/libcore/newcomm.rs
@@ -1,7 +1,9 @@
-#[doc="A new implementation of communication.
-
-This should be implementing almost entirely in Rust, and hopefully
-avoid needing a single global lock."]
+/**
+ * A new implementation of communication.
+ *
+ * This should be implementing almost entirely in Rust, and hopefully
+ * avoid needing a single global lock.
+ */
 
 import arc::methods;
 import dvec::dvec;
diff --git a/src/libcore/num.rs b/src/libcore/num.rs
index 2d192b4aab1..551b444d89c 100644
--- a/src/libcore/num.rs
+++ b/src/libcore/num.rs
@@ -1,4 +1,4 @@
-#[doc="An interface for numbers."]
+/// An interface for numbers.
 
 iface num {
     // FIXME: Cross-crate overloading doesn't work yet. (#2615)
diff --git a/src/libcore/option.rs b/src/libcore/option.rs
index 6e8e5567756..ac7dd013be9 100644
--- a/src/libcore/option.rs
+++ b/src/libcore/option.rs
@@ -1,26 +1,27 @@
-#[doc = "
-Operations on the ubiquitous `option` type.
-
-Type `option` represents an optional value.
-
-Every `option<T>` value can either be `some(T)` or `none`. Where in other
-languages you might use a nullable type, in Rust you would use an option type.
-"];
-
-#[doc = "The option type"]
+/*!
+ * Operations on the ubiquitous `option` type.
+ *
+ * Type `option` represents an optional value.
+ *
+ * Every `option<T>` value can either be `some(T)` or `none`. Where in other
+ * languages you might use a nullable type, in Rust you would use an option
+ * type.
+ */
+
+/// The option type
 enum option<T> {
     none,
     some(T),
 }
 
 pure fn get<T: copy>(opt: option<T>) -> T {
-    #[doc = "
-    Gets the value out of an option
-
-    # Failure
-
-    Fails if the value equals `none`
-    "];
+    /*!
+     * Gets the value out of an option
+     *
+     * # Failure
+     *
+     * Fails if the value equals `none`
+     */
 
     alt opt { some(x) { ret x; } none { fail "option none"; } }
 }
@@ -37,57 +38,57 @@ pure fn expect<T: copy>(opt: option<T>, reason: str) -> T {
 }
 
 pure fn map<T, U: copy>(opt: option<T>, f: fn(T) -> U) -> option<U> {
-    #[doc = "Maps a `some` value from one type to another"];
+    //! Maps a `some` value from one type to another
 
     alt opt { some(x) { some(f(x)) } none { none } }
 }
 
 pure fn chain<T, U>(opt: option<T>, f: fn(T) -> option<U>) -> option<U> {
-    #[doc = "
-    Update an optional value by optionally running its content through a
-    function that returns an option.
-    "];
+    /*!
+     * Update an optional value by optionally running its content through a
+     * function that returns an option.
+     */
 
     alt opt { some(x) { f(x) } none { none } }
 }
 
 pure fn is_none<T>(opt: option<T>) -> bool {
-    #[doc = "Returns true if the option equals `none`"];
+    //! Returns true if the option equals `none`
 
     alt opt { none { true } some(_) { false } }
 }
 
 pure fn is_some<T>(opt: option<T>) -> bool {
-    #[doc = "Returns true if the option contains some value"];
+    //! Returns true if the option contains some value
 
     !is_none(opt)
 }
 
 pure fn get_default<T: copy>(opt: option<T>, def: T) -> T {
-    #[doc = "Returns the contained value or a default"];
+    //! Returns the contained value or a default
 
     alt opt { some(x) { x } none { def } }
 }
 
 pure fn map_default<T, U: copy>(opt: option<T>, def: U, f: fn(T) -> U) -> U {
-    #[doc = "Applies a function to the contained value or returns a default"];
+    //! Applies a function to the contained value or returns a default
 
     alt opt { none { def } some(t) { f(t) } }
 }
 
 pure fn iter<T>(opt: option<T>, f: fn(T)) {
-    #[doc = "Performs an operation on the contained value or does nothing"];
+    //! Performs an operation on the contained value or does nothing
 
     alt opt { none { } some(t) { f(t); } }
 }
 
 pure fn unwrap<T>(-opt: option<T>) -> T {
-    #[doc = "
-    Moves a value out of an option type and returns it.
-
-    Useful primarily for getting strings, vectors and unique pointers out of
-    option types without copying them.
-    "];
+    /*!
+     * Moves a value out of an option type and returns it.
+     *
+     * Useful primarily for getting strings, vectors and unique pointers out
+     * of option types without copying them.
+     */
 
     unsafe {
         let addr = alt opt {
@@ -101,41 +102,42 @@ pure fn unwrap<T>(-opt: option<T>) -> T {
 }
 
 impl extensions<T> for option<T> {
-    #[doc = "
-    Update an optional value by optionally running its content through a
-    function that returns an option.
-    "]
-    pure fn chain<U>(f: fn(T) -> option<U>) -> option<U> { chain(self, f) }
-    #[doc = "Applies a function to the contained value or returns a default"]
-    pure fn map_default<U: copy>(def: U, f: fn(T) -> U) -> U
+    /**
+     * Update an optional value by optionally running its content through a
+     * function that returns an option.
+     */
+    fn chain<U>(f: fn(T) -> option<U>) -> option<U> { chain(self, f) }
+    /// Applies a function to the contained value or returns a default
+    fn map_default<U: copy>(def: U, f: fn(T) -> U) -> U
         { map_default(self, def, f) }
-    #[doc = "Performs an operation on the contained value or does nothing"]
-    pure fn iter(f: fn(T)) { iter(self, f) }
-    #[doc = "Returns true if the option equals `none`"]
-    pure fn is_none() -> bool { is_none(self) }
-    #[doc = "Returns true if the option contains some value"]
-    pure fn is_some() -> bool { is_some(self) }
-    #[doc = "Maps a `some` value from one type to another"]
-    pure fn map<U:copy>(f: fn(T) -> U) -> option<U> { map(self, f) }
+    /// Performs an operation on the contained value or does nothing
+    fn iter(f: fn(T)) { iter(self, f) }
+    /// Returns true if the option equals `none`
+    fn is_none() -> bool { is_none(self) }
+    /// Returns true if the option contains some value
+    fn is_some() -> bool { is_some(self) }
+    /// Maps a `some` value from one type to another
+    fn map<U:copy>(f: fn(T) -> U) -> option<U> { map(self, f) }
 }
 
 impl extensions<T: copy> for option<T> {
-    #[doc = "
-    Gets the value out of an option
-
-    # Failure
-
-    Fails if the value equals `none`
-    "]
-    pure fn get() -> T { get(self) }
-    pure fn get_default(def: T) -> T { get_default(self, def) }
-    #[doc = "
-    Gets the value out of an option, printing a specified message on failure
-
-    # Failure
-
-    Fails if the value equals `none`
-    "]
+    /**
+     * Gets the value out of an option
+     *
+     * # Failure
+     *
+     * Fails if the value equals `none`
+     */
+    fn get() -> T { get(self) }
+    fn get_default(def: T) -> T { get_default(self, def) }
+    /**
+     * Gets the value out of an option, printing a specified message on
+     * failure
+     *
+     * # Failure
+     *
+     * Fails if the value equals `none`
+     */
     pure fn expect(reason: str) -> T { expect(self, reason) }
 }
 
diff --git a/src/libcore/os.rs b/src/libcore/os.rs
index ec553ad5e2f..808552fca6c 100644
--- a/src/libcore/os.rs
+++ b/src/libcore/os.rs
@@ -1,20 +1,20 @@
-#[doc = "
-Higher-level interfaces to libc::* functions and operating system services.
-
-In general these take and return rust types, use rust idioms (enums,
-closures, vectors) rather than C idioms, and do more extensive safety
-checks.
-
-This module is not meant to only contain 1:1 mappings to libc entries; any
-os-interface code that is reasonably useful and broadly applicable can go
-here. Including utility routines that merely build on other os code.
-
-We assume the general case is that users do not care, and do not want to
-be made to care, which operating system they are on. While they may want
-to special case various special cases -- and so we will not _hide_ the
-facts of which OS the user is on -- they should be given the opportunity
-to write OS-ignorant code by default.
-"];
+/*!
+ * Higher-level interfaces to libc::* functions and operating system services.
+ *
+ * In general these take and return rust types, use rust idioms (enums,
+ * closures, vectors) rather than C idioms, and do more extensive safety
+ * checks.
+ *
+ * This module is not meant to only contain 1:1 mappings to libc entries; any
+ * os-interface code that is reasonably useful and broadly applicable can go
+ * here. Including utility routines that merely build on other os code.
+ *
+ * We assume the general case is that users do not care, and do not want to
+ * be made to care, which operating system they are on. While they may want
+ * to special case various special cases -- and so we will not _hide_ the
+ * facts of which OS the user is on -- they should be given the opportunity
+ * to write OS-ignorant code by default.
+ */
 
 import libc::{c_char, c_void, c_int, c_uint, size_t, ssize_t,
               mode_t, pid_t, FILE};
@@ -130,7 +130,7 @@ fn setenv(n: str, v: str) {
 }
 
 mod global_env {
-    #[doc = "Internal module for serializing access to getenv/setenv"];
+    //! Internal module for serializing access to getenv/setenv
 
     export getenv;
     export setenv;
@@ -418,19 +418,19 @@ fn self_exe_path() -> option<path> {
 }
 
 
-#[doc = "
-Returns the path to the user's home directory, if known.
-
-On Unix, returns the value of the 'HOME' environment variable if it is set and
-not equal to the empty string.
-
-On Windows, returns the value of the 'HOME' environment variable if it is set
-and not equal to the empty string. Otherwise, returns the value of the
-'USERPROFILE' environment variable if it is set and not equal to the empty
-string.
-
-Otherwise, homedir returns option::none.
-"]
+/**
+ * Returns the path to the user's home directory, if known.
+ *
+ * On Unix, returns the value of the 'HOME' environment variable if it is set
+ * and not equal to the empty string.
+ *
+ * On Windows, returns the value of the 'HOME' environment variable if it is
+ * set and not equal to the empty string. Otherwise, returns the value of the
+ * 'USERPROFILE' environment variable if it is set and not equal to the empty
+ * string.
+ *
+ * Otherwise, homedir returns option::none.
+ */
 fn homedir() -> option<path> {
     ret alt getenv("HOME") {
         some(p) {
@@ -462,7 +462,7 @@ fn homedir() -> option<path> {
     }
 }
 
-#[doc = "Recursively walk a directory structure"]
+/// Recursively walk a directory structure
 fn walk_dir(p: path, f: fn(path) -> bool) {
 
     walk_dir_(p, f);
@@ -491,14 +491,14 @@ fn walk_dir(p: path, f: fn(path) -> bool) {
     }
 }
 
-#[doc = "Indicates whether a path represents a directory"]
+/// Indicates whether a path represents a directory
 fn path_is_dir(p: path) -> bool {
     do str::as_c_str(p) |buf| {
         rustrt::rust_path_is_dir(buf) != 0 as c_int
     }
 }
 
-#[doc = "Indicates whether a path exists"]
+/// Indicates whether a path exists
 fn path_exists(p: path) -> bool {
     do str::as_c_str(p) |buf| {
         rustrt::rust_path_exists(buf) != 0 as c_int
@@ -507,13 +507,13 @@ fn path_exists(p: path) -> bool {
 
 // FIXME (#2622): under Windows, we should prepend the current drive letter
 // to paths that start with a slash.
-#[doc = "
-Convert a relative path to an absolute path
-
-If the given path is relative, return it prepended with the current working
-directory. If the given path is already an absolute path, return it
-as is.
-"]
+/**
+ * Convert a relative path to an absolute path
+ *
+ * If the given path is relative, return it prepended with the current working
+ * directory. If the given path is already an absolute path, return it
+ * as is.
+ */
 // NB: this is here rather than in path because it is a form of environment
 // querying; what it does depends on the process working directory, not just
 // the input paths.
@@ -526,7 +526,7 @@ fn make_absolute(p: path) -> path {
 }
 
 
-#[doc = "Creates a directory at the specified path"]
+/// Creates a directory at the specified path
 fn make_dir(p: path, mode: c_int) -> bool {
     ret mkdir(p, mode);
 
@@ -551,7 +551,7 @@ fn make_dir(p: path, mode: c_int) -> bool {
     }
 }
 
-#[doc = "Lists the contents of a directory"]
+/// Lists the contents of a directory
 fn list_dir(p: path) -> ~[str] {
 
     #[cfg(unix)]
@@ -573,11 +573,11 @@ fn list_dir(p: path) -> ~[str] {
     }
 }
 
-#[doc = "
-Lists the contents of a directory
-
-This version prepends each entry with the directory.
-"]
+/**
+ * Lists the contents of a directory
+ *
+ * This version prepends each entry with the directory.
+ */
 fn list_dir_path(p: path) -> ~[str] {
     let mut p = p;
     let pl = str::len(p);
@@ -588,7 +588,7 @@ fn list_dir_path(p: path) -> ~[str] {
     os::list_dir(p).map(|f| p + f)
 }
 
-#[doc = "Removes a directory at the specified path"]
+/// Removes a directory at the specified path
 fn remove_dir(p: path) -> bool {
    ret rmdir(p);
 
@@ -633,7 +633,7 @@ fn change_dir(p: path) -> bool {
     }
 }
 
-#[doc = "Copies a file from one location to another"]
+/// Copies a file from one location to another
 fn copy_file(from: path, to: path) -> bool {
     ret do_copy_file(from, to);
 
@@ -696,7 +696,7 @@ fn copy_file(from: path, to: path) -> bool {
     }
 }
 
-#[doc = "Deletes an existing file"]
+/// Deletes an existing file
 fn remove_file(p: path) -> bool {
     ret unlink(p);
 
@@ -720,19 +720,19 @@ fn remove_file(p: path) -> bool {
     }
 }
 
-#[doc = "Get a string representing the platform-dependent last error"]
+/// Get a string representing the platform-dependent last error
 fn last_os_error() -> str {
     rustrt::last_os_error()
 }
 
-#[doc = "
-Sets the process exit code
-
-Sets the exit code returned by the process if all supervised tasks terminate
-successfully (without failing). If the current root task fails and is
-supervised by the scheduler then any user-specified exit status is ignored and
-the process exits with the default failure status
-"]
+/**
+ * Sets the process exit code
+ *
+ * Sets the exit code returned by the process if all supervised tasks
+ * terminate successfully (without failing). If the current root task fails
+ * and is supervised by the scheduler then any user-specified exit status is
+ * ignored and the process exits with the default failure status
+ */
 fn set_exit_status(code: int) {
     rustrt::rust_set_exit_status(code as libc::intptr_t);
 }
diff --git a/src/libcore/path.rs b/src/libcore/path.rs
index 1b514b00759..67f42002557 100644
--- a/src/libcore/path.rs
+++ b/src/libcore/path.rs
@@ -1,4 +1,4 @@
-#[doc = "Path data type and helper functions"];
+//! Path data type and helper functions
 
 export path;
 export consts;
@@ -13,22 +13,22 @@ export splitext;
 export normalize;
 
 // FIXME: This type should probably be constrained (#2624)
-#[doc = "A path or fragment of a filesystem path"]
+/// A path or fragment of a filesystem path
 type path = str;
 
 #[cfg(unix)]
 mod consts {
-    #[doc = "
-    The primary path separator character for the platform
-
-    On all platforms it is '/'
-    "]
+    /**
+     * The primary path separator character for the platform
+     *
+     * On all platforms it is '/'
+     */
     const path_sep: char = '/';
-    #[doc = "
-    The secondary path separator character for the platform
-
-    On Unixes it is '/'. On Windows it is '\\'.
-    "]
+    /**
+     * The secondary path separator character for the platform
+     *
+     * On Unixes it is '/'. On Windows it is '\'.
+     */
     const alt_path_sep: char = '/';
 }
 
@@ -38,12 +38,12 @@ mod consts {
     const alt_path_sep: char = '\\';
 }
 
-#[doc = "
-Indicates whether a path is absolute.
-
-A path is considered absolute if it begins at the filesystem root (\"/\") or,
-on Windows, begins with a drive letter.
-"]
+/**
+ * Indicates whether a path is absolute.
+ *
+ * A path is considered absolute if it begins at the filesystem root ("/") or,
+ * on Windows, begins with a drive letter.
+ */
 #[cfg(unix)]
 fn path_is_absolute(p: path) -> bool {
     str::char_at(p, 0u) == '/'
@@ -57,7 +57,7 @@ fn path_is_absolute(p: str) -> bool {
             || str::char_at(p, 2u) == consts::alt_path_sep);
 }
 
-#[doc = "Get the default path separator for the host platform"]
+/// Get the default path separator for the host platform
 fn path_sep() -> str { ret str::from_char(consts::path_sep); }
 
 fn split_dirname_basename (pp: path) -> {dirname: str, basename: str} {
@@ -72,39 +72,39 @@ fn split_dirname_basename (pp: path) -> {dirname: str, basename: str} {
     }
 }
 
-#[doc = "
-Get the directory portion of a path
-
-Returns all of the path up to, but excluding, the final path separator.
-The dirname of \"/usr/share\" will be \"/usr\", but the dirname of
-\"/usr/share/\" is \"/usr/share\".
-
-If the path is not prefixed with a directory, then \".\" is returned.
-"]
+/**
+ * Get the directory portion of a path
+ *
+ * Returns all of the path up to, but excluding, the final path separator.
+ * The dirname of "/usr/share" will be "/usr", but the dirname of
+ * "/usr/share/" is "/usr/share".
+ *
+ * If the path is not prefixed with a directory, then "." is returned.
+ */
 fn dirname(pp: path) -> path {
     ret split_dirname_basename(pp).dirname;
 }
 
-#[doc = "
-Get the file name portion of a path
-
-Returns the portion of the path after the final path separator.
-The basename of \"/usr/share\" will be \"share\". If there are no
-path separators in the path then the returned path is identical to
-the provided path. If an empty path is provided or the path ends
-with a path separator then an empty path is returned.
-"]
+/**
+ * Get the file name portion of a path
+ *
+ * Returns the portion of the path after the final path separator.
+ * The basename of "/usr/share" will be "share". If there are no
+ * path separators in the path then the returned path is identical to
+ * the provided path. If an empty path is provided or the path ends
+ * with a path separator then an empty path is returned.
+ */
 fn basename(pp: path) -> path {
     ret split_dirname_basename(pp).basename;
 }
 
-#[doc = "
-Connects to path segments
-
-Given paths `pre` and `post, removes any trailing path separator on `pre` and
-any leading path separator on `post`, and returns the concatenation of the two
-with a single path separator between them.
-"]
+/**
+ * Connects to path segments
+ *
+ * Given paths `pre` and `post, removes any trailing path separator on `pre`
+ * and any leading path separator on `post`, and returns the concatenation of
+ * the two with a single path separator between them.
+ */
 fn connect(pre: path, post: path) -> path {
     let mut pre_ = pre;
     let mut post_ = post;
@@ -122,11 +122,11 @@ fn connect(pre: path, post: path) -> path {
     ret pre_ + path_sep() + post_;
 }
 
-#[doc = "
-Connects a vector of path segments into a single path.
-
-Inserts path separators as needed.
-"]
+/**
+ * Connects a vector of path segments into a single path.
+ *
+ * Inserts path separators as needed.
+ */
 fn connect_many(paths: ~[path]) -> path {
     ret if vec::len(paths) == 1u {
         paths[0]
@@ -136,29 +136,29 @@ fn connect_many(paths: ~[path]) -> path {
     }
 }
 
-#[doc = "
-Split a path into its individual components
-
-Splits a given path by path separators and returns a vector containing
-each piece of the path. On Windows, if the path is absolute then
-the first element of the returned vector will be the drive letter
-followed by a colon.
-"]
+/**
+ * Split a path into its individual components
+ *
+ * Splits a given path by path separators and returns a vector containing
+ * each piece of the path. On Windows, if the path is absolute then
+ * the first element of the returned vector will be the drive letter
+ * followed by a colon.
+ */
 fn split(p: path) -> ~[path] {
     str::split_nonempty(p, |c| {
         c == consts::path_sep || c == consts::alt_path_sep
     })
 }
 
-#[doc = "
-Split a path into the part before the extension and the extension
-
-Split a path into a pair of strings with the first element being the filename
-without the extension and the second being either empty or the file extension
-including the period. Leading periods in the basename are ignored.  If the
-path includes directory components then they are included in the filename part
-of the result pair.
-"]
+/**
+ * Split a path into the part before the extension and the extension
+ *
+ * Split a path into a pair of strings with the first element being the
+ * filename without the extension and the second being either empty or the
+ * file extension including the period. Leading periods in the basename are
+ * ignored.  If the path includes directory components then they are included
+ * in the filename part of the result pair.
+ */
 fn splitext(p: path) -> (str, str) {
     if str::is_empty(p) { ("", "") }
     else {
@@ -200,19 +200,18 @@ fn splitext(p: path) -> (str, str) {
     }
 }
 
-#[doc = "
-Collapses redundant path separators.
-
-Does not follow symbolic links.
-
-# Examples
-
-* '/a/../b' becomes '/b'
-* 'a/./b/' becomes 'a/b/'
-* 'a/b/../../../' becomes '..'
-* '/a/b/c/../d/./../../e/' becomes '/a/e/'
-
-"]
+/**
+ * Collapses redundant path separators.
+ *
+ * Does not follow symbolic links.
+ *
+ * # Examples
+ *
+ * * '/a/../b' becomes '/b'
+ * * 'a/./b/' becomes 'a/b/'
+ * * 'a/b/../../../' becomes '..'
+ * * '/a/b/c/../d/./../../e/' becomes '/a/e/'
+ */
 fn normalize(p: path) -> path {
     let s = split(p);
     let s = strip_dots(s);
diff --git a/src/libcore/priv.rs b/src/libcore/priv.rs
index 922911db932..adda674de32 100644
--- a/src/libcore/priv.rs
+++ b/src/libcore/priv.rs
@@ -16,11 +16,11 @@ extern mod rustrt {
 
 type global_ptr = *libc::uintptr_t;
 
-#[doc = "
-Atomically gets a channel from a pointer to a pointer-sized memory location
-or, if no channel exists creates and installs a new channel and sets up a new
-task to receive from it.
-"]
+/**
+ * Atomically gets a channel from a pointer to a pointer-sized memory location
+ * or, if no channel exists creates and installs a new channel and sets up a
+ * new task to receive from it.
+ */
 unsafe fn chan_from_global_ptr<T: send>(
     global: global_ptr,
     builder: fn() -> task::builder,
@@ -161,25 +161,25 @@ fn test_from_global_chan2() {
     }
 }
 
-#[doc = "
-Convert the current task to a 'weak' task temporarily
-
-As a weak task it will not be counted towards the runtime's set
-of live tasks. When there are no more outstanding live (non-weak) tasks
-the runtime will send an exit message on the provided channel.
-
-This function is super-unsafe. Do not use.
-
-# Safety notes
-
-* Weak tasks must either die on their own or exit upon receipt of
-  the exit message. Failure to do so will cause the runtime to never
-  exit
-* Tasks must not call `weaken_task` multiple times. This will
-  break the kernel's accounting of live tasks.
-* Weak tasks must not be supervised. A supervised task keeps
-  a reference to its parent, so the parent will not die.
-"]
+/**
+ * Convert the current task to a 'weak' task temporarily
+ *
+ * As a weak task it will not be counted towards the runtime's set
+ * of live tasks. When there are no more outstanding live (non-weak) tasks
+ * the runtime will send an exit message on the provided channel.
+ *
+ * This function is super-unsafe. Do not use.
+ *
+ * # Safety notes
+ *
+ * * Weak tasks must either die on their own or exit upon receipt of
+ *   the exit message. Failure to do so will cause the runtime to never
+ *   exit
+ * * Tasks must not call `weaken_task` multiple times. This will
+ *   break the kernel's accounting of live tasks.
+ * * Weak tasks must not be supervised. A supervised task keeps
+ *   a reference to its parent, so the parent will not die.
+ */
 unsafe fn weaken_task(f: fn(comm::port<()>)) {
     let po = comm::port();
     let ch = comm::chan(po);
diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index b6913f9479e..704c0fcaf4b 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -1,4 +1,4 @@
-#[doc = "Unsafe pointer utility functions"];
+//! Unsafe pointer utility functions
 
 export addr_of;
 export mut_addr_of;
@@ -33,11 +33,11 @@ extern mod rusti {
     fn addr_of<T>(val: T) -> *T;
 }
 
-#[doc = "Get an unsafe pointer to a value"]
+/// Get an unsafe pointer to a value
 #[inline(always)]
 pure fn addr_of<T>(val: T) -> *T { unchecked { rusti::addr_of(val) } }
 
-#[doc = "Get an unsafe mut pointer to a value"]
+/// Get an unsafe mut pointer to a value
 #[inline(always)]
 pure fn mut_addr_of<T>(val: T) -> *mut T {
     unsafe {
@@ -45,7 +45,7 @@ pure fn mut_addr_of<T>(val: T) -> *mut T {
     }
 }
 
-#[doc = "Calculate the offset from a pointer"]
+/// Calculate the offset from a pointer
 #[inline(always)]
 fn offset<T>(ptr: *T, count: uint) -> *T {
     unsafe {
@@ -53,7 +53,7 @@ fn offset<T>(ptr: *T, count: uint) -> *T {
     }
 }
 
-#[doc = "Calculate the offset from a const pointer"]
+/// Calculate the offset from a const pointer
 #[inline(always)]
 fn const_offset<T>(ptr: *const T, count: uint) -> *const T {
     unsafe {
@@ -61,19 +61,19 @@ fn const_offset<T>(ptr: *const T, count: uint) -> *const T {
     }
 }
 
-#[doc = "Calculate the offset from a mut pointer"]
+/// Calculate the offset from a mut pointer
 #[inline(always)]
 fn mut_offset<T>(ptr: *mut T, count: uint) -> *mut T {
     (ptr as uint + count * sys::size_of::<T>()) as *mut T
 }
 
-#[doc = "Return the offset of the first null pointer in `buf`."]
+/// Return the offset of the first null pointer in `buf`.
 #[inline(always)]
 unsafe fn buf_len<T>(buf: **T) -> uint {
     position(buf, |i| i == null())
 }
 
-#[doc = "Return the first offset `i` such that `f(buf[i]) == true`."]
+/// Return the first offset `i` such that `f(buf[i]) == true`.
 #[inline(always)]
 unsafe fn position<T>(buf: *T, f: fn(T) -> bool) -> uint {
     let mut i = 0u;
@@ -83,34 +83,34 @@ unsafe fn position<T>(buf: *T, f: fn(T) -> bool) -> uint {
     }
 }
 
-#[doc = "Create an unsafe null pointer"]
+/// Create an unsafe null pointer
 #[inline(always)]
 pure fn null<T>() -> *T { unsafe { unsafe::reinterpret_cast(0u) } }
 
-#[doc = "Returns true if the pointer is equal to the null pointer."]
+/// Returns true if the pointer is equal to the null pointer.
 pure fn is_null<T>(ptr: *const T) -> bool { ptr == null() }
 
-#[doc = "Returns true if the pointer is not equal to the null pointer."]
+/// Returns true if the pointer is not equal to the null pointer.
 pure fn is_not_null<T>(ptr: *const T) -> bool { !is_null(ptr) }
 
-#[doc = "
-Copies data from one location to another
-
-Copies `count` elements (not bytes) from `src` to `dst`. The source
-and destination may not overlap.
-"]
+/**
+ * Copies data from one location to another
+ *
+ * Copies `count` elements (not bytes) from `src` to `dst`. The source
+ * and destination may not overlap.
+ */
 #[inline(always)]
 unsafe fn memcpy<T>(dst: *T, src: *T, count: uint) {
     let n = count * sys::size_of::<T>();
     libc_::memcpy(dst as *c_void, src as *c_void, n as size_t);
 }
 
-#[doc = "
-Copies data from one location to another
-
-Copies `count` elements (not bytes) from `src` to `dst`. The source
-and destination may overlap.
-"]
+/**
+ * Copies data from one location to another
+ *
+ * Copies `count` elements (not bytes) from `src` to `dst`. The source
+ * and destination may overlap.
+ */
 #[inline(always)]
 unsafe fn memmove<T>(dst: *T, src: *T, count: uint)  {
     let n = count * sys::size_of::<T>();
@@ -123,12 +123,12 @@ unsafe fn memset<T>(dst: *mut T, c: int, count: uint)  {
     libc_::memset(dst as *c_void, c as libc::c_int, n as size_t);
 }
 
-#[doc = "Extension methods for pointers"]
+/// Extension methods for pointers
 impl extensions<T> for *T {
-    #[doc = "Returns true if the pointer is equal to the null pointer."]
+    /// Returns true if the pointer is equal to the null pointer.
     pure fn is_null() -> bool { is_null(self) }
 
-    #[doc = "Returns true if the pointer is not equal to the null pointer."]
+    /// Returns true if the pointer is not equal to the null pointer.
     pure fn is_not_null() -> bool { is_not_null(self) }
 }
 
diff --git a/src/libcore/rand.rs b/src/libcore/rand.rs
index e004aa32dc7..4db2cdb086d 100644
--- a/src/libcore/rand.rs
+++ b/src/libcore/rand.rs
@@ -1,4 +1,4 @@
-#[doc = "Random number generation"];
+//! Random number generation
 
 export rng, seed, seeded_rng, weighted, extensions;
 export xorshift, seeded_xorshift;
@@ -14,93 +14,97 @@ extern mod rustrt {
     fn rand_free(c: *rctx);
 }
 
-#[doc = "A random number generator"]
+/// A random number generator
 iface rng {
-    #[doc = "Return the next random integer"]
+    /// Return the next random integer
     fn next() -> u32;
 }
 
-#[doc = "A value with a particular weight compared to other values"]
+/// A value with a particular weight compared to other values
 type weighted<T> = { weight: uint, item: T };
 
-#[doc = "Extension methods for random number generators"]
+/// Extension methods for random number generators
 impl extensions for rng {
 
-    #[doc = "Return a random int"]
+    /// Return a random int
     fn gen_int() -> int {
         self.gen_i64() as int
     }
 
-    #[doc = "Return an int randomly chosen from the range [start, end), \
-             failing if start >= end"]
+    /**
+     * Return an int randomly chosen from the range [start, end),
+     * failing if start >= end
+     */
     fn gen_int_range(start: int, end: int) -> int {
         assert start < end;
         start + int::abs(self.gen_int() % (end - start))
     }
 
-    #[doc = "Return a random i8"]
+    /// Return a random i8
     fn gen_i8() -> i8 {
         self.next() as i8
     }
 
-    #[doc = "Return a random i16"]
+    /// Return a random i16
     fn gen_i16() -> i16 {
         self.next() as i16
     }
 
-    #[doc = "Return a random i32"]
+    /// Return a random i32
     fn gen_i32() -> i32 {
         self.next() as i32
     }
 
-    #[doc = "Return a random i64"]
+    /// Return a random i64
     fn gen_i64() -> i64 {
         (self.next() as i64 << 32) | self.next() as i64
     }
 
-    #[doc = "Return a random uint"]
+    /// Return a random uint
     fn gen_uint() -> uint {
         self.gen_u64() as uint
     }
 
-    #[doc = "Return a uint randomly chosen from the range [start, end), \
-             failing if start >= end"]
+    /**
+     * Return a uint randomly chosen from the range [start, end),
+     * failing if start >= end
+     */
     fn gen_uint_range(start: uint, end: uint) -> uint {
         assert start < end;
         start + (self.gen_uint() % (end - start))
     }
 
-    #[doc = "Return a random u8"]
+    /// Return a random u8
     fn gen_u8() -> u8 {
         self.next() as u8
     }
 
-    #[doc = "Return a random u16"]
+    /// Return a random u16
     fn gen_u16() -> u16 {
         self.next() as u16
     }
 
-    #[doc = "Return a random u32"]
+    /// Return a random u32
     fn gen_u32() -> u32 {
         self.next()
     }
 
-    #[doc = "Return a random u64"]
+    /// Return a random u64
     fn gen_u64() -> u64 {
         (self.next() as u64 << 32) | self.next() as u64
     }
 
-    #[doc = "Return a random float"]
+    /// Return a random float
     fn gen_float() -> float {
         self.gen_f64() as float
     }
 
-    #[doc = "Return a random f32"]
+    /// Return a random f32
     fn gen_f32() -> f32 {
         self.gen_f64() as f32
     }
 
-    #[doc = "Return a random f64"]
+    /// Return a random f64
     fn gen_f64() -> f64 {
         let u1 = self.next() as f64;
         let u2 = self.next() as f64;
@@ -109,24 +113,25 @@ impl extensions for rng {
         ret ((u1 / scale + u2) / scale + u3) / scale;
     }
 
-    #[doc = "Return a random char"]
+    /// Return a random char
     fn gen_char() -> char {
         self.next() as char
     }
 
-    #[doc = "Return a char randomly chosen from chars, failing if chars is \
-             empty"]
+    /**
+     * Return a char randomly chosen from chars, failing if chars is empty
+     */
     fn gen_char_from(chars: str) -> char {
         assert !chars.is_empty();
         self.choose(str::chars(chars))
     }
 
-    #[doc = "Return a random bool"]
+    /// Return a random bool
     fn gen_bool() -> bool {
         self.next() & 1u32 == 1u32
     }
 
-    #[doc = "Return a bool with a 1 in n chance of true"]
+    /// Return a bool with a 1 in n chance of true
     fn gen_weighted_bool(n: uint) -> bool {
         if n == 0u {
             true
@@ -135,8 +140,9 @@ impl extensions for rng {
         }
     }
 
-    #[doc = "Return a random string of the specified length composed of A-Z, \
-             a-z, 0-9"]
+    /**
+     * Return a random string of the specified length composed of A-Z,a-z,0-9
+     */
     fn gen_str(len: uint) -> str {
         let charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZ" +
                       "abcdefghijklmnopqrstuvwxyz" +
@@ -150,19 +156,19 @@ impl extensions for rng {
         s
     }
 
-    #[doc = "Return a random byte string of the specified length"]
+    /// Return a random byte string of the specified length
     fn gen_bytes(len: uint) -> ~[u8] {
         do vec::from_fn(len) |_i| {
             self.gen_u8()
         }
     }
 
-    #[doc = "Choose an item randomly, failing if values is empty"]
+    /// Choose an item randomly, failing if values is empty
     fn choose<T:copy>(values: ~[T]) -> T {
         self.choose_option(values).get()
     }
 
-    #[doc = "Choose some(item) randomly, returning none if values is empty"]
+    /// Choose some(item) randomly, returning none if values is empty
     fn choose_option<T:copy>(values: ~[T]) -> option<T> {
         if values.is_empty() {
             none
@@ -171,14 +177,18 @@ impl extensions for rng {
         }
     }
 
-    #[doc = "Choose an item respecting the relative weights, failing if \
-             the sum of the weights is 0"]
+    /**
+     * Choose an item respecting the relative weights, failing if the sum of
+     * the weights is 0
+     */
     fn choose_weighted<T: copy>(v : ~[weighted<T>]) -> T {
         self.choose_weighted_option(v).get()
     }
 
-    #[doc = "Choose some(item) respecting the relative weights, returning \
-             none if the sum of the weights is 0"]
+    /**
+     * Choose some(item) respecting the relative weights, returning none if
+     * the sum of the weights is 0
+     */
     fn choose_weighted_option<T:copy>(v: ~[weighted<T>]) -> option<T> {
         let mut total = 0u;
         for v.each |item| {
@@ -198,8 +208,10 @@ impl extensions for rng {
         unreachable();
     }
 
-    #[doc = "Return a vec containing copies of the items, in order, where \
-             the weight of the item determines how many copies there are"]
+    /**
+     * Return a vec containing copies of the items, in order, where
+     * the weight of the item determines how many copies there are
+     */
     fn weighted_vec<T:copy>(v: ~[weighted<T>]) -> ~[T] {
         let mut r = ~[];
         for v.each |item| {
@@ -210,14 +222,14 @@ impl extensions for rng {
         r
     }
 
-    #[doc = "Shuffle a vec"]
+    /// Shuffle a vec
     fn shuffle<T:copy>(values: ~[T]) -> ~[T] {
         let mut m = vec::to_mut(values);
         self.shuffle_mut(m);
         ret vec::from_mut(m);
     }
 
-    #[doc = "Shuffle a mutable vec in place"]
+    /// Shuffle a mutable vec in place
     fn shuffle_mut<T>(&&values: ~[mut T]) {
         let mut i = values.len();
         while i >= 2u {
@@ -240,20 +252,22 @@ impl of rng for @rand_res {
     fn next() -> u32 { ret rustrt::rand_next((*self).c); }
 }
 
-#[doc = "Create a new random seed for seeded_rng"]
+/// Create a new random seed for seeded_rng
 fn seed() -> ~[u8] {
     rustrt::rand_seed()
 }
 
-#[doc = "Create a random number generator with a system specified seed"]
+/// Create a random number generator with a system specified seed
 fn rng() -> rng {
     @rand_res(rustrt::rand_new()) as rng
 }
 
-#[doc = "Create a random number generator using the specified seed. A \
-         generator constructed with a given seed will generate the same \
-         sequence of values as all other generators constructed with the \
-         same seed. The seed may be any length."]
+/**
+ * Create a random number generator using the specified seed. A generator
+ * constructed with a given seed will generate the same sequence of values as
+ * all other generators constructed with the same seed. The seed may be any
+ * length.
+ */
 fn seeded_rng(seed: ~[u8]) -> rng {
     @rand_res(rustrt::rand_new_seeded(seed)) as rng
 }
diff --git a/src/libcore/result.rs b/src/libcore/result.rs
index 64d5ff9c73c..677d19e0964 100644
--- a/src/libcore/result.rs
+++ b/src/libcore/result.rs
@@ -1,22 +1,22 @@
-#[doc = "A type representing either success or failure"];
+//! A type representing either success or failure
 
 import either::either;
 
-#[doc = "The result type"]
+/// The result type
 enum result<T, U> {
-    #[doc = "Contains the successful result value"]
+    /// Contains the successful result value
     ok(T),
-    #[doc = "Contains the error value"]
+    /// Contains the error value
     err(U)
 }
 
-#[doc = "
-Get the value out of a successful result
-
-# Failure
-
-If the result is an error
-"]
+/**
+ * Get the value out of a successful result
+ *
+ * # Failure
+ *
+ * If the result is an error
+ */
 pure fn get<T: copy, U>(res: result<T, U>) -> T {
     alt res {
       ok(t) { t }
@@ -26,13 +26,13 @@ pure fn get<T: copy, U>(res: result<T, U>) -> T {
     }
 }
 
-#[doc = "
-Get the value out of an error result
-
-# Failure
-
-If the result is not an error
-"]
+/**
+ * Get the value out of an error result
+ *
+ * # Failure
+ *
+ * If the result is not an error
+ */
 pure fn get_err<T, U: copy>(res: result<T, U>) -> U {
     alt res {
       err(u) { u }
@@ -42,7 +42,7 @@ pure fn get_err<T, U: copy>(res: result<T, U>) -> U {
     }
 }
 
-#[doc = "Returns true if the result is `ok`"]
+/// Returns true if the result is `ok`
 pure fn is_ok<T, U>(res: result<T, U>) -> bool {
     alt res {
       ok(_) { true }
@@ -50,17 +50,17 @@ pure fn is_ok<T, U>(res: result<T, U>) -> bool {
     }
 }
 
-#[doc = "Returns true if the result is `err`"]
+/// Returns true if the result is `err`
 pure fn is_err<T, U>(res: result<T, U>) -> bool {
     !is_ok(res)
 }
 
-#[doc = "
-Convert to the `either` type
-
-`ok` result variants are converted to `either::right` variants, `err`
-result variants are converted to `either::left`.
-"]
+/**
+ * Convert to the `either` type
+ *
+ * `ok` result variants are converted to `either::right` variants, `err`
+ * result variants are converted to `either::left`.
+ */
 pure fn to_either<T: copy, U: copy>(res: result<U, T>) -> either<T, U> {
     alt res {
       ok(res) { either::right(res) }
@@ -68,19 +68,20 @@ pure fn to_either<T: copy, U: copy>(res: result<U, T>) -> either<T, U> {
     }
 }
 
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `ok` then the value is extracted and passed to `op` whereupon
-`op`s result is returned. if `res` is `err` then it is immediately returned.
-This function can be used to compose the results of two functions.
-
-Example:
-
-    let res = chain(read_file(file)) { |buf|
-        ok(parse_buf(buf))
-    }
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `ok` then the value is extracted and passed to `op` whereupon
+ * `op`s result is returned. if `res` is `err` then it is immediately
+ * returned. This function can be used to compose the results of two
+ * functions.
+ *
+ * Example:
+ *
+ *     let res = chain(read_file(file)) { |buf|
+ *         ok(parse_buf(buf))
+ *     }
+ */
 fn chain<T, U: copy, V: copy>(res: result<T, V>, op: fn(T) -> result<U, V>)
     -> result<U, V> {
     alt res {
@@ -89,14 +90,14 @@ fn chain<T, U: copy, V: copy>(res: result<T, V>, op: fn(T) -> result<U, V>)
     }
 }
 
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `err` then the value is extracted and passed to `op`
-whereupon `op`s result is returned. if `res` is `ok` then it is
-immediately returned.  This function can be used to pass through a
-successful result while handling an error.
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `err` then the value is extracted and passed to `op`
+ * whereupon `op`s result is returned. if `res` is `ok` then it is
+ * immediately returned.  This function can be used to pass through a
+ * successful result while handling an error.
+ */
 fn chain_err<T: copy, U: copy, V: copy>(
     res: result<T, V>,
     op: fn(V) -> result<T, U>)
@@ -107,19 +108,20 @@ fn chain_err<T: copy, U: copy, V: copy>(
     }
 }
 
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `ok` then the value is extracted and passed to `op` whereupon
-`op`s result is returned. if `res` is `err` then it is immediately returned.
-This function can be used to compose the results of two functions.
-
-Example:
-
-    iter(read_file(file)) { |buf|
-        print_buf(buf)
-    }
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `ok` then the value is extracted and passed to `op` whereupon
+ * `op`s result is returned. if `res` is `err` then it is immediately
+ * returned. This function can be used to compose the results of two
+ * functions.
+ *
+ * Example:
+ *
+ *     iter(read_file(file)) { |buf|
+ *         print_buf(buf)
+ *     }
+ */
 fn iter<T, E>(res: result<T, E>, f: fn(T)) {
     alt res {
       ok(t) { f(t) }
@@ -127,14 +129,14 @@ fn iter<T, E>(res: result<T, E>, f: fn(T)) {
     }
 }
 
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `err` then the value is extracted and passed to `op` whereupon
-`op`s result is returned. if `res` is `ok` then it is immediately returned.
-This function can be used to pass through a successful result while handling
-an error.
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `err` then the value is extracted and passed to `op` whereupon
+ * `op`s result is returned. if `res` is `ok` then it is immediately returned.
+ * This function can be used to pass through a successful result while
+ * handling an error.
+ */
 fn iter_err<T, E>(res: result<T, E>, f: fn(E)) {
     alt res {
       ok(_) { }
@@ -142,20 +144,20 @@ fn iter_err<T, E>(res: result<T, E>, f: fn(E)) {
     }
 }
 
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `ok` then the value is extracted and passed to `op` whereupon
-`op`s result is wrapped in `ok` and returned. if `res` is `err` then it is
-immediately returned.  This function can be used to compose the results of two
-functions.
-
-Example:
-
-    let res = map(read_file(file)) { |buf|
-        parse_buf(buf)
-    }
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `ok` then the value is extracted and passed to `op` whereupon
+ * `op`s result is wrapped in `ok` and returned. if `res` is `err` then it is
+ * immediately returned.  This function can be used to compose the results of
+ * two functions.
+ *
+ * Example:
+ *
+ *     let res = map(read_file(file)) { |buf|
+ *         parse_buf(buf)
+ *     }
+ */
 fn map<T, E: copy, U: copy>(res: result<T, E>, op: fn(T) -> U)
   -> result<U, E> {
     alt res {
@@ -164,14 +166,14 @@ fn map<T, E: copy, U: copy>(res: result<T, E>, op: fn(T) -> U)
     }
 }
 
-#[doc = "
-Call a function based on a previous result
-
-If `res` is `err` then the value is extracted and passed to `op` whereupon
-`op`s result is wrapped in an `err` and returned. if `res` is `ok` then it is
-immediately returned.  This function can be used to pass through a successful
-result while handling an error.
-"]
+/**
+ * Call a function based on a previous result
+ *
+ * If `res` is `err` then the value is extracted and passed to `op` whereupon
+ * `op`s result is wrapped in an `err` and returned. if `res` is `ok` then it
+ * is immediately returned.  This function can be used to pass through a
+ * successful result while handling an error.
+ */
 fn map_err<T: copy, E, F: copy>(res: result<T, E>, op: fn(E) -> F)
   -> result<T, F> {
     alt res {
@@ -232,23 +234,23 @@ impl extensions<T:copy, E:copy> for result<T,E> {
     }
 }
 
-#[doc = "
-Maps each element in the vector `ts` using the operation `op`.  Should an
-error occur, no further mappings are performed and the error is returned.
-Should no error occur, a vector containing the result of each map is
-returned.
-
-Here is an example which increments every integer in a vector,
-checking for overflow:
-
-    fn inc_conditionally(x: uint) -> result<uint,str> {
-        if x == uint::max_value { ret err(\"overflow\"); }
-        else { ret ok(x+1u); }
-    }
-    map([1u, 2u, 3u]/~, inc_conditionally).chain {|incd|
-        assert incd == [2u, 3u, 4u]/~;
-    }
-"]
+/**
+ * Maps each element in the vector `ts` using the operation `op`.  Should an
+ * error occur, no further mappings are performed and the error is returned.
+ * Should no error occur, a vector containing the result of each map is
+ * returned.
+ *
+ * Here is an example which increments every integer in a vector,
+ * checking for overflow:
+ *
+ *     fn inc_conditionally(x: uint) -> result<uint,str> {
+ *         if x == uint::max_value { ret err("overflow"); }
+ *         else { ret ok(x+1u); }
+ *     }
+ *     map([1u, 2u, 3u]/~, inc_conditionally).chain {|incd|
+ *         assert incd == [2u, 3u, 4u]/~;
+ *     }
+ */
 fn map_vec<T,U:copy,V:copy>(
     ts: ~[T], op: fn(T) -> result<V,U>) -> result<~[V],U> {
 
@@ -277,13 +279,15 @@ fn map_opt<T,U:copy,V:copy>(
     }
 }
 
-#[doc = "Same as map, but it operates over two parallel vectors.
-
-A precondition is used here to ensure that the vectors are the same
-length.  While we do not often use preconditions in the standard
-library, a precondition is used here because result::t is generally
-used in 'careful' code contexts where it is both appropriate and easy
-to accommodate an error like the vectors being of different lengths."]
+/**
+ * Same as map, but it operates over two parallel vectors.
+ *
+ * A precondition is used here to ensure that the vectors are the same
+ * length.  While we do not often use preconditions in the standard
+ * library, a precondition is used here because result::t is generally
+ * used in 'careful' code contexts where it is both appropriate and easy
+ * to accommodate an error like the vectors being of different lengths.
+ */
 fn map_vec2<S,T,U:copy,V:copy>(ss: ~[S], ts: ~[T],
                                op: fn(S,T) -> result<V,U>)
     : vec::same_length(ss, ts) -> result<~[V],U> {
@@ -302,11 +306,11 @@ fn map_vec2<S,T,U:copy,V:copy>(ss: ~[S], ts: ~[T],
     ret ok(vs);
 }
 
-#[doc = "
-Applies op to the pairwise elements from `ss` and `ts`, aborting on
-error.  This could be implemented using `map2()` but it is more efficient
-on its own as no result vector is built.
-"]
+/**
+ * Applies op to the pairwise elements from `ss` and `ts`, aborting on
+ * error.  This could be implemented using `map2()` but it is more efficient
+ * on its own as no result vector is built.
+ */
 fn iter_vec2<S,T,U:copy>(ss: ~[S], ts: ~[T],
                          op: fn(S,T) -> result<(),U>)
     : vec::same_length(ss, ts)
@@ -324,9 +328,7 @@ fn iter_vec2<S,T,U:copy>(ss: ~[S], ts: ~[T],
     ret ok(());
 }
 
-#[doc="
-Unwraps a result, assuming it is an `ok(T)`
-"]
+/// Unwraps a result, assuming it is an `ok(T)`
 fn unwrap<T, U>(-res: result<T, U>) -> T {
     unsafe {
         let addr = alt res {
diff --git a/src/libcore/run.rs b/src/libcore/run.rs
index 432b12ddbf7..55a58430fc0 100644
--- a/src/libcore/run.rs
+++ b/src/libcore/run.rs
@@ -1,4 +1,4 @@
-#[doc ="Process spawning"];
+//! Process spawning
 import option::{some, none};
 import libc::{pid_t, c_void, c_int};
 
@@ -17,51 +17,51 @@ extern mod rustrt {
         -> pid_t;
 }
 
-#[doc ="A value representing a child process"]
+/// A value representing a child process
 iface program {
-    #[doc ="Returns the process id of the program"]
+    /// Returns the process id of the program
     fn get_id() -> pid_t;
 
-    #[doc ="Returns an io::writer that can be used to write to stdin"]
+    /// Returns an io::writer that can be used to write to stdin
     fn input() -> io::writer;
 
-    #[doc ="Returns an io::reader that can be used to read from stdout"]
+    /// Returns an io::reader that can be used to read from stdout
     fn output() -> io::reader;
 
-    #[doc ="Returns an io::reader that can be used to read from stderr"]
+    /// Returns an io::reader that can be used to read from stderr
     fn err() -> io::reader;
 
-    #[doc = "Closes the handle to the child processes standard input"]
+    /// Closes the handle to the child processes standard input
     fn close_input();
 
-    #[doc = "
-    Waits for the child process to terminate. Closes the handle
-    to stdin if necessary.
-    "]
+    /**
+     * Waits for the child process to terminate. Closes the handle
+     * to stdin if necessary.
+     */
     fn finish() -> int;
 
-    #[doc ="Closes open handles"]
+    /// Closes open handles
     fn destroy();
 }
 
 
-#[doc = "
-Run a program, providing stdin, stdout and stderr handles
-
-# Arguments
-
-* prog - The path to an executable
-* args - Vector of arguments to pass to the child process
-* env - optional env-modification for child
-* dir - optional dir to run child in (default current dir)
-* in_fd - A file descriptor for the child to use as std input
-* out_fd - A file descriptor for the child to use as std output
-* err_fd - A file descriptor for the child to use as std error
-
-# Return value
-
-The process id of the spawned process
-"]
+/**
+ * Run a program, providing stdin, stdout and stderr handles
+ *
+ * # Arguments
+ *
+ * * prog - The path to an executable
+ * * args - Vector of arguments to pass to the child process
+ * * env - optional env-modification for child
+ * * dir - optional dir to run child in (default current dir)
+ * * in_fd - A file descriptor for the child to use as std input
+ * * out_fd - A file descriptor for the child to use as std output
+ * * err_fd - A file descriptor for the child to use as std error
+ *
+ * # Return value
+ *
+ * The process id of the spawned process
+ */
 fn spawn_process(prog: str, args: ~[str],
                  env: option<~[(str,str)]>,
                  dir: option<str>,
@@ -152,18 +152,18 @@ fn with_dirp<T>(d: option<str>,
     }
 }
 
-#[doc ="
-Spawns a process and waits for it to terminate
-
-# Arguments
-
-* prog - The path to an executable
-* args - Vector of arguments to pass to the child process
-
-# Return value
-
-The process id
-"]
+/**
+ * Spawns a process and waits for it to terminate
+ *
+ * # Arguments
+ *
+ * * prog - The path to an executable
+ * * args - Vector of arguments to pass to the child process
+ *
+ * # Return value
+ *
+ * The process id
+ */
 fn run_program(prog: str, args: ~[str]) -> int {
     let pid = spawn_process(prog, args, none, none,
                             0i32, 0i32, 0i32);
@@ -171,22 +171,22 @@ fn run_program(prog: str, args: ~[str]) -> int {
     ret waitpid(pid);
 }
 
-#[doc ="
-Spawns a process and returns a program
-
-The returned value is a boxed class containing a <program> object that can
-be used for sending and receiving data over the standard file descriptors.
-The class will ensure that file descriptors are closed properly.
-
-# Arguments
-
-* prog - The path to an executable
-* args - Vector of arguments to pass to the child process
-
-# Return value
-
-A class with a <program> field
-"]
+/**
+ * Spawns a process and returns a program
+ *
+ * The returned value is a boxed class containing a <program> object that can
+ * be used for sending and receiving data over the standard file descriptors.
+ * The class will ensure that file descriptors are closed properly.
+ *
+ * # Arguments
+ *
+ * * prog - The path to an executable
+ * * args - Vector of arguments to pass to the child process
+ *
+ * # Return value
+ *
+ * A class with a <program> field
+ */
 fn start_program(prog: str, args: ~[str]) -> program {
     let pipe_input = os::pipe();
     let pipe_output = os::pipe();
@@ -257,20 +257,20 @@ fn read_all(rd: io::reader) -> str {
     ret buf;
 }
 
-#[doc ="
-Spawns a process, waits for it to exit, and returns the exit code, and
-contents of stdout and stderr.
-
-# Arguments
-
-* prog - The path to an executable
-* args - Vector of arguments to pass to the child process
-
-# Return value
-
-A record, {status: int, out: str, err: str} containing the exit code,
-the contents of stdout and the contents of stderr.
-"]
+/**
+ * Spawns a process, waits for it to exit, and returns the exit code, and
+ * contents of stdout and stderr.
+ *
+ * # Arguments
+ *
+ * * prog - The path to an executable
+ * * args - Vector of arguments to pass to the child process
+ *
+ * # Return value
+ *
+ * A record, {status: int, out: str, err: str} containing the exit code,
+ * the contents of stdout and the contents of stderr.
+ */
 fn program_output(prog: str, args: ~[str]) ->
    {status: int, out: str, err: str} {
 
@@ -347,7 +347,7 @@ fn readclose(fd: c_int) -> str {
     ret buf;
 }
 
-#[doc ="Waits for a process to exit and returns the exit code"]
+/// Waits for a process to exit and returns the exit code
 fn waitpid(pid: pid_t) -> int {
     ret waitpid_os(pid);
 
diff --git a/src/libcore/str.rs b/src/libcore/str.rs
index b87a575fdef..43a9e8f6981 100644
--- a/src/libcore/str.rs
+++ b/src/libcore/str.rs
@@ -1,11 +1,11 @@
-#[doc = "
-String manipulation
-
-Strings are a packed UTF-8 representation of text, stored as null
-terminated buffers of u8 bytes.  Strings should be indexed in bytes,
-for efficiency, but UTF-8 unsafe operations should be avoided.  For
-some heavy-duty uses, try std::rope.
-"];
+/*!
+ * String manipulation
+ *
+ * Strings are a packed UTF-8 representation of text, stored as null
+ * terminated buffers of u8 bytes.  Strings should be indexed in bytes,
+ * for efficiency, but UTF-8 unsafe operations should be avoided.  For
+ * some heavy-duty uses, try std::rope.
+ */
 
 import libc::size_t;
 
@@ -115,32 +115,32 @@ extern mod rustrt {
 Section: Creating a string
 */
 
-#[doc = "
-Convert a vector of bytes to a UTF-8 string
-
-# Failure
-
-Fails if invalid UTF-8
-"]
+/**
+ * Convert a vector of bytes to a UTF-8 string
+ *
+ * # Failure
+ *
+ * Fails if invalid UTF-8
+ */
 pure fn from_bytes(+vv: ~[u8]) -> str {
     assert is_utf8(vv);
     ret unsafe { unsafe::from_bytes(vv) };
 }
 
-#[doc = "
-Convert a byte to a UTF-8 string
-
-# Failure
-
-Fails if invalid UTF-8
-"]
+/**
+ * Convert a byte to a UTF-8 string
+ *
+ * # Failure
+ *
+ * Fails if invalid UTF-8
+ */
 pure fn from_byte(b: u8) -> str {
     assert b < 128u8;
     let mut v = ~[b, 0u8];
     unsafe { ::unsafe::transmute(v) }
 }
 
-#[doc = "Appends a character at the end of a string"]
+/// Appends a character at the end of a string
 fn push_char(&s: str, ch: char) {
     unsafe {
         let code = ch as uint;
@@ -216,14 +216,14 @@ fn push_char(&s: str, ch: char) {
     }
 }
 
-#[doc = "Convert a char to a string"]
+/// Convert a char to a string
 pure fn from_char(ch: char) -> str {
     let mut buf = "";
     unchecked { push_char(buf, ch); }
     ret buf;
 }
 
-#[doc = "Convert a vector of chars to a string"]
+/// Convert a vector of chars to a string
 pure fn from_chars(chs: &[const char]) -> str {
     let mut buf = "";
     unchecked {
@@ -233,16 +233,14 @@ pure fn from_chars(chs: &[const char]) -> str {
     ret buf;
 }
 
-#[doc = "Concatenate a vector of strings"]
+/// Concatenate a vector of strings
 pure fn concat(v: &[const str]) -> str {
     let mut s: str = "";
     for vec::each(v) |ss| { s += ss; }
     ret s;
 }
 
-#[doc = "
-Concatenate a vector of strings, placing a given separator between each
-"]
+/// Concatenate a vector of strings, placing a given separator between each
 pure fn connect(v: &[const str], sep: str) -> str {
     let mut s = "", first = true;
     for vec::each(v) |ss| {
@@ -256,13 +254,13 @@ pure fn connect(v: &[const str], sep: str) -> str {
 Section: Adding to and removing from a string
 */
 
-#[doc = "
-Remove the final character from a string and return it
-
-# Failure
-
-If the string does not contain any characters
-"]
+/**
+ * Remove the final character from a string and return it
+ *
+ * # Failure
+ *
+ * If the string does not contain any characters
+ */
 fn pop_char(&s: str) -> char {
     let end = len(s);
     assert end > 0u;
@@ -271,23 +269,23 @@ fn pop_char(&s: str) -> char {
     ret ch;
 }
 
-#[doc = "
-Remove the first character from a string and return it
-
-# Failure
-
-If the string does not contain any characters
-"]
+/**
+ * Remove the first character from a string and return it
+ *
+ * # Failure
+ *
+ * If the string does not contain any characters
+ */
 fn shift_char(&s: str) -> char {
     let {ch, next} = char_range_at(s, 0u);
     s = unsafe { unsafe::slice_bytes(s, next, len(s)) };
     ret ch;
 }
 
-#[doc = "Prepend a char to a string"]
+/// Prepend a char to a string
 fn unshift_char(&s: str, ch: char) { s = from_char(ch) + s; }
 
-#[doc = "Returns a string with leading whitespace removed"]
+/// Returns a string with leading whitespace removed
 pure fn trim_left(+s: str) -> str {
     alt find(s, |c| !char::is_whitespace(c)) {
       none { "" }
@@ -298,7 +296,7 @@ pure fn trim_left(+s: str) -> str {
     }
 }
 
-#[doc = "Returns a string with trailing whitespace removed"]
+/// Returns a string with trailing whitespace removed
 pure fn trim_right(+s: str) -> str {
     alt rfind(s, |c| !char::is_whitespace(c)) {
       none { "" }
@@ -310,18 +308,18 @@ pure fn trim_right(+s: str) -> str {
     }
 }
 
-#[doc = "Returns a string with leading and trailing whitespace removed"]
+/// Returns a string with leading and trailing whitespace removed
 pure fn trim(+s: str) -> str { trim_left(trim_right(s)) }
 
 /*
 Section: Transforming strings
 */
 
-#[doc = "
-Converts a string to a vector of bytes
-
-The result vector is not null-terminated.
-"]
+/**
+ * Converts a string to a vector of bytes
+ *
+ * The result vector is not null-terminated.
+ */
 pure fn bytes(s: str) -> ~[u8] {
     unsafe {
         let mut s_copy = s;
@@ -331,9 +329,7 @@ pure fn bytes(s: str) -> ~[u8] {
     }
 }
 
-#[doc = "
-Work with the string as a byte slice, not including trailing null.
-"]
+/// Work with the string as a byte slice, not including trailing null.
 #[inline(always)]
 pure fn byte_slice<T>(s: str/&, f: fn(v: &[u8]) -> T) -> T {
     do unpack_slice(s) |p,n| {
@@ -341,7 +337,7 @@ pure fn byte_slice<T>(s: str/&, f: fn(v: &[u8]) -> T) -> T {
     }
 }
 
-#[doc = "Convert a string to a vector of characters"]
+/// Convert a string to a vector of characters
 pure fn chars(s: str/&) -> ~[char] {
     let mut buf = ~[], i = 0u;
     let len = len(s);
@@ -353,48 +349,44 @@ pure fn chars(s: str/&) -> ~[char] {
     ret buf;
 }
 
-#[doc = "
-Take a substring of another.
-
-Returns a string containing `n` characters starting at byte offset
-`begin`.
-"]
+/**
+ * Take a substring of another.
+ *
+ * Returns a string containing `n` characters starting at byte offset
+ * `begin`.
+ */
 pure fn substr(s: str/&, begin: uint, n: uint) -> str {
     slice(s, begin, begin + count_bytes(s, begin, n))
 }
 
-#[doc = "
-Returns a slice of the given string from the byte range [`begin`..`end`)
-
-Fails when `begin` and `end` do not point to valid characters or
-beyond the last character of the string
-"]
+/**
+ * Returns a slice of the given string from the byte range [`begin`..`end`)
+ *
+ * Fails when `begin` and `end` do not point to valid characters or
+ * beyond the last character of the string
+ */
 pure fn slice(s: str/&, begin: uint, end: uint) -> str {
     assert is_char_boundary(s, begin);
     assert is_char_boundary(s, end);
     unsafe { unsafe::slice_bytes(s, begin, end) }
 }
 
-#[doc = "
-Splits a string into substrings at each occurrence of a given character
-"]
+/// Splits a string into substrings at each occurrence of a given character
 pure fn split_char(s: str/&, sep: char) -> ~[str] {
     split_char_inner(s, sep, len(s), true)
 }
 
-#[doc = "
-Splits a string into substrings at each occurrence of a given
-character up to 'count' times
-
-The byte must be a valid UTF-8/ASCII byte
-"]
+/**
+ * Splits a string into substrings at each occurrence of a given
+ * character up to 'count' times
+ *
+ * The byte must be a valid UTF-8/ASCII byte
+ */
 pure fn splitn_char(s: str/&, sep: char, count: uint) -> ~[str] {
     split_char_inner(s, sep, count, true)
 }
 
-#[doc = "
-Like `split_char`, but omits empty strings from the returned vector
-"]
+/// Like `split_char`, but omits empty strings from the returned vector
 pure fn split_char_nonempty(s: str/&, sep: char) -> ~[str] {
     split_char_inner(s, sep, len(s), false)
 }
@@ -426,20 +418,20 @@ pure fn split_char_inner(s: str/&, sep: char, count: uint, allow_empty: bool)
 }
 
 
-#[doc = "Splits a string into substrings using a character function"]
+/// Splits a string into substrings using a character function
 pure fn split(s: str/&, sepfn: fn(char) -> bool) -> ~[str] {
     split_inner(s, sepfn, len(s), true)
 }
 
-#[doc = "
-Splits a string into substrings using a character function, cutting at
-most `count` times.
-"]
+/**
+ * Splits a string into substrings using a character function, cutting at
+ * most `count` times.
+ */
 pure fn splitn(s: str/&, sepfn: fn(char) -> bool, count: uint) -> ~[str] {
     split_inner(s, sepfn, count, true)
 }
 
-#[doc = "Like `split`, but omits empty strings from the returned vector"]
+/// Like `split`, but omits empty strings from the returned vector
 pure fn split_nonempty(s: str/&, sepfn: fn(char) -> bool) -> ~[str] {
     split_inner(s, sepfn, len(s), false)
 }
@@ -502,15 +494,15 @@ pure fn iter_between_matches(s: str/&a, sep: str/&b, f: fn(uint, uint)) {
     f(last_end, len(s));
 }
 
-#[doc = "
-Splits a string into a vector of the substrings separated by a given string
-
-# Example
-
-~~~
-assert [\"\", \"XXX\", \"YYY\", \"\"] == split_str(\".XXX.YYY.\", \".\")
-~~~
-"]
+/**
+ * Splits a string into a vector of the substrings separated by a given string
+ *
+ * # Example
+ *
+ * ~~~
+ * assert ["", "XXX", "YYY", ""] == split_str(".XXX.YYY.", ".")
+ * ~~~
+ */
 pure fn split_str(s: str/&a, sep: str/&b) -> ~[str] {
     let mut result = ~[];
     do iter_between_matches(s, sep) |from, to| {
@@ -529,15 +521,15 @@ pure fn split_str_nonempty(s: str/&a, sep: str/&b) -> ~[str] {
     result
 }
 
-#[doc = "
-Splits a string into a vector of the substrings separated by LF ('\\n')
-"]
+/**
+ * Splits a string into a vector of the substrings separated by LF ('\n')
+ */
 pure fn lines(s: str/&) -> ~[str] { split_char(s, '\n') }
 
-#[doc = "
-Splits a string into a vector of the substrings separated by LF ('\\n')
-and/or CR LF ('\\r\\n')
-"]
+/**
+ * Splits a string into a vector of the substrings separated by LF ('\n')
+ * and/or CR LF ("\r\n")
+ */
 pure fn lines_any(s: str/&) -> ~[str] {
     vec::map(lines(s), |s| {
         let l = len(s);
@@ -549,40 +541,38 @@ pure fn lines_any(s: str/&) -> ~[str] {
     })
 }
 
-#[doc = "
-Splits a string into a vector of the substrings separated by whitespace
-"]
+/// Splits a string into a vector of the substrings separated by whitespace
 pure fn words(s: str/&) -> ~[str] {
     split_nonempty(s, |c| char::is_whitespace(c))
 }
 
-#[doc = "Convert a string to lowercase. ASCII only"]
+/// Convert a string to lowercase. ASCII only
 pure fn to_lower(s: str/&) -> str {
     map(s,
         |c| unchecked{(libc::tolower(c as libc::c_char)) as char}
     )
 }
 
-#[doc = "Convert a string to uppercase. ASCII only"]
+/// Convert a string to uppercase. ASCII only
 pure fn to_upper(s: str/&) -> str {
     map(s,
         |c| unchecked{(libc::toupper(c as libc::c_char)) as char}
     )
 }
 
-#[doc = "
-Replace all occurrences of one string with another
-
-# Arguments
-
-* s - The string containing substrings to replace
-* from - The string to replace
-* to - The replacement string
-
-# Return value
-
-The original string with all occurances of `from` replaced with `to`
-"]
+/**
+ * Replace all occurrences of one string with another
+ *
+ * # Arguments
+ *
+ * * s - The string containing substrings to replace
+ * * from - The string to replace
+ * * to - The replacement string
+ *
+ * # Return value
+ *
+ * The original string with all occurances of `from` replaced with `to`
+ */
 pure fn replace(s: str, from: str, to: str) -> str {
     let mut result = "", first = true;
     do iter_between_matches(s, from) |start, end| {
@@ -596,7 +586,7 @@ pure fn replace(s: str, from: str, to: str) -> str {
 Section: Comparing strings
 */
 
-#[doc = "Bytewise string equality"]
+/// Bytewise string equality
 pure fn eq(&&a: str, &&b: str) -> bool {
     // FIXME (#2627): This should just be "a == b" but that calls into the
     // shape code.
@@ -614,10 +604,10 @@ pure fn eq(&&a: str, &&b: str) -> bool {
     ret true;
 }
 
-#[doc = "Bytewise less than or equal"]
+/// Bytewise less than or equal
 pure fn le(&&a: str, &&b: str) -> bool { a <= b }
 
-#[doc = "String hash function"]
+/// String hash function
 pure fn hash(&&s: str) -> uint {
     // djb hash.
     // FIXME: replace with murmur. (see #859 and #1616)
@@ -630,23 +620,23 @@ pure fn hash(&&s: str) -> uint {
 Section: Iterating through strings
 */
 
-#[doc = "
-Return true if a predicate matches all characters or if the string
-contains no characters
-"]
+/**
+ * Return true if a predicate matches all characters or if the string
+ * contains no characters
+ */
 pure fn all(s: str/&, it: fn(char) -> bool) -> bool {
     all_between(s, 0u, len(s), it)
 }
 
-#[doc = "
-Return true if a predicate matches any character (and false if it
-matches none or there are no characters)
-"]
+/**
+ * Return true if a predicate matches any character (and false if it
+ * matches none or there are no characters)
+ */
 pure fn any(ss: str/&, pred: fn(char) -> bool) -> bool {
     !all(ss, |cc| !pred(cc))
 }
 
-#[doc = "Apply a function to each character"]
+/// Apply a function to each character
 pure fn map(ss: str/&, ff: fn(char) -> char) -> str {
     let mut result = "";
     unchecked {
@@ -658,7 +648,7 @@ pure fn map(ss: str/&, ff: fn(char) -> char) -> str {
     result
 }
 
-#[doc = "Iterate over the bytes in a string"]
+/// Iterate over the bytes in a string
 pure fn bytes_iter(ss: str/&, it: fn(u8)) {
     let mut pos = 0u;
     let len = len(ss);
@@ -669,13 +659,13 @@ pure fn bytes_iter(ss: str/&, it: fn(u8)) {
     }
 }
 
-#[doc = "Iterate over the bytes in a string"]
+/// Iterate over the bytes in a string
 #[inline(always)]
 pure fn each(s: str/&, it: fn(u8) -> bool) {
     eachi(s, |_i, b| it(b) )
 }
 
-#[doc = "Iterate over the bytes in a string, with indices"]
+/// Iterate over the bytes in a string, with indices
 #[inline(always)]
 pure fn eachi(s: str/&, it: fn(uint, u8) -> bool) {
     let mut i = 0u, l = len(s);
@@ -685,13 +675,13 @@ pure fn eachi(s: str/&, it: fn(uint, u8) -> bool) {
     }
 }
 
-#[doc = "Iterates over the chars in a string"]
+/// Iterates over the chars in a string
 #[inline(always)]
 pure fn each_char(s: str/&, it: fn(char) -> bool) {
     each_chari(s, |_i, c| it(c))
 }
 
-#[doc = "Iterates over the chars in a string, with indices"]
+/// Iterates over the chars in a string, with indices
 #[inline(always)]
 pure fn each_chari(s: str/&, it: fn(uint, char) -> bool) {
     let mut pos = 0u, ch_pos = 0u;
@@ -704,7 +694,7 @@ pure fn each_chari(s: str/&, it: fn(uint, char) -> bool) {
     }
 }
 
-#[doc = "Iterate over the characters in a string"]
+/// Iterate over the characters in a string
 pure fn chars_iter(s: str/&, it: fn(char)) {
     let mut pos = 0u;
     let len = len(s);
@@ -715,28 +705,28 @@ pure fn chars_iter(s: str/&, it: fn(char)) {
     }
 }
 
-#[doc = "
-Apply a function to each substring after splitting by character
-"]
+/// Apply a function to each substring after splitting by character
 pure fn split_char_iter(ss: str/&, cc: char, ff: fn(&&str)) {
    vec::iter(split_char(ss, cc), ff)
 }
 
-#[doc = "
-Apply a function to each substring after splitting by character, up to
-`count` times
-"]
+/**
+ * Apply a function to each substring after splitting by character, up to
+ * `count` times
+ */
 pure fn splitn_char_iter(ss: str/&, sep: char, count: uint,
                          ff: fn(&&str)) {
    vec::iter(splitn_char(ss, sep, count), ff)
 }
 
-#[doc = "Apply a function to each word"]
+/// Apply a function to each word
 pure fn words_iter(ss: str/&, ff: fn(&&str)) {
     vec::iter(words(ss), ff)
 }
 
-#[doc = "Apply a function to each line (by '\\n')"]
+/**
+ * Apply a function to each line (by '\n')
+ */
 pure fn lines_iter(ss: str/&, ff: fn(&&str)) {
     vec::iter(lines(ss), ff)
 }
@@ -745,68 +735,68 @@ pure fn lines_iter(ss: str/&, ff: fn(&&str)) {
 Section: Searching
 */
 
-#[doc = "
-Returns the byte index of the first matching character
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-"]
+/**
+ * Returns the byte index of the first matching character
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ */
 pure fn find_char(s: str/&, c: char) -> option<uint> {
     find_char_between(s, c, 0u, len(s))
 }
 
-#[doc = "
-Returns the byte index of the first matching character beginning
-from a given byte offset
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-* `start` - The byte index to begin searching at, inclusive
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `len(s)`. `start` must be the
-index of a character boundary, as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the first matching character beginning
+ * from a given byte offset
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ * * `start` - The byte index to begin searching at, inclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `len(s)`. `start` must be the
+ * index of a character boundary, as defined by `is_char_boundary`.
+ */
 pure fn find_char_from(s: str/&, c: char, start: uint) -> option<uint> {
     find_char_between(s, c, start, len(s))
 }
 
-#[doc = "
-Returns the byte index of the first matching character within a given range
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-* `start` - The byte index to begin searching at, inclusive
-* `end` - The byte index to end searching at, exclusive
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `end` and `end` must be less than
-or equal to `len(s)`. `start` must be the index of a character boundary,
-as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the first matching character within a given range
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ * * `start` - The byte index to begin searching at, inclusive
+ * * `end` - The byte index to end searching at, exclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `end` and `end` must be less than
+ * or equal to `len(s)`. `start` must be the index of a character boundary,
+ * as defined by `is_char_boundary`.
+ */
 pure fn find_char_between(s: str/&, c: char, start: uint, end: uint)
     -> option<uint> {
     if c < 128u as char {
@@ -824,68 +814,68 @@ pure fn find_char_between(s: str/&, c: char, start: uint, end: uint)
     }
 }
 
-#[doc = "
-Returns the byte index of the last matching character
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-"]
+/**
+ * Returns the byte index of the last matching character
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ */
 pure fn rfind_char(s: str/&, c: char) -> option<uint> {
     rfind_char_between(s, c, len(s), 0u)
 }
 
-#[doc = "
-Returns the byte index of the last matching character beginning
-from a given byte offset
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-* `start` - The byte index to begin searching at, exclusive
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `len(s)`. `start` must be
-the index of a character boundary, as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the last matching character beginning
+ * from a given byte offset
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ * * `start` - The byte index to begin searching at, exclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `len(s)`. `start` must be
+ * the index of a character boundary, as defined by `is_char_boundary`.
+ */
 pure fn rfind_char_from(s: str/&, c: char, start: uint) -> option<uint> {
     rfind_char_between(s, c, start, 0u)
 }
 
-#[doc = "
-Returns the byte index of the last matching character within a given range
-
-# Arguments
-
-* `s` - The string to search
-* `c` - The character to search for
-* `start` - The byte index to begin searching at, exclusive
-* `end` - The byte index to end searching at, inclusive
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-
-# Failure
-
-`end` must be less than or equal to `start` and `start` must be less than
-or equal to `len(s)`. `start` must be the index of a character boundary,
-as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the last matching character within a given range
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `c` - The character to search for
+ * * `start` - The byte index to begin searching at, exclusive
+ * * `end` - The byte index to end searching at, inclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `end` must be less than or equal to `start` and `start` must be less than
+ * or equal to `len(s)`. `start` must be the index of a character boundary,
+ * as defined by `is_char_boundary`.
+ */
 pure fn rfind_char_between(s: str/&, c: char, start: uint, end: uint)
     -> option<uint> {
     if c < 128u as char {
@@ -903,71 +893,71 @@ pure fn rfind_char_between(s: str/&, c: char, start: uint, end: uint)
     }
 }
 
-#[doc = "
-Returns the byte index of the first character that satisfies
-the given predicate
-
-# Arguments
-
-* `s` - The string to search
-* `f` - The predicate to satisfy
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-"]
+/**
+ * Returns the byte index of the first character that satisfies
+ * the given predicate
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ */
 pure fn find(s: str/&, f: fn(char) -> bool) -> option<uint> {
     find_between(s, 0u, len(s), f)
 }
 
-#[doc = "
-Returns the byte index of the first character that satisfies
-the given predicate, beginning from a given byte offset
-
-# Arguments
-
-* `s` - The string to search
-* `start` - The byte index to begin searching at, inclusive
-* `f` - The predicate to satisfy
-
-# Return value
-
-An `option` containing the byte index of the first matching charactor
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `len(s)`. `start` must be the
-index of a character boundary, as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the first character that satisfies
+ * the given predicate, beginning from a given byte offset
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `start` - The byte index to begin searching at, inclusive
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching charactor
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `len(s)`. `start` must be the
+ * index of a character boundary, as defined by `is_char_boundary`.
+ */
 pure fn find_from(s: str/&, start: uint, f: fn(char)
     -> bool) -> option<uint> {
     find_between(s, start, len(s), f)
 }
 
-#[doc = "
-Returns the byte index of the first character that satisfies
-the given predicate, within a given range
-
-# Arguments
-
-* `s` - The string to search
-* `start` - The byte index to begin searching at, inclusive
-* `end` - The byte index to end searching at, exclusive
-* `f` - The predicate to satisfy
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `end` and `end` must be less than
-or equal to `len(s)`. `start` must be the index of a character
-boundary, as defined by `is_char_boundary`.
-"]
+/**
+ * Returns the byte index of the first character that satisfies
+ * the given predicate, within a given range
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `start` - The byte index to begin searching at, inclusive
+ * * `end` - The byte index to end searching at, exclusive
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `end` and `end` must be less than
+ * or equal to `len(s)`. `start` must be the index of a character
+ * boundary, as defined by `is_char_boundary`.
+ */
 pure fn find_between(s: str/&, start: uint, end: uint, f: fn(char) -> bool)
     -> option<uint> {
     assert start <= end;
@@ -982,71 +972,71 @@ pure fn find_between(s: str/&, start: uint, end: uint, f: fn(char) -> bool)
     ret none;
 }
 
-#[doc = "
-Returns the byte index of the last character that satisfies
-the given predicate
-
-# Arguments
-
-* `s` - The string to search
-* `f` - The predicate to satisfy
-
-# Return value
-
-An option containing the byte index of the last matching character
-or `none` if there is no match
-"]
+/**
+ * Returns the byte index of the last character that satisfies
+ * the given predicate
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An option containing the byte index of the last matching character
+ * or `none` if there is no match
+ */
 pure fn rfind(s: str/&, f: fn(char) -> bool) -> option<uint> {
     rfind_between(s, len(s), 0u, f)
 }
 
-#[doc = "
-Returns the byte index of the last character that satisfies
-the given predicate, beginning from a given byte offset
-
-# Arguments
-
-* `s` - The string to search
-* `start` - The byte index to begin searching at, exclusive
-* `f` - The predicate to satisfy
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `len(s)', `start` must be the
-index of a character boundary, as defined by `is_char_boundary`
-"]
+/**
+ * Returns the byte index of the last character that satisfies
+ * the given predicate, beginning from a given byte offset
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `start` - The byte index to begin searching at, exclusive
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `len(s)', `start` must be the
+ * index of a character boundary, as defined by `is_char_boundary`
+ */
 pure fn rfind_from(s: str/&, start: uint, f: fn(char) -> bool)
     -> option<uint> {
     rfind_between(s, start, 0u, f)
 }
 
-#[doc = "
-Returns the byte index of the last character that satisfies
-the given predicate, within a given range
-
-# Arguments
-
-* `s` - The string to search
-* `start` - The byte index to begin searching at, exclusive
-* `end` - The byte index to end searching at, inclusive
-* `f` - The predicate to satisfy
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-
-# Failure
-
-`end` must be less than or equal to `start` and `start` must be less
-than or equal to `len(s)`. `start` must be the index of a character
-boundary, as defined by `is_char_boundary`
-"]
+/**
+ * Returns the byte index of the last character that satisfies
+ * the given predicate, within a given range
+ *
+ * # Arguments
+ *
+ * * `s` - The string to search
+ * * `start` - The byte index to begin searching at, exclusive
+ * * `end` - The byte index to end searching at, inclusive
+ * * `f` - The predicate to satisfy
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `end` must be less than or equal to `start` and `start` must be less
+ * than or equal to `len(s)`. `start` must be the index of a character
+ * boundary, as defined by `is_char_boundary`
+ */
 pure fn rfind_between(s: str/&, start: uint, end: uint, f: fn(char) -> bool)
     -> option<uint> {
     assert start >= end;
@@ -1068,67 +1058,67 @@ pure fn match_at(haystack: str/&a, needle: str/&b, at: uint) -> bool {
     ret true;
 }
 
-#[doc = "
-Returns the byte index of the first matching substring
-
-# Arguments
-
-* `haystack` - The string to search
-* `needle` - The string to search for
-
-# Return value
-
-An `option` containing the byte index of the first matching substring
-or `none` if there is no match
-"]
+/**
+ * Returns the byte index of the first matching substring
+ *
+ * # Arguments
+ *
+ * * `haystack` - The string to search
+ * * `needle` - The string to search for
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching substring
+ * or `none` if there is no match
+ */
 pure fn find_str(haystack: str/&a, needle: str/&b) -> option<uint> {
     find_str_between(haystack, needle, 0u, len(haystack))
 }
 
-#[doc = "
-Returns the byte index of the first matching substring beginning
-from a given byte offset
-
-# Arguments
-
-* `haystack` - The string to search
-* `needle` - The string to search for
-* `start` - The byte index to begin searching at, inclusive
-
-# Return value
-
-An `option` containing the byte index of the last matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `len(s)`
-"]
+/**
+ * Returns the byte index of the first matching substring beginning
+ * from a given byte offset
+ *
+ * # Arguments
+ *
+ * * `haystack` - The string to search
+ * * `needle` - The string to search for
+ * * `start` - The byte index to begin searching at, inclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the last matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `len(s)`
+ */
 pure fn find_str_from(haystack: str/&a, needle: str/&b, start: uint)
   -> option<uint> {
     find_str_between(haystack, needle, start, len(haystack))
 }
 
-#[doc = "
-Returns the byte index of the first matching substring within a given range
-
-# Arguments
-
-* `haystack` - The string to search
-* `needle` - The string to search for
-* `start` - The byte index to begin searching at, inclusive
-* `end` - The byte index to end searching at, exclusive
-
-# Return value
-
-An `option` containing the byte index of the first matching character
-or `none` if there is no match
-
-# Failure
-
-`start` must be less than or equal to `end` and `end` must be less than
-or equal to `len(s)`.
-"]
+/**
+ * Returns the byte index of the first matching substring within a given range
+ *
+ * # Arguments
+ *
+ * * `haystack` - The string to search
+ * * `needle` - The string to search for
+ * * `start` - The byte index to begin searching at, inclusive
+ * * `end` - The byte index to end searching at, exclusive
+ *
+ * # Return value
+ *
+ * An `option` containing the byte index of the first matching character
+ * or `none` if there is no match
+ *
+ * # Failure
+ *
+ * `start` must be less than or equal to `end` and `end` must be less than
+ * or equal to `len(s)`.
+ */
 pure fn find_str_between(haystack: str/&a, needle: str/&b, start: uint,
                          end:uint)
   -> option<uint> {
@@ -1147,38 +1137,38 @@ pure fn find_str_between(haystack: str/&a, needle: str/&b, start: uint,
     ret none;
 }
 
-#[doc = "
-Returns true if one string contains another
-
-# Arguments
-
-* haystack - The string to look in
-* needle - The string to look for
-"]
+/**
+ * Returns true if one string contains another
+ *
+ * # Arguments
+ *
+ * * haystack - The string to look in
+ * * needle - The string to look for
+ */
 pure fn contains(haystack: str/&a, needle: str/&b) -> bool {
     option::is_some(find_str(haystack, needle))
 }
 
-#[doc = "
-Returns true if a string contains a char.
-
-# Arguments
-
-* haystack - The string to look in
-* needle - The char to look for
-"]
+/**
+ * Returns true if a string contains a char.
+ *
+ * # Arguments
+ *
+ * * haystack - The string to look in
+ * * needle - The char to look for
+ */
 pure fn contains_char(haystack: str/&, needle: char) -> bool {
     option::is_some(find_char(haystack, needle))
 }
 
-#[doc = "
-Returns true if one string starts with another
-
-# Arguments
-
-* haystack - The string to look in
-* needle - The string to look for
-"]
+/**
+ * Returns true if one string starts with another
+ *
+ * # Arguments
+ *
+ * * haystack - The string to look in
+ * * needle - The string to look for
+ */
 pure fn starts_with(haystack: str/&a, needle: str/&b) -> bool {
     let haystack_len = len(haystack), needle_len = len(needle);
     if needle_len == 0u { true }
@@ -1186,14 +1176,14 @@ pure fn starts_with(haystack: str/&a, needle: str/&b) -> bool {
     else { match_at(haystack, needle, 0u) }
 }
 
-#[doc = "
-Returns true if one string ends with another
-
-# Arguments
-
-* haystack - The string to look in
-* needle - The string to look for
-"]
+/**
+ * Returns true if one string ends with another
+ *
+ * # Arguments
+ *
+ * * haystack - The string to look in
+ * * needle - The string to look for
+ */
 pure fn ends_with(haystack: str/&a, needle: str/&b) -> bool {
     let haystack_len = len(haystack), needle_len = len(needle);
     if needle_len == 0u { true }
@@ -1205,52 +1195,50 @@ pure fn ends_with(haystack: str/&a, needle: str/&b) -> bool {
 Section: String properties
 */
 
-#[doc = "Determines if a string contains only ASCII characters"]
+/// Determines if a string contains only ASCII characters
 pure fn is_ascii(s: str/&) -> bool {
     let mut i: uint = len(s);
     while i > 0u { i -= 1u; if !u8::is_ascii(s[i]) { ret false; } }
     ret true;
 }
 
-#[doc = "Returns true if the string has length 0"]
+/// Returns true if the string has length 0
 pure fn is_empty(s: str/&) -> bool { len(s) == 0u }
 
-#[doc = "Returns true if the string has length greater than 0"]
+/// Returns true if the string has length greater than 0
 pure fn is_not_empty(s: str/&) -> bool { !is_empty(s) }
 
-#[doc = "
-Returns true if the string contains only whitespace
-
-Whitespace characters are determined by `char::is_whitespace`
-"]
+/**
+ * Returns true if the string contains only whitespace
+ *
+ * Whitespace characters are determined by `char::is_whitespace`
+ */
 pure fn is_whitespace(s: str/&) -> bool {
     ret all(s, char::is_whitespace);
 }
 
-#[doc = "
-Returns true if the string contains only alphanumerics
-
-Alphanumeric characters are determined by `char::is_alphanumeric`
-"]
+/**
+ * Returns true if the string contains only alphanumerics
+ *
+ * Alphanumeric characters are determined by `char::is_alphanumeric`
+ */
 fn is_alphanumeric(s: str/&) -> bool {
     ret all(s, char::is_alphanumeric);
 }
 
-#[doc = "
-Returns the string length/size in bytes not counting the null terminator
-"]
+/// Returns the string length/size in bytes not counting the null terminator
 pure fn len(s: str/&) -> uint {
     do unpack_slice(s) |_p, n| { n - 1u }
 }
 
-#[doc = "Returns the number of characters that a string holds"]
+/// Returns the number of characters that a string holds
 pure fn char_len(s: str/&) -> uint { count_chars(s, 0u, len(s)) }
 
 /*
 Section: Misc
 */
 
-#[doc = "Determines if a vector of bytes contains valid UTF-8"]
+/// Determines if a vector of bytes contains valid UTF-8
 pure fn is_utf8(v: &[const u8]) -> bool {
     let mut i = 0u;
     let total = vec::len::<u8>(v);
@@ -1268,7 +1256,7 @@ pure fn is_utf8(v: &[const u8]) -> bool {
     ret true;
 }
 
-#[doc = "Determines if a vector of `u16` contains valid UTF-16"]
+/// Determines if a vector of `u16` contains valid UTF-16
 pure fn is_utf16(v: &[const u16]) -> bool {
     let len = vec::len(v);
     let mut i = 0u;
@@ -1289,7 +1277,7 @@ pure fn is_utf16(v: &[const u16]) -> bool {
     ret true;
 }
 
-#[doc = "Converts to a vector of `u16` encoded as UTF-16"]
+/// Converts to a vector of `u16` encoded as UTF-16
 pure fn to_utf16(s: str/&) -> ~[u16] {
     let mut u = ~[];
     do chars_iter(s) |cch| {
@@ -1347,19 +1335,19 @@ pure fn from_utf16(v: &[const u16]) -> str {
 }
 
 
-#[doc = "
-As char_len but for a slice of a string
-
-# Arguments
-
-* s - A valid string
-* start - The position inside `s` where to start counting in bytes
-* end - The position where to stop counting
-
-# Return value
-
-The number of Unicode characters in `s` between the given indices.
-"]
+/**
+ * As char_len but for a slice of a string
+ *
+ * # Arguments
+ *
+ * * s - A valid string
+ * * start - The position inside `s` where to start counting in bytes
+ * * end - The position where to stop counting
+ *
+ * # Return value
+ *
+ * The number of Unicode characters in `s` between the given indices.
+ */
 pure fn count_chars(s: str/&, start: uint, end: uint) -> uint {
     assert is_char_boundary(s, start);
     assert is_char_boundary(s, end);
@@ -1372,9 +1360,7 @@ pure fn count_chars(s: str/&, start: uint, end: uint) -> uint {
     ret len;
 }
 
-#[doc = "
-Counts the number of bytes taken by the `n` in `s` starting from `start`.
-"]
+/// Counts the number of bytes taken by the `n` in `s` starting from `start`.
 pure fn count_bytes(s: str/&b, start: uint, n: uint) -> uint {
     assert is_char_boundary(s, start);
     let mut end = start, cnt = n;
@@ -1388,9 +1374,7 @@ pure fn count_bytes(s: str/&b, start: uint, n: uint) -> uint {
     end - start
 }
 
-#[doc = "
-Given a first byte, determine how many bytes are in this UTF-8 character
-"]
+/// Given a first byte, determine how many bytes are in this UTF-8 character
 pure fn utf8_char_width(b: u8) -> uint {
     let byte: uint = b as uint;
     if byte < 128u { ret 1u; }
@@ -1403,63 +1387,65 @@ pure fn utf8_char_width(b: u8) -> uint {
     ret 6u;
 }
 
-#[doc = "
-Returns false if the index points into the middle of a multi-byte
-character sequence.
-"]
+/**
+ * Returns false if the index points into the middle of a multi-byte
+ * character sequence.
+ */
 pure fn is_char_boundary(s: str/&, index: uint) -> bool {
     if index == len(s) { ret true; }
     let b = s[index];
     ret b < 128u8 || b >= 192u8;
 }
 
-#[doc = "
-Pluck a character out of a string and return the index of the next character.
-
-This function can be used to iterate over the unicode characters of a string.
-
-# Example
-
-~~~
-let s = \"中华Việt Nam\";
-let i = 0u;
-while i < str::len(s) {
-    let {ch, next} = str::char_range_at(s, i);
-    std::io::println(#fmt(\"%u: %c\",i,ch));
-    i = next;
-}
-~~~
-
-# Example output
-
-~~~
-0: 中
-3: 华
-6: V
-7: i
-8: ệ
-11: t
-12:
-13: N
-14: a
-15: m
-~~~
-
-# Arguments
-
-* s - The string
-* i - The byte offset of the char to extract
-
-# Return value
-
-A record {ch: char, next: uint} containing the char value and the byte
-index of the next unicode character.
-
-# Failure
-
-If `i` is greater than or equal to the length of the string.
-If `i` is not the index of the beginning of a valid UTF-8 character.
-"]
+/**
+ * Pluck a character out of a string and return the index of the next
+ * character.
+ *
+ * This function can be used to iterate over the unicode characters of a
+ * string.
+ *
+ * # Example
+ *
+ * ~~~
+ * let s = "中华Việt Nam";
+ * let i = 0u;
+ * while i < str::len(s) {
+ *     let {ch, next} = str::char_range_at(s, i);
+ *     std::io::println(#fmt("%u: %c",i,ch));
+ *     i = next;
+ * }
+ * ~~~
+ *
+ * # Example output
+ *
+ * ~~~
+ * 0: 中
+ * 3: 华
+ * 6: V
+ * 7: i
+ * 8: ệ
+ * 11: t
+ * 12:
+ * 13: N
+ * 14: a
+ * 15: m
+ * ~~~
+ *
+ * # Arguments
+ *
+ * * s - The string
+ * * i - The byte offset of the char to extract
+ *
+ * # Return value
+ *
+ * A record {ch: char, next: uint} containing the char value and the byte
+ * index of the next unicode character.
+ *
+ * # Failure
+ *
+ * If `i` is greater than or equal to the length of the string.
+ * If `i` is not the index of the beginning of a valid UTF-8 character.
+ */
 pure fn char_range_at(s: str/&, i: uint) -> {ch: char, next: uint} {
     let b0 = s[i];
     let w = utf8_char_width(b0);
@@ -1482,14 +1468,14 @@ pure fn char_range_at(s: str/&, i: uint) -> {ch: char, next: uint} {
     ret {ch: val as char, next: i};
 }
 
-#[doc = "Pluck a character out of a string"]
+/// Pluck a character out of a string
 pure fn char_at(s: str/&, i: uint) -> char { ret char_range_at(s, i).ch; }
 
-#[doc = "
-Given a byte position and a str, return the previous char and its position
-
-This function can be used to iterate over a unicode string in reverse.
-"]
+/**
+ * Given a byte position and a str, return the previous char and its position
+ *
+ * This function can be used to iterate over a unicode string in reverse.
+ */
 pure fn char_range_at_reverse(ss: str/&, start: uint)
     -> {ch: char, prev: uint} {
 
@@ -1507,28 +1493,28 @@ pure fn char_range_at_reverse(ss: str/&, start: uint)
     ret {ch:ch, prev:prev};
 }
 
-#[doc = "
-Loop through a substring, char by char
-
-# Safety note
-
-* This function does not check whether the substring is valid.
-* This function fails if `start` or `end` do not
-  represent valid positions inside `s`
-
-# Arguments
-
-* s - A string to traverse. It may be empty.
-* start - The byte offset at which to start in the string.
-* end - The end of the range to traverse
-* it - A block to execute with each consecutive character of `s`.
-       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 substring, char by char
+ *
+ * # Safety note
+ *
+ * * This function does not check whether the substring is valid.
+ * * This function fails if `start` or `end` do not
+ *   represent valid positions inside `s`
+ *
+ * # Arguments
+ *
+ * * s - A string to traverse. It may be empty.
+ * * start - The byte offset at which to start in the string.
+ * * end - The end of the range to traverse
+ * * it - A block to execute with each consecutive character of `s`.
+ *        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.
+ */
 pure fn all_between(s: str/&, start: uint, end: uint,
                     it: fn(char) -> bool) -> bool {
     assert is_char_boundary(s, start);
@@ -1541,27 +1527,27 @@ pure fn all_between(s: str/&, start: uint, end: uint,
     ret true;
 }
 
-#[doc = "
-Loop through a substring, char by char
-
-# Safety note
-
-* This function does not check whether the substring is valid.
-* This function fails if `start` or `end` do not
-  represent valid positions inside `s`
-
-# Arguments
-
-* s - A string to traverse. It may be empty.
-* start - The byte offset at which to start in the string.
-* end - The end of the range to traverse
-* it - A block to execute with each consecutive character of `s`.
-       Return `true` to continue, `false` to stop.
-
-# Return value
-
-`true` if `it` returns `true` for any character
-"]
+/**
+ * Loop through a substring, char by char
+ *
+ * # Safety note
+ *
+ * * This function does not check whether the substring is valid.
+ * * This function fails if `start` or `end` do not
+ *   represent valid positions inside `s`
+ *
+ * # Arguments
+ *
+ * * s - A string to traverse. It may be empty.
+ * * start - The byte offset at which to start in the string.
+ * * end - The end of the range to traverse
+ * * it - A block to execute with each consecutive character of `s`.
+ *        Return `true` to continue, `false` to stop.
+ *
+ * # Return value
+ *
+ * `true` if `it` returns `true` for any character
+ */
 pure fn any_between(s: str/&, start: uint, end: uint,
                     it: fn(char) -> bool) -> bool {
     !all_between(s, start, end, |c| !it(c))
@@ -1582,18 +1568,18 @@ const max_five_b: uint = 67108864u;
 const tag_six_b: uint = 252u;
 
 
-#[doc = "
-Work with the byte buffer of a string.
-
-Allows for unsafe manipulation of strings, which is useful for foreign
-interop.
-
-# Example
-
-~~~
-let i = str::as_bytes(\"Hello World\") { |bytes| vec::len(bytes) };
-~~~
-"]
+/**
+ * Work with the byte buffer of a string.
+ *
+ * Allows for unsafe manipulation of strings, which is useful for foreign
+ * interop.
+ *
+ * # Example
+ *
+ * ~~~
+ * let i = str::as_bytes("Hello World") { |bytes| vec::len(bytes) };
+ * ~~~
+ */
 pure fn as_bytes<T>(s: str, f: fn(~[u8]) -> T) -> T {
     unsafe {
         let v: *~[u8] = ::unsafe::reinterpret_cast(ptr::addr_of(s));
@@ -1601,41 +1587,41 @@ pure fn as_bytes<T>(s: str, f: fn(~[u8]) -> T) -> T {
     }
 }
 
-#[doc = "
-Work with the byte buffer of a string.
-
-Allows for unsafe manipulation of strings, which is useful for foreign
-interop.
-"]
+/**
+ * Work with the byte buffer of a string.
+ *
+ * Allows for unsafe manipulation of strings, which is useful for foreign
+ * interop.
+ */
 pure fn as_buf<T>(s: str, f: fn(*u8) -> T) -> T {
     as_bytes(s, |v| unsafe { vec::as_buf(v, f) })
 }
 
-#[doc = "
-Work with the byte buffer of a string as a null-terminated C string.
-
-Allows for unsafe manipulation of strings, which is useful for foreign
-interop, without copying the original string.
-
-# Example
-
-~~~
-let s = str::as_buf(\"PATH\", { |path_buf| libc::getenv(path_buf) });
-~~~
-"]
+/**
+ * Work with the byte buffer of a string as a null-terminated C string.
+ *
+ * Allows for unsafe manipulation of strings, which is useful for foreign
+ * interop, without copying the original string.
+ *
+ * # Example
+ *
+ * ~~~
+ * let s = str::as_buf("PATH", { |path_buf| libc::getenv(path_buf) });
+ * ~~~
+ */
 pure fn as_c_str<T>(s: str, f: fn(*libc::c_char) -> T) -> T {
     as_buf(s, |buf| f(buf as *libc::c_char))
 }
 
 
-#[doc = "
-Work with the byte buffer and length of a slice.
-
-The unpacked length is one byte longer than the 'official' indexable
-length of the string. This is to permit probing the byte past the
-indexable area for a null byte, as is the case in slices pointing
-to full strings, or suffixes of them.
-"]
+/**
+ * Work with the byte buffer and length of a slice.
+ *
+ * The unpacked length is one byte longer than the 'official' indexable
+ * length of the string. This is to permit probing the byte past the
+ * indexable area for a null byte, as is the case in slices pointing
+ * to full strings, or suffixes of them.
+ */
 #[inline(always)]
 pure fn unpack_slice<T>(s: str/&, f: fn(*u8, uint) -> T) -> T {
     unsafe {
@@ -1645,56 +1631,56 @@ pure fn unpack_slice<T>(s: str/&, f: fn(*u8, uint) -> T) -> T {
     }
 }
 
-#[doc = "
-Reserves capacity for exactly `n` bytes in the given string, not including
-the null terminator.
-
-Assuming single-byte characters, the resulting string will be large
-enough to hold a string of length `n`. To account for the null terminator,
-the underlying buffer will have the size `n` + 1.
-
-If the capacity for `s` is already equal to or greater than the requested
-capacity, then no action is taken.
-
-# Arguments
-
-* s - A string
-* n - The number of bytes to reserve space for
-"]
+/**
+ * Reserves capacity for exactly `n` bytes in the given string, not including
+ * the null terminator.
+ *
+ * Assuming single-byte characters, the resulting string will be large
+ * enough to hold a string of length `n`. To account for the null terminator,
+ * the underlying buffer will have the size `n` + 1.
+ *
+ * If the capacity for `s` is already equal to or greater than the requested
+ * capacity, then no action is taken.
+ *
+ * # Arguments
+ *
+ * * s - A string
+ * * n - The number of bytes to reserve space for
+ */
 fn reserve(&s: str, n: uint) {
     if capacity(s) < n {
         rustrt::str_reserve_shared(s, n as size_t);
     }
 }
 
-#[doc = "
-Reserves capacity for at least `n` bytes in the given string, not including
-the null terminator.
-
-Assuming single-byte characters, the resulting string will be large
-enough to hold a string of length `n`. To account for the null terminator,
-the underlying buffer will have the size `n` + 1.
-
-This function will over-allocate in order to amortize the allocation costs
-in scenarios where the caller may need to repeatedly reserve additional
-space.
-
-If the capacity for `s` is already equal to or greater than the requested
-capacity, then no action is taken.
-
-# Arguments
-
-* s - A string
-* n - The number of bytes to reserve space for
-"]
+/**
+ * Reserves capacity for at least `n` bytes in the given string, not including
+ * the null terminator.
+ *
+ * Assuming single-byte characters, the resulting string will be large
+ * enough to hold a string of length `n`. To account for the null terminator,
+ * the underlying buffer will have the size `n` + 1.
+ *
+ * This function will over-allocate in order to amortize the allocation costs
+ * in scenarios where the caller may need to repeatedly reserve additional
+ * space.
+ *
+ * If the capacity for `s` is already equal to or greater than the requested
+ * capacity, then no action is taken.
+ *
+ * # Arguments
+ *
+ * * s - A string
+ * * n - The number of bytes to reserve space for
+ */
 fn reserve_at_least(&s: str, n: uint) {
     reserve(s, uint::next_power_of_two(n + 1u) - 1u)
 }
 
-#[doc = "
-Returns the number of single-byte characters the string can hold without
-reallocating
-"]
+/**
+ * Returns the number of single-byte characters the string can hold without
+ * reallocating
+ */
 pure fn capacity(&&s: str) -> uint {
     do as_bytes(s) |buf| {
         let vcap = vec::capacity(buf);
@@ -1703,7 +1689,7 @@ pure fn capacity(&&s: str) -> uint {
     }
 }
 
-#[doc = "Escape each char in `s` with char::escape_default."]
+/// Escape each char in `s` with char::escape_default.
 pure fn escape_default(s: str/&) -> str {
     let mut out: str = "";
     unchecked {
@@ -1713,7 +1699,7 @@ pure fn escape_default(s: str/&) -> str {
     ret out;
 }
 
-#[doc = "Escape each char in `s` with char::escape_unicode."]
+/// Escape each char in `s` with char::escape_unicode.
 pure fn escape_unicode(s: str/&) -> str {
     let mut out: str = "";
     unchecked {
@@ -1723,7 +1709,7 @@ pure fn escape_unicode(s: str/&) -> str {
     ret out;
 }
 
-#[doc = "Unsafe operations"]
+/// Unsafe operations
 mod unsafe {
    export
       from_buf,
@@ -1737,7 +1723,7 @@ mod unsafe {
       shift_byte,
       set_len;
 
-    #[doc = "Create a Rust string from a null-terminated *u8 buffer"]
+    /// Create a Rust string from a null-terminated *u8 buffer
     unsafe fn from_buf(buf: *u8) -> str {
         let mut curr = buf, i = 0u;
         while *curr != 0u8 {
@@ -1747,7 +1733,7 @@ mod unsafe {
         ret from_buf_len(buf, i);
     }
 
-    #[doc = "Create a Rust string from a *u8 buffer of the given length"]
+    /// Create a Rust string from a *u8 buffer of the given length
     unsafe fn from_buf_len(buf: *u8, len: uint) -> str {
         let mut v: ~[u8] = ~[];
         vec::reserve(v, len + 1u);
@@ -1759,23 +1745,21 @@ mod unsafe {
         ret ::unsafe::transmute(v);
     }
 
-    #[doc = "Create a Rust string from a null-terminated C string"]
+    /// Create a Rust string from a null-terminated C string
     unsafe fn from_c_str(c_str: *libc::c_char) -> str {
         from_buf(::unsafe::reinterpret_cast(c_str))
     }
 
-    #[doc = "
-    Create a Rust string from a `*c_char` buffer of the given length
-    "]
+    /// Create a Rust string from a `*c_char` buffer of the given length
     unsafe fn from_c_str_len(c_str: *libc::c_char, len: uint) -> str {
         from_buf_len(::unsafe::reinterpret_cast(c_str), len)
     }
 
-   #[doc = "
-   Converts a vector of bytes to a string.
-
-   Does not verify that the vector contains valid UTF-8.
-   "]
+   /**
+    * Converts a vector of bytes to a string.
+    *
+    * Does not verify that the vector contains valid UTF-8.
+    */
    unsafe fn from_bytes(+v: ~[const u8]) -> str {
        unsafe {
            let mut vcopy = ::unsafe::transmute(v);
@@ -1784,23 +1768,23 @@ mod unsafe {
        }
    }
 
-   #[doc = "
-   Converts a byte to a string.
-
-   Does not verify that the byte is valid UTF-8.
-   "]
+   /**
+    * Converts a byte to a string.
+    *
+    * Does not verify that the byte is valid UTF-8.
+    */
    unsafe fn from_byte(u: u8) -> str { unsafe::from_bytes(~[u]) }
 
-   #[doc = "
-   Takes a bytewise (not UTF-8) slice from a string.
-
-   Returns the substring from [`begin`..`end`).
-
-   # Failure
-
-   If begin is greater than end.
-   If end is greater than the length of the string.
-   "]
+   /**
+    * Takes a bytewise (not UTF-8) slice from a string.
+    *
+    * Returns the substring from [`begin`..`end`).
+    *
+    * # Failure
+    *
+    * If begin is greater than end.
+    * If end is greater than the length of the string.
+    */
    unsafe fn slice_bytes(s: str/&, begin: uint, end: uint) -> str {
        do unpack_slice(s) |sbuf, n| {
            assert (begin <= end);
@@ -1820,19 +1804,17 @@ mod unsafe {
        }
    }
 
-   #[doc = "Appends a byte to a string. (Not UTF-8 safe)."]
+   /// Appends a byte to a string. (Not UTF-8 safe).
    unsafe fn push_byte(&s: str, b: u8) {
        rustrt::rust_str_push(s, b);
    }
 
-   #[doc = "Appends a vector of bytes to a string. (Not UTF-8 safe)."]
+   /// Appends a vector of bytes to a string. (Not UTF-8 safe).
    unsafe fn push_bytes(&s: str, bytes: ~[u8]) {
        for vec::each(bytes) |byte| { rustrt::rust_str_push(s, byte); }
    }
 
-   #[doc = "
-   Removes the last byte from a string and returns it. (Not UTF-8 safe).
-   "]
+   /// Removes the last byte from a string and returns it. (Not UTF-8 safe).
    unsafe fn pop_byte(&s: str) -> u8 {
        let len = len(s);
        assert (len > 0u);
@@ -1841,9 +1823,7 @@ mod unsafe {
        ret b;
    }
 
-   #[doc = "
-   Removes the first byte from a string and returns it. (Not UTF-8 safe).
-   "]
+   /// Removes the first byte from a string and returns it. (Not UTF-8 safe).
    unsafe fn shift_byte(&s: str) -> u8 {
        let len = len(s);
        assert (len > 0u);
@@ -1852,9 +1832,7 @@ mod unsafe {
        ret b;
    }
 
-    #[doc = "
-    Sets the length of the string and adds the null terminator
-    "]
+    /// Sets the length of the string and adds the null terminator
     unsafe fn set_len(&v: str, new_len: uint) {
         let repr: *vec::unsafe::vec_repr = ::unsafe::reinterpret_cast(v);
         (*repr).fill = new_len + 1u;
@@ -1874,120 +1852,121 @@ mod unsafe {
 
 }
 
-#[doc = "Extension methods for strings"]
+/// Extension methods for strings
 impl extensions for str {
-    #[doc = "Returns a string with leading and trailing whitespace removed"]
+    /// Returns a string with leading and trailing whitespace removed
     #[inline]
     fn trim() -> str { trim(self) }
-    #[doc = "Returns a string with leading whitespace removed"]
+    /// Returns a string with leading whitespace removed
     #[inline]
     fn trim_left() -> str { trim_left(self) }
-    #[doc = "Returns a string with trailing whitespace removed"]
+    /// Returns a string with trailing whitespace removed
     #[inline]
     fn trim_right() -> str { trim_right(self) }
 }
 
-#[doc = "Extension methods for strings"]
+/// Extension methods for strings
 impl extensions/& for str/& {
-    #[doc = "
-    Return true if a predicate matches all characters or if the string
-    contains no characters
-    "]
+    /**
+     * Return true if a predicate matches all characters or if the string
+     * contains no characters
+     */
     #[inline]
     fn all(it: fn(char) -> bool) -> bool { all(self, it) }
-    #[doc = "
-    Return true if a predicate matches any character (and false if it
-    matches none or there are no characters)
-    "]
+    /**
+     * Return true if a predicate matches any character (and false if it
+     * matches none or there are no characters)
+     */
     #[inline]
     fn any(it: fn(char) -> bool) -> bool { any(self, it) }
-    #[doc = "Returns true if one string contains another"]
+    /// Returns true if one string contains another
     #[inline]
     fn contains(needle: str/&a) -> bool { contains(self, needle) }
-    #[doc = "Returns true if a string contains a char"]
+    /// Returns true if a string contains a char
     #[inline]
     fn contains_char(needle: char) -> bool { contains_char(self, needle) }
-    #[doc = "Iterate over the bytes in a string"]
+    /// Iterate over the bytes in a string
     #[inline]
     fn each(it: fn(u8) -> bool) { each(self, it) }
-    #[doc = "Iterate over the bytes in a string, with indices"]
+    /// Iterate over the bytes in a string, with indices
     #[inline]
     fn eachi(it: fn(uint, u8) -> bool) { eachi(self, it) }
-    #[doc = "Iterate over the chars in a string"]
+    /// Iterate over the chars in a string
     #[inline]
     fn each_char(it: fn(char) -> bool) { each_char(self, it) }
-    #[doc = "Iterate over the chars in a string, with indices"]
+    /// Iterate over the chars in a string, with indices
     #[inline]
     fn each_chari(it: fn(uint, char) -> bool) { each_chari(self, it) }
-    #[doc = "Returns true if one string ends with another"]
+    /// Returns true if one string ends with another
     #[inline]
     fn ends_with(needle: str/&) -> bool { ends_with(self, needle) }
-    #[doc = "Returns true if the string has length 0"]
+    /// Returns true if the string has length 0
     #[inline]
     fn is_empty() -> bool { is_empty(self) }
-    #[doc = "Returns true if the string has length greater than 0"]
+    /// Returns true if the string has length greater than 0
     #[inline]
     fn is_not_empty() -> bool { is_not_empty(self) }
-    #[doc = "
-    Returns true if the string contains only whitespace
-
-    Whitespace characters are determined by `char::is_whitespace`
-    "]
+    /**
+     * Returns true if the string contains only whitespace
+     *
+     * Whitespace characters are determined by `char::is_whitespace`
+     */
     #[inline]
     fn is_whitespace() -> bool { is_whitespace(self) }
-    #[doc = "
-    Returns true if the string contains only alphanumerics
-
-    Alphanumeric characters are determined by `char::is_alphanumeric`
-    "]
+    /**
+     * Returns true if the string contains only alphanumerics
+     *
+     * Alphanumeric characters are determined by `char::is_alphanumeric`
+     */
     #[inline]
     fn is_alphanumeric() -> bool { is_alphanumeric(self) }
     #[inline]
-    #[doc ="Returns the size in bytes not counting the null terminator"]
+    /// Returns the size in bytes not counting the null terminator
     pure fn len() -> uint { len(self) }
-    #[doc = "
-    Returns a slice of the given string from the byte range [`begin`..`end`)
-
-    Fails when `begin` and `end` do not point to valid characters or
-    beyond the last character of the string
-    "]
+    /**
+     * Returns a slice of the given string from the byte range
+     * [`begin`..`end`)
+     *
+     * Fails when `begin` and `end` do not point to valid characters or
+     * beyond the last character of the string
+     */
     #[inline]
     fn slice(begin: uint, end: uint) -> str { slice(self, begin, end) }
-    #[doc = "Splits a string into substrings using a character function"]
+    /// Splits a string into substrings using a character function
     #[inline]
     fn split(sepfn: fn(char) -> bool) -> ~[str] { split(self, sepfn) }
-    #[doc = "
-    Splits a string into substrings at each occurrence of a given character
-    "]
+    /**
+     * Splits a string into substrings at each occurrence of a given character
+     */
     #[inline]
     fn split_char(sep: char) -> ~[str] { split_char(self, sep) }
-    #[doc = "
-    Splits a string into a vector of the substrings separated by a given
-    string
-    "]
+    /**
+     * Splits a string into a vector of the substrings separated by a given
+     * string
+     */
     #[inline]
     fn split_str(sep: str/&a) -> ~[str] { split_str(self, sep) }
-    #[doc = "Returns true if one string starts with another"]
+    /// Returns true if one string starts with another
     #[inline]
     fn starts_with(needle: str/&a) -> bool { starts_with(self, needle) }
-    #[doc = "
-    Take a substring of another.
-
-    Returns a string containing `n` characters starting at byte offset
-    `begin`.
-    "]
+    /**
+     * Take a substring of another.
+     *
+     * Returns a string containing `n` characters starting at byte offset
+     * `begin`.
+     */
     #[inline]
     fn substr(begin: uint, n: uint) -> str { substr(self, begin, n) }
-    #[doc = "Convert a string to lowercase"]
+    /// Convert a string to lowercase
     #[inline]
     fn to_lower() -> str { to_lower(self) }
-    #[doc = "Convert a string to uppercase"]
+    /// Convert a string to uppercase
     #[inline]
     fn to_upper() -> str { to_upper(self) }
-    #[doc = "Escape each char in `s` with char::escape_default."]
+    /// Escape each char in `s` with char::escape_default.
     #[inline]
     fn escape_default() -> str { escape_default(self) }
-    #[doc = "Escape each char in `s` with char::escape_unicode."]
+    /// Escape each char in `s` with char::escape_unicode.
     #[inline]
     fn escape_unicode() -> str { escape_unicode(self) }
 }
diff --git a/src/libcore/sys.rs b/src/libcore/sys.rs
index 992083c484b..e99860a6250 100644
--- a/src/libcore/sys.rs
+++ b/src/libcore/sys.rs
@@ -1,4 +1,4 @@
-#[doc = "Misc low level stuff"];
+//! Misc low level stuff
 
 export type_desc;
 export get_type_desc;
@@ -39,38 +39,38 @@ extern mod rusti {
     fn min_align_of<T>() -> uint;
 }
 
-#[doc = "
-Returns a pointer to a type descriptor.
-
-Useful for calling certain function in the Rust runtime or otherwise
-performing dark magick.
-"]
+/**
+ * Returns a pointer to a type descriptor.
+ *
+ * Useful for calling certain function in the Rust runtime or otherwise
+ * performing dark magick.
+ */
 pure fn get_type_desc<T>() -> *type_desc {
     unchecked { rusti::get_tydesc::<T>() as *type_desc }
 }
 
-#[doc = "Returns the size of a type"]
+/// Returns the size of a type
 #[inline(always)]
 pure fn size_of<T>() -> uint {
     unchecked { rusti::size_of::<T>() }
 }
 
-#[doc = "
-Returns the ABI-required minimum alignment of a type
-
-This is the alignment used for struct fields. It may be smaller
-than the preferred alignment.
-"]
+/**
+ * Returns the ABI-required minimum alignment of a type
+ *
+ * This is the alignment used for struct fields. It may be smaller
+ * than the preferred alignment.
+ */
 pure fn min_align_of<T>() -> uint {
     unchecked { rusti::min_align_of::<T>() }
 }
 
-#[doc = "Returns the preferred alignment of a type"]
+/// Returns the preferred alignment of a type
 pure fn pref_align_of<T>() -> uint {
     unchecked { rusti::pref_align_of::<T>() }
 }
 
-#[doc = "Returns the refcount of a shared box (as just before calling this)"]
+/// Returns the refcount of a shared box (as just before calling this)
 pure fn refcount<T>(+t: @T) -> uint {
     unsafe {
         let ref_ptr: *uint = unsafe::reinterpret_cast(t);
diff --git a/src/libcore/task.rs b/src/libcore/task.rs
index d5e26a0f8ec..7794798de11 100644
--- a/src/libcore/task.rs
+++ b/src/libcore/task.rs
@@ -1,26 +1,27 @@
-#[doc = "
-Task management.
-
-An executing Rust program consists of a tree of tasks, each with their own
-stack, and sole ownership of their allocated heap data. Tasks communicate
-with each other using ports and channels.
-
-When a task fails, that failure will propagate to its parent (the task
-that spawned it) and the parent will fail as well. The reverse is not
-true: when a parent task fails its children will continue executing. When
-the root (main) task fails, all tasks fail, and then so does the entire
-process.
-
-Tasks may execute in parallel and are scheduled automatically by the runtime.
-
-# Example
-
-~~~
-spawn {||
-    log(error, \"Hello, World!\");
-}
-~~~
-"];
+/*!
+ * Task management.
+ *
+ * An executing Rust program consists of a tree of tasks, each with their own
+ * stack, and sole ownership of their allocated heap data. Tasks communicate
+ * with each other using ports and channels.
+ *
+ * When a task fails, that failure will propagate to its parent (the task
+ * that spawned it) and the parent will fail as well. The reverse is not
+ * true: when a parent task fails its children will continue executing. When
+ * the root (main) task fails, all tasks fail, and then so does the entire
+ * process.
+ *
+ * Tasks may execute in parallel and are scheduled automatically by the
+ * runtime.
+ *
+ * # Example
+ *
+ * ~~~
+ * spawn {||
+ *     log(error, "Hello, World!");
+ * }
+ * ~~~
+ */
 
 import result::result;
 import dvec::extensions;
@@ -63,106 +64,106 @@ export local_data_modify;
 
 /* Data types */
 
-#[doc = "A handle to a task"]
+/// A handle to a task
 enum task = task_id;
 
-#[doc = "
-Indicates the manner in which a task exited.
-
-A task that completes without failing and whose supervised children complete
-without failing is considered to exit successfully.
-
-FIXME (See #1868): This description does not indicate the current behavior
-for linked failure.
-"]
+/**
+ * Indicates the manner in which a task exited.
+ *
+ * A task that completes without failing and whose supervised children
+ * complete without failing is considered to exit successfully.
+ *
+ * FIXME (See #1868): This description does not indicate the current behavior
+ * for linked failure.
+ */
 enum task_result {
     success,
     failure,
 }
 
-#[doc = "A message type for notifying of task lifecycle events"]
+/// A message type for notifying of task lifecycle events
 enum notification {
-    #[doc = "Sent when a task exits with the task handle and result"]
+    /// Sent when a task exits with the task handle and result
     exit(task, task_result)
 }
 
-#[doc = "Scheduler modes"]
+/// Scheduler modes
 enum sched_mode {
-    #[doc = "1:N -- All tasks run in the same OS thread"]
+    /// All tasks run in the same OS thread
     single_threaded,
-    #[doc = "M:N -- Tasks are distributed among available CPUs"]
+    /// Tasks are distributed among available CPUs
     thread_per_core,
-    #[doc = "N:N -- Each task runs in its own OS thread"]
+    /// Each task runs in its own OS thread
     thread_per_task,
-    #[doc = "?:N -- Tasks are distributed among a fixed number of OS threads"]
+    /// Tasks are distributed among a fixed number of OS threads
     manual_threads(uint),
-    #[doc = "
-    Tasks are scheduled on the main OS thread
-
-    The main OS thread is the thread used to launch the runtime which,
-    in most cases, is the process's initial thread as created by the OS.
-    "]
+    /**
+     * Tasks are scheduled on the main OS thread
+     *
+     * The main OS thread is the thread used to launch the runtime which,
+     * in most cases, is the process's initial thread as created by the OS.
+     */
     osmain
 }
 
-#[doc = "
-Scheduler configuration options
-
-# Fields
-
-* sched_mode - The operating mode of the scheduler
-
-* foreign_stack_size - The size of the foreign stack, in bytes
-
-    Rust code runs on Rust-specific stacks. When Rust code calls foreign code
-    (via functions in foreign modules) it switches to a typical, large stack
-    appropriate for running code written in languages like C. By default these
-    foreign stacks have unspecified size, but with this option their size can
-    be precisely specified.
-"]
+/**
+ * Scheduler configuration options
+ *
+ * # Fields
+ *
+ * * sched_mode - The operating mode of the scheduler
+ *
+ * * foreign_stack_size - The size of the foreign stack, in bytes
+ *
+ *     Rust code runs on Rust-specific stacks. When Rust code calls foreign
+ *     code (via functions in foreign modules) it switches to a typical, large
+ *     stack appropriate for running code written in languages like C. By
+ *     default these foreign stacks have unspecified size, but with this
+ *     option their size can be precisely specified.
+ */
 type sched_opts = {
     mode: sched_mode,
     foreign_stack_size: option<uint>
 };
 
-#[doc = "
-Task configuration options
-
-# Fields
-
-* supervise - Do not propagate failure to the parent task
-
-    All tasks are linked together via a tree, from parents to children. By
-    default children are 'supervised' by their parent and when they fail
-    so too will their parents. Settings this flag to false disables that
-    behavior.
-
-* notify_chan - Enable lifecycle notifications on the given channel
-
-* sched - Specify the configuration of a new scheduler to create the task in
-
-    By default, every task is created in the same scheduler as its
-    parent, where it is scheduled cooperatively with all other tasks
-    in that scheduler. Some specialized applications may want more
-    control over their scheduling, in which case they can be spawned
-    into a new scheduler with the specific properties required.
-
-    This is of particular importance for libraries which want to call
-    into foreign code that blocks. Without doing so in a different
-    scheduler other tasks will be impeded or even blocked indefinitely.
-
-"]
+/**
+ * Task configuration options
+ *
+ * # Fields
+ *
+ * * supervise - Do not propagate failure to the parent task
+ *
+ *     All tasks are linked together via a tree, from parents to children. By
+ *     default children are 'supervised' by their parent and when they fail
+ *     so too will their parents. Settings this flag to false disables that
+ *     behavior.
+ *
+ * * notify_chan - Enable lifecycle notifications on the given channel
+ *
+ * * sched - Specify the configuration of a new scheduler to create the task
+ *           in
+ *
+ *     By default, every task is created in the same scheduler as its
+ *     parent, where it is scheduled cooperatively with all other tasks
+ *     in that scheduler. Some specialized applications may want more
+ *     control over their scheduling, in which case they can be spawned
+ *     into a new scheduler with the specific properties required.
+ *
+ *     This is of particular importance for libraries which want to call
+ *     into foreign code that blocks. Without doing so in a different
+ *     scheduler other tasks will be impeded or even blocked indefinitely.
+ */
 type task_opts = {
     supervise: bool,
     notify_chan: option<comm::chan<notification>>,
     sched: option<sched_opts>,
 };
 
-#[doc = "
-The task builder type.
-
-Provides detailed control over the properties and behavior of new tasks.
-"]
+/**
+ * The task builder type.
+ *
+ * Provides detailed control over the properties and behavior of new tasks.
+ */
 // NB: Builders are designed to be single-use because they do stateful
 // things that get weird when reusing - e.g. if you create a result future
 // it only applies to a single task, so then you have to maintain some
@@ -182,12 +183,12 @@ enum builder {
 /* Task construction */
 
 fn default_task_opts() -> task_opts {
-    #[doc = "
-    The default task options
-
-    By default all tasks are supervised by their parent, are spawned
-    into the same scheduler, and do not post lifecycle notifications.
-    "];
+    /*!
+     * The default task options
+     *
+     * By default all tasks are supervised by their parent, are spawned
+     * into the same scheduler, and do not post lifecycle notifications.
+     */
 
     {
         supervise: true,
@@ -197,7 +198,7 @@ fn default_task_opts() -> task_opts {
 }
 
 fn builder() -> builder {
-    #[doc = "Construct a builder"];
+    //! Construct a builder
 
     let body_identity = fn@(+body: fn~()) -> fn~() { body };
 
@@ -209,39 +210,39 @@ fn builder() -> builder {
 }
 
 fn get_opts(builder: builder) -> task_opts {
-    #[doc = "Get the task_opts associated with a builder"];
+    //! Get the task_opts associated with a builder
 
     builder.opts
 }
 
 fn set_opts(builder: builder, opts: task_opts) {
-    #[doc = "
-    Set the task_opts associated with a builder
-
-    To update a single option use a pattern like the following:
-
-        set_opts(builder, {
-            supervise: false
-            with get_opts(builder)
-        });
-    "];
+    /*!
+     * Set the task_opts associated with a builder
+     *
+     * To update a single option use a pattern like the following:
+     *
+     *     set_opts(builder, {
+     *         supervise: false
+     *         with get_opts(builder)
+     *     });
+     */
 
     builder.opts = opts;
 }
 
 fn add_wrapper(builder: builder, gen_body: fn@(+fn~()) -> fn~()) {
-    #[doc = "
-    Add a wrapper to the body of the spawned task.
-
-    Before the task is spawned it is passed through a 'body generator'
-    function that may perform local setup operations as well as wrap
-    the task body in remote setup operations. With this the behavior
-    of tasks can be extended in simple ways.
-
-    This function augments the current body generator with a new body
-    generator by applying the task body which results from the
-    existing body generator to the new body generator.
-    "];
+    /*!
+     * Add a wrapper to the body of the spawned task.
+     *
+     * Before the task is spawned it is passed through a 'body generator'
+     * function that may perform local setup operations as well as wrap
+     * the task body in remote setup operations. With this the behavior
+     * of tasks can be extended in simple ways.
+     *
+     * This function augments the current body generator with a new body
+     * generator by applying the task body which results from the
+     * existing body generator to the new body generator.
+     */
 
     let prev_gen_body = builder.gen_body;
     builder.gen_body = fn@(+body: fn~()) -> fn~() {
@@ -250,18 +251,18 @@ fn add_wrapper(builder: builder, gen_body: fn@(+fn~()) -> fn~()) {
 }
 
 fn run(-builder: builder, +f: fn~()) {
-    #[doc = "
-    Creates and exucutes a new child task
-
-    Sets up a new task with its own call stack and schedules it to run
-    the provided unique closure. The task has the properties and behavior
-    specified by `builder`.
-
-    # Failure
-
-    When spawning into a new scheduler, the number of threads requested
-    must be greater than zero.
-    "];
+    /*!
+     * Creates and exucutes a new child task
+     *
+     * Sets up a new task with its own call stack and schedules it to run
+     * the provided unique closure. The task has the properties and behavior
+     * specified by `builder`.
+     *
+     * # Failure
+     *
+     * When spawning into a new scheduler, the number of threads requested
+     * must be greater than zero.
+     */
 
     let body = builder.gen_body(f);
     spawn_raw(builder.opts, body);
@@ -271,17 +272,18 @@ fn run(-builder: builder, +f: fn~()) {
 /* Builder convenience functions */
 
 fn future_result(builder: builder) -> future::future<task_result> {
-    #[doc = "
-    Get a future representing the exit status of the task.
-
-    Taking the value of the future will block until the child task terminates.
-
-    Note that the future returning by this function is only useful for
-    obtaining the value of the next task to be spawning with the
-    builder. If additional tasks are spawned with the same builder
-    then a new result future must be obtained prior to spawning each
-    task.
-    "];
+    /*!
+     * Get a future representing the exit status of the task.
+     *
+     * Taking the value of the future will block until the child task
+     * terminates.
+     *
+     * Note that the future returning by this function is only useful for
+     * obtaining the value of the next task to be spawning with the
+     * builder. If additional tasks are spawned with the same builder
+     * then a new result future must be obtained prior to spawning each
+     * task.
+     */
 
     // FIXME (#1087, #1857): Once linked failure and notification are
     // handled in the library, I can imagine implementing this by just
@@ -304,7 +306,7 @@ fn future_result(builder: builder) -> future::future<task_result> {
 }
 
 fn future_task(builder: builder) -> future::future<task> {
-    #[doc = "Get a future representing the handle to the new task"];
+    //! Get a future representing the handle to the new task
 
     let mut po = comm::port();
     let ch = comm::chan(po);
@@ -318,7 +320,7 @@ fn future_task(builder: builder) -> future::future<task> {
 }
 
 fn unsupervise(builder: builder) {
-    #[doc = "Configures the new task to not propagate failure to its parent"];
+    //! Configures the new task to not propagate failure to its parent
 
     set_opts(builder, {
         supervise: false
@@ -328,17 +330,17 @@ fn unsupervise(builder: builder) {
 
 fn run_listener<A:send>(-builder: builder,
                         +f: fn~(comm::port<A>)) -> comm::chan<A> {
-    #[doc = "
-    Runs a new task while providing a channel from the parent to the child
-
-    Sets up a communication channel from the current task to the new
-    child task, passes the port to child's body, and returns a channel
-    linked to the port to the parent.
-
-    This encapsulates some boilerplate handshaking logic that would
-    otherwise be required to establish communication from the parent
-    to the child.
-    "];
+    /*!
+     * Runs a new task while providing a channel from the parent to the child
+     *
+     * Sets up a communication channel from the current task to the new
+     * child task, passes the port to child's body, and returns a channel
+     * linked to the port to the parent.
+     *
+     * This encapsulates some boilerplate handshaking logic that would
+     * otherwise be required to establish communication from the parent
+     * to the child.
+     */
 
     let setup_po = comm::port();
     let setup_ch = comm::chan(setup_po);
@@ -357,60 +359,60 @@ fn run_listener<A:send>(-builder: builder,
 /* Spawn convenience functions */
 
 fn spawn(+f: fn~()) {
-    #[doc = "
-    Creates and executes a new child task
-
-    Sets up a new task with its own call stack and schedules it to run
-    the provided unique closure.
-
-    This function is equivalent to `run(new_builder(), f)`.
-    "];
+    /*!
+     * Creates and executes a new child task
+     *
+     * Sets up a new task with its own call stack and schedules it to run
+     * the provided unique closure.
+     *
+     * This function is equivalent to `run(new_builder(), f)`.
+     */
 
     run(builder(), f);
 }
 
 fn spawn_listener<A:send>(+f: fn~(comm::port<A>)) -> comm::chan<A> {
-    #[doc = "
-    Runs a new task while providing a channel from the parent to the child
-
-    Sets up a communication channel from the current task to the new
-    child task, passes the port to child's body, and returns a channel
-    linked to the port to the parent.
-
-    This encapsulates some boilerplate handshaking logic that would
-    otherwise be required to establish communication from the parent
-    to the child.
-
-    The simplest way to establish bidirectional communication between
-    a parent in child is as follows:
-
-        let po = comm::port();
-        let ch = comm::chan(po);
-        let ch = spawn_listener {|po|
-            // Now the child has a port called 'po' to read from and
-            // an environment-captured channel called 'ch'.
-        };
-        // Likewise, the parent has both a 'po' and 'ch'
-
-    This function is equivalent to `run_listener(builder(), f)`.
-    "];
+    /*!
+     * Runs a new task while providing a channel from the parent to the child
+     *
+     * Sets up a communication channel from the current task to the new
+     * child task, passes the port to child's body, and returns a channel
+     * linked to the port to the parent.
+     *
+     * This encapsulates some boilerplate handshaking logic that would
+     * otherwise be required to establish communication from the parent
+     * to the child.
+     *
+     * The simplest way to establish bidirectional communication between
+     * a parent in child is as follows:
+     *
+     *     let po = comm::port();
+     *     let ch = comm::chan(po);
+     *     let ch = spawn_listener {|po|
+     *         // Now the child has a port called 'po' to read from and
+     *         // an environment-captured channel called 'ch'.
+     *     };
+     *     // Likewise, the parent has both a 'po' and 'ch'
+     *
+     * This function is equivalent to `run_listener(builder(), f)`.
+     */
 
     run_listener(builder(), f)
 }
 
 fn spawn_sched(mode: sched_mode, +f: fn~()) {
-    #[doc = "
-    Creates a new scheduler and executes a task on it
-
-    Tasks subsequently spawned by that task will also execute on
-    the new scheduler. When there are no more tasks to execute the
-    scheduler terminates.
-
-    # Failure
-
-    In manual threads mode the number of threads requested must be
-    greater than zero.
-    "];
+    /*!
+     * Creates a new scheduler and executes a task on it
+     *
+     * Tasks subsequently spawned by that task will also execute on
+     * the new scheduler. When there are no more tasks to execute the
+     * scheduler terminates.
+     *
+     * # Failure
+     *
+     * In manual threads mode the number of threads requested must be
+     * greater than zero.
+     */
 
     let mut builder = builder();
     set_opts(builder, {
@@ -424,16 +426,16 @@ fn spawn_sched(mode: sched_mode, +f: fn~()) {
 }
 
 fn try<T:send>(+f: fn~() -> T) -> result<T,()> {
-    #[doc = "
-    Execute a function in another task and return either the return value
-    of the function or result::err.
-
-    # Return value
-
-    If the function executed successfully then try returns result::ok
-    containing the value returned by the function. If the function fails
-    then try returns result::err containing nil.
-    "];
+    /*!
+     * Execute a function in another task and return either the return value
+     * of the function or result::err.
+     *
+     * # Return value
+     *
+     * If the function executed successfully then try returns result::ok
+     * containing the value returned by the function. If the function fails
+     * then try returns result::err containing nil.
+     */
 
     let po = comm::port();
     let ch = comm::chan(po);
@@ -453,7 +455,7 @@ fn try<T:send>(+f: fn~() -> T) -> result<T,()> {
 /* Lifecycle functions */
 
 fn yield() {
-    #[doc = "Yield control to the task scheduler"];
+    //! Yield control to the task scheduler
 
     let task_ = rustrt::rust_get_task();
     let mut killed = false;
@@ -464,31 +466,30 @@ fn yield() {
 }
 
 fn failing() -> bool {
-    #[doc = "True if the running task has failed"];
+    //! True if the running task has failed
 
     rustrt::rust_task_is_unwinding(rustrt::rust_get_task())
 }
 
 fn get_task() -> task {
-    #[doc = "Get a handle to the running task"];
+    //! Get a handle to the running task
 
     task(rustrt::get_task_id())
 }
 
-#[doc = "
-Temporarily make the task unkillable
-
-# Example
-
-    task::unkillable {||
-        // detach / yield / destroy must all be called together
-        rustrt::rust_port_detach(po);
-        // This must not result in the current task being killed
-        task::yield();
-        rustrt::rust_port_destroy(po);
-    }
-
-"]
+/**
+ * Temporarily make the task unkillable
+ *
+ * # Example
+ *
+ *     task::unkillable {||
+ *         // detach / yield / destroy must all be called together
+ *         rustrt::rust_port_detach(po);
+ *         // This must not result in the current task being killed
+ *         task::yield();
+ *         rustrt::rust_port_destroy(po);
+ *     }
+ */
 unsafe fn unkillable(f: fn()) {
     class allow_failure {
       let i: (); // since a class must have at least one field
@@ -596,14 +597,16 @@ fn spawn_raw(opts: task_opts, +f: fn~()) {
  * Casting 'Arcane Sight' reveals an overwhelming aura of Transmutation magic.
  ****************************************************************************/
 
-#[doc = "Indexes a task-local data slot. The function itself is used to
-automatically finalise stored values; also, its code pointer is used for
-comparison. Recommended use is to write an empty function for each desired
-task-local data slot (and use class destructors, instead of code inside the
-finaliser, if specific teardown is needed). DO NOT use multiple instantiations
-of a single polymorphic function to index data of different types; arbitrary
-type coercion is possible this way. The interface is safe as long as all key
-functions are monomorphic."]
+/**
+ * Indexes a task-local data slot. The function itself is used to
+ * automatically finalise stored values; also, its code pointer is used for
+ * comparison. Recommended use is to write an empty function for each desired
+ * task-local data slot (and use class destructors, instead of code inside the
+ * finaliser, if specific teardown is needed). DO NOT use multiple
+ * instantiations of a single polymorphic function to index data of different
+ * types; arbitrary type coercion is possible this way. The interface is safe
+ * as long as all key functions are monomorphic.
+ */
 type local_data_key<T> = fn@(+@T);
 
 // We use dvec because it's the best data structure in core. If TLS is used
@@ -741,23 +744,31 @@ unsafe fn local_modify<T>(task: *rust_task, key: local_data_key<T>,
 }
 
 /* Exported interface for task-local data (plus local_data_key above). */
-#[doc = "Remove a task-local data value from the table, returning the
-reference that was originally created to insert it."]
+/**
+ * Remove a task-local data value from the table, returning the
+ * reference that was originally created to insert it.
+ */
 unsafe fn local_data_pop<T>(key: local_data_key<T>) -> option<@T> {
     local_pop(rustrt::rust_get_task(), key)
 }
-#[doc = "Retrieve a task-local data value. It will also be kept alive in the
-table until explicitly removed."]
+/**
+ * Retrieve a task-local data value. It will also be kept alive in the
+ * table until explicitly removed.
+ */
 unsafe fn local_data_get<T>(key: local_data_key<T>) -> option<@T> {
     local_get(rustrt::rust_get_task(), key)
 }
-#[doc = "Store a value in task-local data. If this key already has a value,
-that value is overwritten (and its destructor is run)."]
+/**
+ * Store a value in task-local data. If this key already has a value,
+ * that value is overwritten (and its destructor is run).
+ */
 unsafe fn local_data_set<T>(key: local_data_key<T>, -data: @T) {
     local_set(rustrt::rust_get_task(), key, data)
 }
-#[doc = "Modify a task-local data value. If the function returns 'none', the
-data is removed (and its reference dropped)."]
+/**
+ * Modify a task-local data value. If the function returns 'none', the
+ * data is removed (and its reference dropped).
+ */
 unsafe fn local_data_modify<T>(key: local_data_key<T>,
                                modify_fn: fn(option<@T>) -> option<@T>) {
     local_modify(rustrt::rust_get_task(), key, modify_fn)
diff --git a/src/libcore/tuple.rs b/src/libcore/tuple.rs
index 98840dadc11..d50ee4ac687 100644
--- a/src/libcore/tuple.rs
+++ b/src/libcore/tuple.rs
@@ -1,18 +1,18 @@
-#[doc = "Operations on tuples"];
+//! Operations on tuples
 
-#[doc = "Return the first element of a pair"]
+/// Return the first element of a pair
 pure fn first<T:copy, U:copy>(pair: (T, U)) -> T {
     let (t, _) = pair;
     ret t;
 }
 
-#[doc = "Return the second element of a pair"]
+/// Return the second element of a pair
 pure fn second<T:copy, U:copy>(pair: (T, U)) -> U {
     let (_, u) = pair;
     ret u;
 }
 
-#[doc = "Return the results of swapping the two elements of a pair"]
+/// Return the results of swapping the two elements of a pair
 pure fn swap<T:copy, U:copy>(pair: (T, U)) -> (U, T) {
     let (t, u) = pair;
     ret (u, t);
diff --git a/src/libcore/uint-template.rs b/src/libcore/uint-template.rs
index 7f4ffe97c01..91b9eb856e4 100644
--- a/src/libcore/uint-template.rs
+++ b/src/libcore/uint-template.rs
@@ -38,7 +38,7 @@ pure fn is_nonpositive(x: T) -> bool { x <= 0 as T }
 pure fn is_nonnegative(x: T) -> bool { x >= 0 as T }
 
 #[inline(always)]
-#[doc = "Iterate over the range [`lo`..`hi`)"]
+/// Iterate over the range [`lo`..`hi`)
 fn range(lo: T, hi: T, it: fn(T) -> bool) {
     let mut i = lo;
     while i < hi {
@@ -47,7 +47,7 @@ fn range(lo: T, hi: T, it: fn(T) -> bool) {
     }
 }
 
-#[doc = "Computes the bitwise complement"]
+/// Computes the bitwise complement
 pure fn compl(i: T) -> T {
     max_value ^ i
 }
@@ -76,18 +76,18 @@ impl num of num::num for T {
     fn from_int(n: int) -> T   { ret n as T;      }
 }
 
-#[doc = "
-Parse a buffer of bytes
-
-# Arguments
-
-* buf - A byte buffer
-* radix - The base of the number
-
-# Failure
-
-`buf` must not be empty
-"]
+/**
+ * Parse a buffer of bytes
+ *
+ * # Arguments
+ *
+ * * buf - A byte buffer
+ * * radix - The base of the number
+ *
+ * # Failure
+ *
+ * `buf` must not be empty
+ */
 fn parse_buf(buf: ~[u8], radix: uint) -> option<T> {
     if vec::len(buf) == 0u { ret none; }
     let mut i = vec::len(buf) - 1u;
@@ -104,10 +104,10 @@ fn parse_buf(buf: ~[u8], radix: uint) -> option<T> {
     };
 }
 
-#[doc = "Parse a string to an int"]
+/// Parse a string to an int
 fn from_str(s: str) -> option<T> { parse_buf(str::bytes(s), 10u) }
 
-#[doc = "Parse a string as an unsigned integer."]
+/// Parse a string as an unsigned integer.
 fn from_str_radix(buf: str, radix: u64) -> option<u64> {
     if str::len(buf) == 0u { ret none; }
     let mut i = str::len(buf) - 1u;
@@ -123,13 +123,13 @@ fn from_str_radix(buf: str, radix: u64) -> option<u64> {
     };
 }
 
-#[doc = "
-Convert to a string in a given base
-
-# Failure
-
-Fails if `radix` < 2 or `radix` > 16
-"]
+/**
+ * Convert to a string in a given base
+ *
+ * # Failure
+ *
+ * Fails if `radix` < 2 or `radix` > 16
+ */
 fn to_str(num: T, radix: uint) -> str {
     do to_str_bytes(false, num, radix) |slice| {
         do vec::unpack_slice(slice) |p, len| {
@@ -138,7 +138,7 @@ fn to_str(num: T, radix: uint) -> str {
     }
 }
 
-#[doc = "Low-level helper routine for string conversion."]
+/// Low-level helper routine for string conversion.
 fn to_str_bytes<U>(neg: bool, num: T, radix: uint,
                    f: fn(v: &[u8]) -> U) -> U {
 
@@ -203,7 +203,7 @@ fn to_str_bytes<U>(neg: bool, num: T, radix: uint,
     }
 }
 
-#[doc = "Convert to a string"]
+/// Convert to a string
 fn str(i: T) -> str { ret to_str(i, 10u); }
 
 #[test]
diff --git a/src/libcore/uint-template/uint.rs b/src/libcore/uint-template/uint.rs
index 843215bd4b9..19d0a3e9e45 100644
--- a/src/libcore/uint-template/uint.rs
+++ b/src/libcore/uint-template/uint.rs
@@ -1,76 +1,76 @@
 type T = uint;
 
-#[doc = "
-Divide two numbers, return the result, rounded up.
-
-# Arguments
-
-* x - an integer
-* y - an integer distinct from 0u
-
-# Return value
-
-The smallest integer `q` such that `x/y <= q`.
-"]
+/**
+ * Divide two numbers, return the result, rounded up.
+ *
+ * # Arguments
+ *
+ * * x - an integer
+ * * y - an integer distinct from 0u
+ *
+ * # Return value
+ *
+ * The smallest integer `q` such that `x/y <= q`.
+ */
 pure fn div_ceil(x: uint, y: uint) -> uint {
     let div = div(x, y);
     if x % y == 0u { ret div;}
     else { ret div + 1u; }
 }
 
-#[doc = "
-Divide two numbers, return the result, rounded to the closest integer.
-
-# Arguments
-
-* x - an integer
-* y - an integer distinct from 0u
-
-# Return value
-
-The integer `q` closest to `x/y`.
-"]
+/**
+ * Divide two numbers, return the result, rounded to the closest integer.
+ *
+ * # Arguments
+ *
+ * * x - an integer
+ * * y - an integer distinct from 0u
+ *
+ * # Return value
+ *
+ * The integer `q` closest to `x/y`.
+ */
 pure fn div_round(x: uint, y: uint) -> uint {
     let div = div(x, y);
     if x % y * 2u  < y { ret div;}
     else { ret div + 1u; }
 }
 
-#[doc = "
-Divide two numbers, return the result, rounded down.
-
-Note: This is the same function as `div`.
-
-# Arguments
-
-* x - an integer
-* y - an integer distinct from 0u
-
-# Return value
-
-The smallest integer `q` such that `x/y <= q`. This
-is either `x/y` or `x/y + 1`.
-"]
+/**
+ * Divide two numbers, return the result, rounded down.
+ *
+ * Note: This is the same function as `div`.
+ *
+ * # Arguments
+ *
+ * * x - an integer
+ * * y - an integer distinct from 0u
+ *
+ * # Return value
+ *
+ * The smallest integer `q` such that `x/y <= q`. This
+ * is either `x/y` or `x/y + 1`.
+ */
 pure fn div_floor(x: uint, y: uint) -> uint { ret x / y; }
 
-#[doc = "Produce a uint suitable for use in a hash table"]
+/// Produce a uint suitable for use in a hash table
 pure fn hash(&&x: uint) -> uint { ret x; }
 
-#[doc = "
-Iterate over the range [`lo`..`hi`), or stop when requested
-
-# Arguments
-
-* lo - The integer at which to start the loop (included)
-* hi - The integer at which to stop the loop (excluded)
-* it - A block to execute with each consecutive integer of the range.
-       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.
-"]
+/**
+ * Iterate over the range [`lo`..`hi`), or stop when requested
+ *
+ * # Arguments
+ *
+ * * lo - The integer at which to start the loop (included)
+ * * hi - The integer at which to stop the loop (excluded)
+ * * it - A block to execute with each consecutive integer of the range.
+ *        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 iterate(lo: uint, hi: uint, it: fn(uint) -> bool) -> bool {
     let mut i = lo;
     while i < hi {
@@ -80,7 +80,7 @@ fn iterate(lo: uint, hi: uint, it: fn(uint) -> bool) -> bool {
     ret true;
 }
 
-#[doc = "Returns the smallest power of 2 greater than or equal to `n`"]
+/// Returns the smallest power of 2 greater than or equal to `n`
 #[inline(always)]
 fn next_power_of_two(n: uint) -> uint {
     let halfbits: uint = sys::size_of::<uint>() * 4u;
diff --git a/src/libcore/unicode.rs b/src/libcore/unicode.rs
index de120b8cc78..716a59f8ea9 100644
--- a/src/libcore/unicode.rs
+++ b/src/libcore/unicode.rs
@@ -2565,7 +2565,7 @@ mod general_category {
 
 }
 mod derived_property {
-    #[doc = "Check if a character has the alphabetic unicode property"]
+    /// Check if a character has the alphabetic unicode property
     pure fn Alphabetic(c: char) -> bool {
         ret alt c {
               '\x41' to '\x5a'
diff --git a/src/libcore/unsafe.rs b/src/libcore/unsafe.rs
index a4e4c4fe166..ad7017444dd 100644
--- a/src/libcore/unsafe.rs
+++ b/src/libcore/unsafe.rs
@@ -1,4 +1,4 @@
-#[doc = "Unsafe operations"];
+//! Unsafe operations
 
 export reinterpret_cast, forget, bump_box_refcount, transmute;
 
@@ -8,39 +8,39 @@ extern mod rusti {
     fn reinterpret_cast<T, U>(e: T) -> U;
 }
 
-#[doc = "
-Casts the value at `src` to U. The two types must have the same length.
-"]
+/// Casts the value at `src` to U. The two types must have the same length.
 #[inline(always)]
 unsafe fn reinterpret_cast<T, U>(src: T) -> U {
     rusti::reinterpret_cast(src)
 }
 
-#[doc ="
-Move a thing into the void
-
-The forget function will take ownership of the provided value but neglect
-to run any required cleanup or memory-management operations on it. This
-can be used for various acts of magick, particularly when using
-reinterpret_cast on managed pointer types.
-"]
+/**
+ * Move a thing into the void
+ *
+ * The forget function will take ownership of the provided value but neglect
+ * to run any required cleanup or memory-management operations on it. This
+ * can be used for various acts of magick, particularly when using
+ * reinterpret_cast on managed pointer types.
+ */
 #[inline(always)]
 unsafe fn forget<T>(-thing: T) { rusti::forget(thing); }
 
-#[doc = "Force-increment the reference count on a shared box. If used
-uncarefully, this can leak the box. Use this in conjunction with transmute
-and/or reinterpret_cast when such calls would otherwise scramble a box's
-reference count"]
+/**
+ * Force-increment the reference count on a shared box. If used
+ * uncarefully, this can leak the box. Use this in conjunction with transmute
+ * and/or reinterpret_cast when such calls would otherwise scramble a box's
+ * reference count
+ */
 unsafe fn bump_box_refcount<T>(+t: @T) { forget(t); }
 
-#[doc = "
-Transform a value of one type into a value of another type.
-Both types must have the same size and alignment.
-
-# Example
-
-    assert transmute(\"L\") == [76u8, 0u8]/~;
-"]
+/**
+ * Transform a value of one type into a value of another type.
+ * Both types must have the same size and alignment.
+ *
+ * # Example
+ *
+ *     assert transmute("L") == [76u8, 0u8]/~;
+ */
 unsafe fn transmute<L, G>(-thing: L) -> G {
     let newthing = reinterpret_cast(thing);
     forget(thing);
diff --git a/src/libcore/vec.rs b/src/libcore/vec.rs
index 81039ec5521..895377170bc 100644
--- a/src/libcore/vec.rs
+++ b/src/libcore/vec.rs
@@ -1,4 +1,4 @@
-#[doc = "Vectors"];
+//! Vectors
 
 import option::{some, none};
 import ptr::addr_of;
@@ -99,35 +99,35 @@ extern mod rusti {
     fn move_val_init<T>(&dst: T, -src: T);
 }
 
-#[doc = "A function used to initialize the elements of a vector"]
+/// A function used to initialize the elements of a vector
 type init_op<T> = fn(uint) -> T;
 
-#[doc = "Returns true if a vector contains no elements"]
+/// Returns true if a vector contains no elements
 pure fn is_empty<T>(v: &[const T]) -> bool {
     unpack_const_slice(v, |_p, len| len == 0u)
 }
 
-#[doc = "Returns true if a vector contains some elements"]
+/// Returns true if a vector contains some elements
 pure fn is_not_empty<T>(v: &[const T]) -> bool {
     unpack_const_slice(v, |_p, len| len > 0u)
 }
 
-#[doc = "Returns true if two vectors have the same length"]
+/// Returns true if two vectors have the same length
 pure fn same_length<T, U>(xs: &[const T], ys: &[const U]) -> bool {
     len(xs) == len(ys)
 }
 
-#[doc = "
-Reserves capacity for exactly `n` elements in the given vector.
-
-If the capacity for `v` is already equal to or greater than the requested
-capacity, then no action is taken.
-
-# Arguments
-
-* v - A vector
-* n - The number of elements to reserve space for
-"]
+/**
+ * Reserves capacity for exactly `n` elements in the given vector.
+ *
+ * If the capacity for `v` is already equal to or greater than the requested
+ * capacity, then no action is taken.
+ *
+ * # Arguments
+ *
+ * * v - A vector
+ * * n - The number of elements to reserve space for
+ */
 fn reserve<T>(&v: ~[const T], n: uint) {
     // Only make the (slow) call into the runtime if we have to
     if capacity(v) < n {
@@ -137,28 +137,26 @@ fn reserve<T>(&v: ~[const T], n: uint) {
     }
 }
 
-#[doc = "
-Reserves capacity for at least `n` elements in the given vector.
-
-This function will over-allocate in order to amortize the allocation costs
-in scenarios where the caller may need to repeatedly reserve additional
-space.
-
-If the capacity for `v` is already equal to or greater than the requested
-capacity, then no action is taken.
-
-# Arguments
-
-* v - A vector
-* n - The number of elements to reserve space for
-"]
+/**
+ * Reserves capacity for at least `n` elements in the given vector.
+ *
+ * This function will over-allocate in order to amortize the allocation costs
+ * in scenarios where the caller may need to repeatedly reserve additional
+ * space.
+ *
+ * If the capacity for `v` is already equal to or greater than the requested
+ * capacity, then no action is taken.
+ *
+ * # Arguments
+ *
+ * * v - A vector
+ * * n - The number of elements to reserve space for
+ */
 fn reserve_at_least<T>(&v: ~[const T], n: uint) {
     reserve(v, uint::next_power_of_two(n));
 }
 
-#[doc = "
-Returns the number of elements the vector can hold without reallocating
-"]
+/// Returns the number of elements the vector can hold without reallocating
 #[inline(always)]
 pure fn capacity<T>(&&v: ~[const T]) -> uint {
     unsafe {
@@ -167,18 +165,18 @@ pure fn capacity<T>(&&v: ~[const T]) -> uint {
     }
 }
 
-#[doc = "Returns the length of a vector"]
+/// Returns the length of a vector
 #[inline(always)]
 pure fn len<T>(&&v: &[const T]) -> uint {
     unpack_const_slice(v, |_p, len| len)
 }
 
-#[doc = "
-Creates and initializes an immutable vector.
-
-Creates an immutable vector of size `n_elts` and initializes the elements
-to the value returned by the function `op`.
-"]
+/**
+ * Creates and initializes an immutable vector.
+ *
+ * Creates an immutable vector of size `n_elts` and initializes the elements
+ * to the value returned by the function `op`.
+ */
 pure fn from_fn<T>(n_elts: uint, op: init_op<T>) -> ~[T] {
     let mut v = ~[];
     unchecked{reserve(v, n_elts);}
@@ -187,12 +185,12 @@ pure fn from_fn<T>(n_elts: uint, op: init_op<T>) -> ~[T] {
     ret v;
 }
 
-#[doc = "
-Creates and initializes an immutable vector.
-
-Creates an immutable vector of size `n_elts` and initializes the elements
-to the value `t`.
-"]
+/**
+ * Creates and initializes an immutable vector.
+ *
+ * Creates an immutable vector of size `n_elts` and initializes the elements
+ * to the value `t`.
+ */
 pure fn from_elem<T: copy>(n_elts: uint, t: T) -> ~[T] {
     let mut v = ~[];
     unchecked{reserve(v, n_elts)}
@@ -203,56 +201,56 @@ pure fn from_elem<T: copy>(n_elts: uint, t: T) -> ~[T] {
     ret v;
 }
 
-#[doc = "Produces a mut vector from an immutable vector."]
+/// Produces a mut vector from an immutable vector.
 fn to_mut<T>(+v: ~[T]) -> ~[mut T] {
     unsafe { ::unsafe::transmute(v) }
 }
 
-#[doc = "Produces an immutable vector from a mut vector."]
+/// Produces an immutable vector from a mut vector.
 fn from_mut<T>(+v: ~[mut T]) -> ~[T] {
     unsafe { ::unsafe::transmute(v) }
 }
 
 // Accessors
 
-#[doc = "Returns the first element of a vector"]
+/// Returns the first element of a vector
 pure fn head<T: copy>(v: &[const T]) -> T { v[0] }
 
-#[doc = "Returns a vector containing all but the first element of a slice"]
+/// Returns a vector containing all but the first element of a slice
 pure fn tail<T: copy>(v: &[const T]) -> ~[T] {
     ret slice(v, 1u, len(v));
 }
 
-#[doc = "Returns a vector containing all but the first `n` \
-         elements of a slice"]
+/**
+ * Returns a vector containing all but the first `n` \
+ * elements of a slice
+ */
 pure fn tailn<T: copy>(v: &[const T], n: uint) -> ~[T] {
     slice(v, n, len(v))
 }
 
-#[doc = "Returns a vector containing all but the last element of a slice"]
+/// Returns a vector containing all but the last element of a slice
 pure fn init<T: copy>(v: &[const T]) -> ~[T] {
     assert len(v) != 0u;
     slice(v, 0u, len(v) - 1u)
 }
 
-#[doc = "
-Returns the last element of the slice `v`, failing if the slice is empty.
-"]
+/// Returns the last element of the slice `v`, failing if the slice is empty.
 pure fn last<T: copy>(v: &[const T]) -> T {
     if len(v) == 0u { fail "last_unsafe: empty vector" }
     v[len(v) - 1u]
 }
 
-#[doc = "
-Returns `some(x)` where `x` is the last element of the slice `v`,
-or `none` if the vector is empty.
-"]
+/**
+ * Returns `some(x)` where `x` is the last element of the slice `v`,
+ * or `none` if the vector is empty.
+ */
 pure fn last_opt<T: copy>(v: &[const T]) -> option<T> {
     if len(v) == 0u { ret none; }
     some(v[len(v) - 1u])
 }
 
-#[doc = "Returns a copy of the elements from [`start`..`end`) from `v`."]
+/// Returns a copy of the elements from [`start`..`end`) from `v`.
 pure fn slice<T: copy>(v: &[const T], start: uint, end: uint) -> ~[T] {
     assert (start <= end);
     assert (end <= len(v));
@@ -263,7 +261,7 @@ pure fn slice<T: copy>(v: &[const T], start: uint, end: uint) -> ~[T] {
     ret result;
 }
 
-#[doc = "Return a slice that points into another slice."]
+/// Return a slice that points into another slice.
 pure fn view<T: copy>(v: &[const T], start: uint, end: uint) -> &a.[T] {
     assert (start <= end);
     assert (end <= len(v));
@@ -275,9 +273,7 @@ pure fn view<T: copy>(v: &[const T], start: uint, end: uint) -> &a.[T] {
     }
 }
 
-#[doc = "
-Split the vector `v` by applying each element against the predicate `f`.
-"]
+/// Split the vector `v` by applying each element against the predicate `f`.
 fn split<T: copy>(v: &[T], f: fn(T) -> bool) -> ~[~[T]] {
     let ln = len(v);
     if (ln == 0u) { ret ~[] }
@@ -297,10 +293,10 @@ fn split<T: copy>(v: &[T], f: fn(T) -> bool) -> ~[~[T]] {
     result
 }
 
-#[doc = "
-Split the vector `v` by applying each element against the predicate `f` up
-to `n` times.
-"]
+/**
+ * Split the vector `v` by applying each element against the predicate `f` up
+ * to `n` times.
+ */
 fn splitn<T: copy>(v: &[T], n: uint, f: fn(T) -> bool) -> ~[~[T]] {
     let ln = len(v);
     if (ln == 0u) { ret ~[] }
@@ -323,10 +319,10 @@ fn splitn<T: copy>(v: &[T], n: uint, f: fn(T) -> bool) -> ~[~[T]] {
     result
 }
 
-#[doc = "
-Reverse split the vector `v` by applying each element against the predicate
-`f`.
-"]
+/**
+ * Reverse split the vector `v` by applying each element against the predicate
+ * `f`.
+ */
 fn rsplit<T: copy>(v: &[T], f: fn(T) -> bool) -> ~[~[T]] {
     let ln = len(v);
     if (ln == 0u) { ret ~[] }
@@ -346,10 +342,10 @@ fn rsplit<T: copy>(v: &[T], f: fn(T) -> bool) -> ~[~[T]] {
     reversed(result)
 }
 
-#[doc = "
-Reverse split the vector `v` by applying each element against the predicate
-`f` up to `n times.
-"]
+/**
+ * Reverse split the vector `v` by applying each element against the predicate
+ * `f` up to `n times.
+ */
 fn rsplitn<T: copy>(v: &[T], n: uint, f: fn(T) -> bool) -> ~[~[T]] {
     let ln = len(v);
     if (ln == 0u) { ret ~[] }
@@ -374,7 +370,7 @@ fn rsplitn<T: copy>(v: &[T], n: uint, f: fn(T) -> bool) -> ~[~[T]] {
 
 // Mutators
 
-#[doc = "Removes the first element from a vector and return it"]
+/// Removes the first element from a vector and return it
 fn shift<T>(&v: ~[T]) -> T {
     let ln = len::<T>(v);
     assert (ln > 0u);
@@ -399,7 +395,7 @@ fn shift<T>(&v: ~[T]) -> T {
     }
 }
 
-#[doc = "Prepend an element to the vector"]
+/// Prepend an element to the vector
 fn unshift<T>(&v: ~[T], +x: T) {
     let mut vv = ~[x];
     v <-> vv;
@@ -408,7 +404,7 @@ fn unshift<T>(&v: ~[T], +x: T) {
     }
 }
 
-#[doc = "Remove the last element from a vector and return it"]
+/// Remove the last element from a vector and return it
 fn pop<T>(&v: ~[const T]) -> T {
     let ln = len(v);
     assert ln > 0u;
@@ -420,7 +416,7 @@ fn pop<T>(&v: ~[const T]) -> T {
     }
 }
 
-#[doc = "Append an element to a vector"]
+/// Append an element to a vector
 #[inline(always)]
 fn push<T>(&v: ~[const T], +initval: T) {
     unsafe {
@@ -519,15 +515,15 @@ pure fn append_mut<T: copy>(lhs: &[mut T], rhs: &[const T]) -> ~[mut T] {
     ret v;
 }
 
-#[doc = "
-Expands a vector in place, initializing the new elements to a given value
-
-# Arguments
-
-* v - The vector to grow
-* n - The number of elements to add
-* initval - The value for the new elements
-"]
+/**
+ * Expands a vector in place, initializing the new elements to a given value
+ *
+ * # Arguments
+ *
+ * * v - The vector to grow
+ * * n - The number of elements to add
+ * * initval - The value for the new elements
+ */
 fn grow<T: copy>(&v: ~[const T], n: uint, initval: T) {
     reserve_at_least(v, len(v) + n);
     let mut i: uint = 0u;
@@ -535,33 +531,33 @@ fn grow<T: copy>(&v: ~[const T], n: uint, initval: T) {
     while i < n { push(v, initval); i += 1u; }
 }
 
-#[doc = "
-Expands a vector in place, initializing the new elements to the result of
-a function
-
-Function `init_op` is called `n` times with the values [0..`n`)
-
-# Arguments
-
-* v - The vector to grow
-* n - The number of elements to add
-* init_op - A function to call to retreive each appended element's
-            value
-"]
+/**
+ * Expands a vector in place, initializing the new elements to the result of
+ * a function
+ *
+ * Function `init_op` is called `n` times with the values [0..`n`)
+ *
+ * # Arguments
+ *
+ * * v - The vector to grow
+ * * n - The number of elements to add
+ * * init_op - A function to call to retreive each appended element's
+ *             value
+ */
 fn grow_fn<T>(&v: ~[const T], n: uint, op: init_op<T>) {
     reserve_at_least(v, len(v) + n);
     let mut i: uint = 0u;
     while i < n { push(v, op(i)); i += 1u; }
 }
 
-#[doc = "
-Sets the value of a vector element at a given index, growing the vector as
-needed
-
-Sets the element at position `index` to `val`. If `index` is past the end
-of the vector, expands the vector by replicating `initval` to fill the
-intervening space.
-"]
+/**
+ * Sets the value of a vector element at a given index, growing the vector as
+ * needed
+ *
+ * Sets the element at position `index` to `val`. If `index` is past the end
+ * of the vector, expands the vector by replicating `initval` to fill the
+ * intervening space.
+ */
 #[inline(always)]
 fn grow_set<T: copy>(&v: ~[mut T], index: uint, initval: T, val: T) {
     if index >= len(v) { grow(v, index - len(v) + 1u, initval); }
@@ -571,9 +567,7 @@ fn grow_set<T: copy>(&v: ~[mut T], index: uint, initval: T, val: T) {
 
 // Functional utilities
 
-#[doc = "
-Apply a function to each element of a vector and return the results
-"]
+/// Apply a function to each element of a vector and return the results
 pure fn map<T, U>(v: &[T], f: fn(T) -> U) -> ~[U] {
     let mut result = ~[];
     unchecked{reserve(result, len(v));}
@@ -581,9 +575,7 @@ pure fn map<T, U>(v: &[T], f: fn(T) -> U) -> ~[U] {
     ret result;
 }
 
-#[doc = "
-Apply a function to each element of a vector and return the results
-"]
+/// Apply a function to each element of a vector and return the results
 pure fn mapi<T, U>(v: &[T], f: fn(uint, T) -> U) -> ~[U] {
     let mut result = ~[];
     unchecked{reserve(result, len(v));}
@@ -591,19 +583,17 @@ pure fn mapi<T, U>(v: &[T], f: fn(uint, T) -> U) -> ~[U] {
     ret result;
 }
 
-#[doc = "
-Apply a function to each element of a vector and return a concatenation
-of each result vector
-"]
+/**
+ * Apply a function to each element of a vector and return a concatenation
+ * of each result vector
+ */
 pure fn flat_map<T, U>(v: &[T], f: fn(T) -> ~[U]) -> ~[U] {
     let mut result = ~[];
     for each(v) |elem| { unchecked{ push_all_move(result, f(elem)); } }
     ret result;
 }
 
-#[doc = "
-Apply a function to each pair of elements and return the results
-"]
+/// Apply a function to each pair of elements and return the results
 pure fn map2<T: copy, U: copy, V>(v0: &[T], v1: &[U],
                                   f: fn(T, U) -> V) -> ~[V] {
     let v0_len = len(v0);
@@ -617,12 +607,12 @@ pure fn map2<T: copy, U: copy, V>(v0: &[T], v1: &[U],
     ret u;
 }
 
-#[doc = "
-Apply a function to each element of a vector and return the results
-
-If function `f` returns `none` then that element is excluded from
-the resulting vector.
-"]
+/**
+ * Apply a function to each element of a vector and return the results
+ *
+ * If function `f` returns `none` then that element is excluded from
+ * the resulting vector.
+ */
 pure fn filter_map<T, U: copy>(v: &[T], f: fn(T) -> option<U>)
     -> ~[U] {
     let mut result = ~[];
@@ -635,13 +625,13 @@ pure fn filter_map<T, U: copy>(v: &[T], f: fn(T) -> option<U>)
     ret result;
 }
 
-#[doc = "
-Construct a new vector from the elements of a vector for which some predicate
-holds.
-
-Apply function `f` to each element of `v` and return a vector containing
-only those elements for which `f` returned true.
-"]
+/**
+ * Construct a new vector from the elements of a vector for which some
+ * predicate holds.
+ *
+ * Apply function `f` to each element of `v` and return a vector containing
+ * only those elements for which `f` returned true.
+ */
 pure fn filter<T: copy>(v: &[T], f: fn(T) -> bool) -> ~[T] {
     let mut result = ~[];
     for each(v) |elem| {
@@ -650,20 +640,18 @@ pure fn filter<T: copy>(v: &[T], f: fn(T) -> bool) -> ~[T] {
     ret result;
 }
 
-#[doc = "
-Concatenate a vector of vectors.
-
-Flattens a vector of vectors of T into a single vector of T.
-"]
+/**
+ * Concatenate a vector of vectors.
+ *
+ * Flattens a vector of vectors of T into a single vector of T.
+ */
 pure fn concat<T: copy>(v: &[[T]/~]) -> ~[T] {
     let mut r = ~[];
     for each(v) |inner| { unsafe { push_all(r, inner); } }
     ret r;
 }
 
-#[doc = "
-Concatenate a vector of vectors, placing a given separator between each
-"]
+/// Concatenate a vector of vectors, placing a given separator between each
 pure fn connect<T: copy>(v: &[[T]/~], sep: T) -> ~[T] {
     let mut r: ~[T] = ~[];
     let mut first = true;
@@ -674,7 +662,7 @@ pure fn connect<T: copy>(v: &[[T]/~], sep: T) -> ~[T] {
     ret r;
 }
 
-#[doc = "Reduce a vector from left to right"]
+/// Reduce a vector from left to right
 pure fn foldl<T: copy, U>(z: T, v: &[U], p: fn(T, U) -> T) -> T {
     let mut accum = z;
     do iter(v) |elt| {
@@ -683,7 +671,7 @@ pure fn foldl<T: copy, U>(z: T, v: &[U], p: fn(T, U) -> T) -> T {
     ret accum;
 }
 
-#[doc = "Reduce a vector from right to left"]
+/// Reduce a vector from right to left
 pure fn foldr<T, U: copy>(v: &[T], z: U, p: fn(T, U) -> U) -> U {
     let mut accum = z;
     do riter(v) |elt| {
@@ -692,21 +680,21 @@ pure fn foldr<T, U: copy>(v: &[T], z: U, p: fn(T, U) -> U) -> U {
     ret accum;
 }
 
-#[doc = "
-Return true if a predicate matches any elements
-
-If the vector contains no elements then false is returned.
-"]
+/**
+ * Return true if a predicate matches any elements
+ *
+ * If the vector contains no elements then false is returned.
+ */
 pure fn any<T>(v: &[T], f: fn(T) -> bool) -> bool {
     for each(v) |elem| { if f(elem) { ret true; } }
     ret false;
 }
 
-#[doc = "
-Return true if a predicate matches any elements in both vectors.
-
-If the vectors contains no elements then false is returned.
-"]
+/**
+ * Return true if a predicate matches any elements in both vectors.
+ *
+ * If the vectors contains no elements then false is returned.
+ */
 pure fn any2<T, U>(v0: &[T], v1: &[U],
                    f: fn(T, U) -> bool) -> bool {
     let v0_len = len(v0);
@@ -719,31 +707,31 @@ pure fn any2<T, U>(v0: &[T], v1: &[U],
     ret false;
 }
 
-#[doc = "
-Return true if a predicate matches all elements
-
-If the vector contains no elements then true is returned.
-"]
+/**
+ * Return true if a predicate matches all elements
+ *
+ * If the vector contains no elements then true is returned.
+ */
 pure fn all<T>(v: &[T], f: fn(T) -> bool) -> bool {
     for each(v) |elem| { if !f(elem) { ret false; } }
     ret true;
 }
 
-#[doc = "
-Return true if a predicate matches all elements
-
-If the vector contains no elements then true is returned.
-"]
+/**
+ * Return true if a predicate matches all elements
+ *
+ * If the vector contains no elements then true is returned.
+ */
 pure fn alli<T>(v: &[T], f: fn(uint, T) -> bool) -> bool {
     for eachi(v) |i, elem| { if !f(i, elem) { ret false; } }
     ret true;
 }
 
-#[doc = "
-Return true if a predicate matches all elements in both vectors.
-
-If the vectors are not the same size then false is returned.
-"]
+/**
+ * Return true if a predicate matches all elements in both vectors.
+ *
+ * If the vectors are not the same size then false is returned.
+ */
 pure fn all2<T, U>(v0: &[T], v1: &[U],
                    f: fn(T, U) -> bool) -> bool {
     let v0_len = len(v0);
@@ -753,88 +741,88 @@ pure fn all2<T, U>(v0: &[T], v1: &[U],
     ret true;
 }
 
-#[doc = "Return true if a vector contains an element with the given value"]
+/// Return true if a vector contains an element with the given value
 pure fn contains<T>(v: &[T], x: T) -> bool {
     for each(v) |elt| { if x == elt { ret true; } }
     ret false;
 }
 
-#[doc = "Returns the number of elements that are equal to a given value"]
+/// Returns the number of elements that are equal to a given value
 pure fn count<T>(v: &[T], x: T) -> uint {
     let mut cnt = 0u;
     for each(v) |elt| { if x == elt { cnt += 1u; } }
     ret cnt;
 }
 
-#[doc = "
-Search for the first 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 the first 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.
+ */
 pure fn find<T: copy>(v: &[T], f: fn(T) -> bool) -> option<T> {
     find_between(v, 0u, len(v), f)
 }
 
-#[doc = "
-Search for the first element that matches a given predicate within a range
-
-Apply function `f` to each element of `v` within the range [`start`, `end`).
-When function `f` returns true then an option containing the element
-is returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Search for the first element that matches a given predicate within a range
+ *
+ * Apply function `f` to each element of `v` within the range
+ * [`start`, `end`). When function `f` returns true then an option containing
+ * the element is returned. If `f` matches no elements then none is returned.
+ */
 pure fn find_between<T: copy>(v: &[T], start: uint, end: uint,
                       f: fn(T) -> bool) -> option<T> {
     option::map(position_between(v, start, end, f), |i| v[i])
 }
 
-#[doc = "
-Search for the last element that matches a given predicate
-
-Apply function `f` to each element of `v` in reverse order. When function `f`
-returns true then an option containing the element is returned. If `f`
-matches no elements then none is returned.
-"]
+/**
+ * Search for the last element that matches a given predicate
+ *
+ * Apply function `f` to each element of `v` in reverse order. When function
+ * `f` returns true then an option containing the element is returned. If `f`
+ * matches no elements then none is returned.
+ */
 pure fn rfind<T: copy>(v: &[T], f: fn(T) -> bool) -> option<T> {
     rfind_between(v, 0u, len(v), f)
 }
 
-#[doc = "
-Search for the last element that matches a given predicate within a range
-
-Apply function `f` to each element of `v` in reverse order within the range
-[`start`, `end`). When function `f` returns true then an option containing
-the element is returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Search for the last element that matches a given predicate within a range
+ *
+ * Apply function `f` to each element of `v` in reverse order within the range
+ * [`start`, `end`). When function `f` returns true then an option containing
+ * the element is returned. If `f` matches no elements then none is returned.
+ */
 pure fn rfind_between<T: copy>(v: &[T], start: uint, end: uint,
                                f: fn(T) -> bool) -> option<T> {
     option::map(rposition_between(v, start, end, f), |i| v[i])
 }
 
-#[doc = "Find the first index containing a matching value"]
+/// Find the first index containing a matching value
 pure fn position_elem<T>(v: &[T], x: T) -> option<uint> {
     position(v, |y| x == y)
 }
 
-#[doc = "
-Find the first index matching some predicate
-
-Apply function `f` to each element of `v`.  When function `f` returns true
-then an option containing the index is returned. If `f` matches no elements
-then none is returned.
-"]
+/**
+ * Find the first index matching some predicate
+ *
+ * Apply function `f` to each element of `v`.  When function `f` returns true
+ * then an option containing the index is returned. If `f` matches no elements
+ * then none is returned.
+ */
 pure fn position<T>(v: &[T], f: fn(T) -> bool) -> option<uint> {
     position_between(v, 0u, len(v), f)
 }
 
-#[doc = "
-Find the first index matching some predicate within a range
-
-Apply function `f` to each element of `v` between the range [`start`, `end`).
-When function `f` returns true then an option containing the index is
-returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Find the first index matching some predicate within a range
+ *
+ * Apply function `f` to each element of `v` between the range
+ * [`start`, `end`). When function `f` returns true then an option containing
+ * the index is returned. If `f` matches no elements then none is returned.
+ */
 pure fn position_between<T>(v: &[T], start: uint, end: uint,
                             f: fn(T) -> bool) -> option<uint> {
     assert start <= end;
@@ -844,29 +832,30 @@ pure fn position_between<T>(v: &[T], start: uint, end: uint,
     ret none;
 }
 
-#[doc = "Find the last index containing a matching value"]
+/// Find the last index containing a matching value
 pure fn rposition_elem<T>(v: &[T], x: T) -> option<uint> {
     rposition(v, |y| x == y)
 }
 
-#[doc = "
-Find the last index matching some predicate
-
-Apply function `f` to each element of `v` in reverse order.  When function
-`f` returns true then an option containing the index is returned. If `f`
-matches no elements then none is returned.
-"]
+/**
+ * Find the last index matching some predicate
+ *
+ * Apply function `f` to each element of `v` in reverse order.  When function
+ * `f` returns true then an option containing the index is returned. If `f`
+ * matches no elements then none is returned.
+ */
 pure fn rposition<T>(v: &[T], f: fn(T) -> bool) -> option<uint> {
     rposition_between(v, 0u, len(v), f)
 }
 
-#[doc = "
-Find the last index matching some predicate within a range
-
-Apply function `f` to each element of `v` in reverse order between the range
-[`start`, `end`). When function `f` returns true then an option containing
-the index is returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Find the last index matching some predicate within a range
+ *
+ * Apply function `f` to each element of `v` in reverse order between the
+ * range [`start`, `end`). When function `f` returns true then an option
+ * containing the index is returned. If `f` matches no elements then none is
+ * returned.
+ */
 pure fn rposition_between<T>(v: &[T], start: uint, end: uint,
                              f: fn(T) -> bool) -> option<uint> {
     assert start <= end;
@@ -883,14 +872,14 @@ pure fn rposition_between<T>(v: &[T], start: uint, end: uint,
 // saying the two result lists have the same length -- or, could
 // return a nominal record with a constraint saying that, instead of
 // returning a tuple (contingent on issue #869)
-#[doc = "
-Convert a vector of pairs into a pair of vectors
-
-Returns a tuple containing two vectors where the i-th element of the first
-vector contains the first element of the i-th tuple of the input vector,
-and the i-th element of the second vector contains the second element
-of the i-th tuple of the input vector.
-"]
+/**
+ * Convert a vector of pairs into a pair of vectors
+ *
+ * Returns a tuple containing two vectors where the i-th element of the first
+ * vector contains the first element of the i-th tuple of the input vector,
+ * and the i-th element of the second vector contains the second element
+ * of the i-th tuple of the input vector.
+ */
 pure fn unzip<T: copy, U: copy>(v: &[(T, U)]) -> (~[T], ~[U]) {
     let mut as = ~[], bs = ~[];
     for each(v) |p| {
@@ -903,12 +892,12 @@ pure fn unzip<T: copy, U: copy>(v: &[(T, U)]) -> (~[T], ~[U]) {
     ret (as, bs);
 }
 
-#[doc = "
-Convert two vectors to a vector of pairs
-
-Returns a vector of tuples, where the i-th tuple contains contains the
-i-th elements from each of the input vectors.
-"]
+/**
+ * Convert two vectors to a vector of pairs
+ *
+ * Returns a vector of tuples, where the i-th tuple contains contains the
+ * i-th elements from each of the input vectors.
+ */
 pure fn zip<T: copy, U: copy>(v: &[const T], u: &[const U]) -> ~[(T, U)] {
     let mut zipped = ~[];
     let sz = len(v);
@@ -918,20 +907,20 @@ pure fn zip<T: copy, U: copy>(v: &[const T], u: &[const U]) -> ~[(T, U)] {
     ret zipped;
 }
 
-#[doc = "
-Swaps two elements in a vector
-
-# Arguments
-
-* v  The input vector
-* a - The index of the first element
-* b - The index of the second element
-"]
+/**
+ * Swaps two elements in a vector
+ *
+ * # Arguments
+ *
+ * * v  The input vector
+ * * a - The index of the first element
+ * * b - The index of the second element
+ */
 fn swap<T>(&&v: ~[mut T], a: uint, b: uint) {
     v[a] <-> v[b];
 }
 
-#[doc = "Reverse the order of elements in a vector, in place"]
+/// Reverse the order of elements in a vector, in place
 fn reverse<T>(v: ~[mut T]) {
     let mut i: uint = 0u;
     let ln = len::<T>(v);
@@ -939,7 +928,7 @@ fn reverse<T>(v: ~[mut T]) {
 }
 
 
-#[doc = "Returns a vector with the order of elements reversed"]
+/// Returns a vector with the order of elements reversed
 pure fn reversed<T: copy>(v: &[const T]) -> ~[T] {
     let mut rs: ~[T] = ~[];
     let mut i = len::<T>(v);
@@ -951,12 +940,12 @@ pure fn reversed<T: copy>(v: &[const T]) -> ~[T] {
     ret rs;
 }
 
-#[doc = "
-Iterates over a slice
-
-Iterates over slice `v` and, for each element, calls function `f` with the
-element's value.
-"]
+/**
+ * Iterates over a slice
+ *
+ * Iterates over slice `v` and, for each element, calls function `f` with the
+ * element's value.
+ */
 #[inline(always)]
 pure fn iter<T>(v: &[T], f: fn(T)) {
     iter_between(v, 0u, vec::len(v), f)
@@ -988,11 +977,11 @@ pure fn iter_between<T>(v: &[T], start: uint, end: uint, f: fn(T)) {
     }
 }
 
-#[doc = "
-Iterates over a vector, with option to break
-
-Return true to continue, false to break.
-"]
+/**
+ * Iterates over a vector, with option to break
+ *
+ * Return true to continue, false to break.
+ */
 #[inline(always)]
 pure fn each<T>(v: &[const T], f: fn(T) -> bool) {
     do vec::unpack_slice(v) |p, n| {
@@ -1008,11 +997,11 @@ pure fn each<T>(v: &[const T], f: fn(T) -> bool) {
     }
 }
 
-#[doc = "
-Iterates over a vector's elements and indices
-
-Return true to continue, false to break.
-"]
+/**
+ * Iterates over a vector's elements and indices
+ *
+ * Return true to continue, false to break.
+ */
 #[inline(always)]
 pure fn eachi<T>(v: &[const T], f: fn(uint, T) -> bool) {
     do vec::unpack_slice(v) |p, n| {
@@ -1028,13 +1017,13 @@ pure fn eachi<T>(v: &[const T], f: fn(uint, T) -> bool) {
     }
 }
 
-#[doc = "
-Iterates over two vectors simultaneously
-
-# Failure
-
-Both vectors must have the same length
-"]
+/**
+ * Iterates over two vectors simultaneously
+ *
+ * # Failure
+ *
+ * Both vectors must have the same length
+ */
 #[inline]
 fn iter2<U, T>(v1: &[U], v2: &[T], f: fn(U, T)) {
     assert len(v1) == len(v2);
@@ -1043,12 +1032,12 @@ fn iter2<U, T>(v1: &[U], v2: &[T], f: fn(U, T)) {
     }
 }
 
-#[doc = "
-Iterates over a vector's elements and indexes
-
-Iterates over vector `v` and, for each element, calls function `f` with the
-element's value and index.
-"]
+/**
+ * Iterates over a vector's elements and indexes
+ *
+ * Iterates over vector `v` and, for each element, calls function `f` with the
+ * element's value and index.
+ */
 #[inline(always)]
 pure fn iteri<T>(v: &[T], f: fn(uint, T)) {
     let mut i = 0u;
@@ -1056,22 +1045,22 @@ pure fn iteri<T>(v: &[T], f: fn(uint, T)) {
     while i < l { f(i, v[i]); i += 1u; }
 }
 
-#[doc = "
-Iterates over a vector in reverse
-
-Iterates over vector `v` and, for each element, calls function `f` with the
-element's value.
-"]
+/**
+ * Iterates over a vector in reverse
+ *
+ * Iterates over vector `v` and, for each element, calls function `f` with the
+ * element's value.
+ */
 pure fn riter<T>(v: &[T], f: fn(T)) {
     riteri(v, |_i, v| f(v))
 }
 
-#[doc ="
-Iterates over a vector's elements and indexes in reverse
-
-Iterates over vector `v` and, for each element, calls function `f` with the
-element's value and index.
-"]
+/**
+ * Iterates over a vector's elements and indexes in reverse
+ *
+ * Iterates over vector `v` and, for each element, calls function `f` with the
+ * element's value and index.
+ */
 pure fn riteri<T>(v: &[T], f: fn(uint, T)) {
     let mut i = len(v);
     while 0u < i {
@@ -1080,16 +1069,16 @@ pure fn riteri<T>(v: &[T], f: fn(uint, T)) {
     };
 }
 
-#[doc = "
-Iterate over all permutations of vector `v`.
-
-Permutations are produced in lexicographic order with respect to the order of
-elements in `v` (so if `v` is sorted then the permutations are
-lexicographically sorted).
-
-The total number of permutations produced is `len(v)!`.  If `v` contains
-repeated elements, then some permutations are repeated.
-"]
+/**
+ * Iterate over all permutations of vector `v`.
+ *
+ * Permutations are produced in lexicographic order with respect to the order
+ * of elements in `v` (so if `v` is sorted then the permutations are
+ * lexicographically sorted).
+ *
+ * The total number of permutations produced is `len(v)!`.  If `v` contains
+ * repeated elements, then some permutations are repeated.
+ */
 pure fn permute<T: copy>(v: &[T], put: fn(~[T])) {
     let ln = len(v);
     if ln == 0u {
@@ -1122,12 +1111,12 @@ pure fn windowed<TT: copy>(nn: uint, xx: &[TT]) -> ~[~[TT]] {
     ret ww;
 }
 
-#[doc = "
-Work with the buffer of a vector.
-
-Allows for unsafe manipulation of vector contents, which is useful for
-foreign interop.
-"]
+/**
+ * Work with the buffer of a vector.
+ *
+ * Allows for unsafe manipulation of vector contents, which is useful for
+ * foreign interop.
+ */
 fn as_buf<E,T>(v: &[E], f: fn(*E) -> T) -> T {
     unpack_slice(v, |buf, _len| f(buf))
 }
@@ -1136,9 +1125,7 @@ fn as_mut_buf<E,T>(v: &[mut E], f: fn(*mut E) -> T) -> T {
     unpack_mut_slice(v, |buf, _len| f(buf))
 }
 
-#[doc = "
-Work with the buffer and length of a slice.
-"]
+/// Work with the buffer and length of a slice.
 #[inline(always)]
 pure fn unpack_slice<T,U>(s: &[const T],
                           f: fn(*T, uint) -> U) -> U {
@@ -1149,9 +1136,7 @@ pure fn unpack_slice<T,U>(s: &[const T],
     }
 }
 
-#[doc = "
-Work with the buffer and length of a slice.
-"]
+/// Work with the buffer and length of a slice.
 #[inline(always)]
 pure fn unpack_const_slice<T,U>(s: &[const T],
                                 f: fn(*const T, uint) -> U) -> U {
@@ -1163,9 +1148,7 @@ pure fn unpack_const_slice<T,U>(s: &[const T],
     }
 }
 
-#[doc = "
-Work with the buffer and length of a slice.
-"]
+/// Work with the buffer and length of a slice.
 #[inline(always)]
 pure fn unpack_mut_slice<T,U>(s: &[mut T],
                               f: fn(*mut T, uint) -> U) -> U {
@@ -1191,172 +1174,170 @@ impl extensions<T: copy> for ~[mut T] {
     }
 }
 
-#[doc = "Extension methods for vectors"]
+/// Extension methods for vectors
 impl extensions/&<T> for &[const T] {
-    #[doc = "Returns true if a vector contains no elements"]
+    /// Returns true if a vector contains no elements
     #[inline]
     pure fn is_empty() -> bool { is_empty(self) }
-    #[doc = "Returns true if a vector contains some elements"]
+    /// Returns true if a vector contains some elements
     #[inline]
     pure fn is_not_empty() -> bool { is_not_empty(self) }
-    #[doc = "Returns the length of a vector"]
+    /// Returns the length of a vector
     #[inline]
     pure fn len() -> uint { len(self) }
 }
 
-#[doc = "Extension methods for vectors"]
+/// Extension methods for vectors
 impl extensions/&<T: copy> for &[const T] {
-    #[doc = "Returns the first element of a vector"]
+    /// Returns the first element of a vector
     #[inline]
     pure fn head() -> T { head(self) }
-    #[doc = "Returns all but the last elemnt of a vector"]
+    /// Returns all but the last elemnt of a vector
     #[inline]
     pure fn init() -> ~[T] { init(self) }
-    #[doc = "
-    Returns the last element of a `v`, failing if the vector is empty.
-    "]
+    /// Returns the last element of a `v`, failing if the vector is empty.
     #[inline]
     pure fn last() -> T { last(self) }
-    #[doc = "Returns a copy of the elements from [`start`..`end`) from `v`."]
+    /// Returns a copy of the elements from [`start`..`end`) from `v`.
     #[inline]
     pure fn slice(start: uint, end: uint) -> ~[T] { slice(self, start, end) }
-    #[doc = "Returns all but the first element of a vector"]
+    /// Returns all but the first element of a vector
     #[inline]
     pure fn tail() -> ~[T] { tail(self) }
 }
 
-#[doc = "Extension methods for vectors"]
+/// Extension methods for vectors
 impl extensions/&<T> for &[T] {
-    #[doc = "Reduce a vector from right to left"]
+    /// Reduce a vector from right to left
     #[inline]
     pure fn foldr<U: copy>(z: U, p: fn(T, U) -> U) -> U { foldr(self, z, p) }
-    #[doc = "
-    Iterates over a vector
-
-    Iterates over vector `v` and, for each element, calls function `f` with
-    the element's value.
-    "]
+    /**
+     * Iterates over a vector
+     *
+     * Iterates over vector `v` and, for each element, calls function `f` with
+     * the element's value.
+     */
     #[inline]
     pure fn iter(f: fn(T)) { iter(self, f) }
-    #[doc = "
-    Iterates over a vector's elements and indexes
-
-    Iterates over vector `v` and, for each element, calls function `f` with
-    the element's value and index.
-    "]
+    /**
+     * Iterates over a vector's elements and indexes
+     *
+     * Iterates over vector `v` and, for each element, calls function `f` with
+     * the element's value and index.
+     */
     #[inline]
     pure fn iteri(f: fn(uint, T)) { iteri(self, f) }
-    #[doc = "
-    Find the first index matching some predicate
-
-    Apply function `f` to each element of `v`.  When function `f` returns true
-    then an option containing the index is returned. If `f` matches no
-    elements then none is returned.
-    "]
+    /**
+     * Find the first index matching some predicate
+     *
+     * Apply function `f` to each element of `v`.  When function `f` returns
+     * true then an option containing the index is returned. If `f` matches no
+     * elements then none is returned.
+     */
     #[inline]
     pure fn position(f: fn(T) -> bool) -> option<uint> { position(self, f) }
-    #[doc = "Find the first index containing a matching value"]
+    /// Find the first index containing a matching value
     #[inline]
     pure fn position_elem(x: T) -> option<uint> { position_elem(self, x) }
-    #[doc = "
-    Iterates over a vector in reverse
-
-    Iterates over vector `v` and, for each element, calls function `f` with
-    the element's value.
-    "]
+    /**
+     * Iterates over a vector in reverse
+     *
+     * Iterates over vector `v` and, for each element, calls function `f` with
+     * the element's value.
+     */
     #[inline]
     pure fn riter(f: fn(T)) { riter(self, f) }
-    #[doc ="
-    Iterates over a vector's elements and indexes in reverse
-
-    Iterates over vector `v` and, for each element, calls function `f` with
-    the element's value and index.
-    "]
+    /**
+     * Iterates over a vector's elements and indexes in reverse
+     *
+     * Iterates over vector `v` and, for each element, calls function `f` with
+     * the element's value and index.
+     */
     #[inline]
     pure fn riteri(f: fn(uint, T)) { riteri(self, f) }
-    #[doc = "
-    Find the last index matching some predicate
-
-    Apply function `f` to each element of `v` in reverse order.  When function
-    `f` returns true then an option containing the index is returned. If `f`
-    matches no elements then none is returned.
-    "]
+    /**
+     * Find the last index matching some predicate
+     *
+     * Apply function `f` to each element of `v` in reverse order.  When
+     * function `f` returns true then an option containing the index is
+     * returned. If `f` matches no elements then none is returned.
+     */
     #[inline]
     pure fn rposition(f: fn(T) -> bool) -> option<uint> { rposition(self, f) }
-    #[doc = "Find the last index containing a matching value"]
+    /// Find the last index containing a matching value
     #[inline]
     pure fn rposition_elem(x: T) -> option<uint> { rposition_elem(self, x) }
-    #[doc = "
-    Apply a function to each element of a vector and return the results
-    "]
+    /// Apply a function to each element of a vector and return the results
     #[inline]
     pure fn map<U>(f: fn(T) -> U) -> ~[U] { map(self, f) }
-    #[doc = "
-    Apply a function to the index and value of each element in the vector
-    and return the results
-    "]
+    /**
+     * Apply a function to the index and value of each element in the vector
+     * and return the results
+     */
     pure fn mapi<U>(f: fn(uint, T) -> U) -> ~[U] {
         mapi(self, f)
     }
-    #[doc = "Returns true if the function returns true for all elements.
-
-    If the vector is empty, true is returned."]
+    /**
+     * Returns true if the function returns true for all elements.
+     *
+     *     If the vector is empty, true is returned.
+     */
     pure fn alli(f: fn(uint, T) -> bool) -> bool {
         alli(self, f)
     }
-    #[doc = "
-    Apply a function to each element of a vector and return a concatenation
-    of each result vector
-    "]
+    /**
+     * Apply a function to each element of a vector and return a concatenation
+     * of each result vector
+     */
     #[inline]
     pure fn flat_map<U>(f: fn(T) -> ~[U]) -> ~[U] { flat_map(self, f) }
-    #[doc = "
-    Apply a function to each element of a vector and return the results
-
-    If function `f` returns `none` then that element is excluded from
-    the resulting vector.
-    "]
+    /**
+     * Apply a function to each element of a vector and return the results
+     *
+     * If function `f` returns `none` then that element is excluded from
+     * the resulting vector.
+     */
     #[inline]
     pure fn filter_map<U: copy>(f: fn(T) -> option<U>) -> ~[U] {
         filter_map(self, f)
     }
 }
 
-#[doc = "Extension methods for vectors"]
+/// Extension methods for vectors
 impl extensions/&<T: copy> for &[T] {
-    #[doc = "
-    Construct a new vector from the elements of a vector for which some
-    predicate holds.
-
-    Apply function `f` to each element of `v` and return a vector containing
-    only those elements for which `f` returned true.
-    "]
+    /**
+     * Construct a new vector from the elements of a vector for which some
+     * predicate holds.
+     *
+     * Apply function `f` to each element of `v` and return a vector
+     * containing only those elements for which `f` returned true.
+     */
     #[inline]
     pure fn filter(f: fn(T) -> bool) -> ~[T] { filter(self, f) }
-    #[doc = "
-    Search for the first 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 the first 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.
+     */
     #[inline]
     pure fn find(f: fn(T) -> bool) -> option<T> { find(self, f) }
-    #[doc = "
-    Search for the last element that matches a given predicate
-
-    Apply function `f` to each element of `v` in reverse order. When function
-    `f` returns true then an option containing the element is returned. If `f`
-    matches no elements then none is returned.
-    "]
+    /**
+     * Search for the last element that matches a given predicate
+     *
+     * Apply function `f` to each element of `v` in reverse order. When
+     * function `f` returns true then an option containing the element is
+     * returned. If `f` matches no elements then none is returned.
+     */
     #[inline]
     pure fn rfind(f: fn(T) -> bool) -> option<T> { rfind(self, f) }
 }
 
-#[doc = "Unsafe operations"]
+/// Unsafe operations
 mod unsafe {
     // FIXME: This should have crate visibility (#1893 blocks that)
-    #[doc = "The internal representation of a vector"]
+    /// The internal representation of a vector
     type vec_repr = {
         box_header: (uint, uint, uint, uint),
         mut fill: uint,
@@ -1364,14 +1345,14 @@ mod unsafe {
         data: u8
     };
 
-    #[doc = "
-    Constructs a vector from an unsafe pointer to a buffer
-
-    # Arguments
-
-    * ptr - An unsafe pointer to a buffer of `T`
-    * elts - The number of elements in the buffer
-    "]
+    /**
+     * Constructs a vector from an unsafe pointer to a buffer
+     *
+     * # Arguments
+     *
+     * * ptr - An unsafe pointer to a buffer of `T`
+     * * elts - The number of elements in the buffer
+     */
     #[inline(always)]
     unsafe fn from_buf<T>(ptr: *T, elts: uint) -> ~[T] {
         ret ::unsafe::reinterpret_cast(
@@ -1380,28 +1361,28 @@ mod unsafe {
                                         elts as size_t));
     }
 
-    #[doc = "
-    Sets the length of a vector
-
-    This will explicitly set the size of the vector, without actually
-    modifing its buffers, so it is up to the caller to ensure that
-    the vector is actually the specified size.
-    "]
+    /**
+     * Sets the length of a vector
+     *
+     * This will explicitly set the size of the vector, without actually
+     * modifing its buffers, so it is up to the caller to ensure that
+     * the vector is actually the specified size.
+     */
     #[inline(always)]
     unsafe fn set_len<T>(&&v: ~[const T], new_len: uint) {
         let repr: **vec_repr = ::unsafe::reinterpret_cast(addr_of(v));
         (**repr).fill = new_len * sys::size_of::<T>();
     }
 
-    #[doc = "
-    Returns an unsafe pointer to the vector's buffer
-
-    The caller must ensure that the vector outlives the pointer this
-    function returns, or else it will end up pointing to garbage.
-
-    Modifying the vector may cause its buffer to be reallocated, which
-    would also make any pointers to it invalid.
-    "]
+    /**
+     * Returns an unsafe pointer to the vector's buffer
+     *
+     * The caller must ensure that the vector outlives the pointer this
+     * function returns, or else it will end up pointing to garbage.
+     *
+     * Modifying the vector may cause its buffer to be reallocated, which
+     * would also make any pointers to it invalid.
+     */
     #[inline(always)]
     unsafe fn to_ptr<T>(v: ~[const T]) -> *T {
         let repr: **vec_repr = ::unsafe::reinterpret_cast(addr_of(v));
@@ -1409,9 +1390,10 @@ mod unsafe {
     }
 
 
-    #[doc = "
-    Form a slice from a pointer and length (as a number of units, not bytes).
-    "]
+    /**
+     * Form a slice from a pointer and length (as a number of units,
+     * not bytes).
+     */
     #[inline(always)]
     unsafe fn form_slice<T,U>(p: *T, len: uint, f: fn(&& &[T]) -> U) -> U {
         let pair = (p, len * sys::size_of::<T>());
@@ -1421,13 +1403,13 @@ mod unsafe {
     }
 }
 
-#[doc = "Operations on `[u8]`"]
+/// Operations on `[u8]`
 mod u8 {
     export cmp;
     export lt, le, eq, ne, ge, gt;
     export hash;
 
-    #[doc = "Bytewise string comparison"]
+    /// Bytewise string comparison
     pure fn cmp(&&a: ~[u8], &&b: ~[u8]) -> int {
         let a_len = len(a);
         let b_len = len(b);
@@ -1448,25 +1430,25 @@ mod u8 {
         }
     }
 
-    #[doc = "Bytewise less than or equal"]
+    /// Bytewise less than or equal
     pure fn lt(&&a: ~[u8], &&b: ~[u8]) -> bool { cmp(a, b) < 0 }
 
-    #[doc = "Bytewise less than or equal"]
+    /// Bytewise less than or equal
     pure fn le(&&a: ~[u8], &&b: ~[u8]) -> bool { cmp(a, b) <= 0 }
 
-    #[doc = "Bytewise equality"]
+    /// Bytewise equality
     pure fn eq(&&a: ~[u8], &&b: ~[u8]) -> bool { unsafe { cmp(a, b) == 0 } }
 
-    #[doc = "Bytewise inequality"]
+    /// Bytewise inequality
     pure fn ne(&&a: ~[u8], &&b: ~[u8]) -> bool { unsafe { cmp(a, b) != 0 } }
 
-    #[doc ="Bytewise greater than or equal"]
+    /// Bytewise greater than or equal
     pure fn ge(&&a: ~[u8], &&b: ~[u8]) -> bool { cmp(a, b) >= 0 }
 
-    #[doc = "Bytewise greater than"]
+    /// Bytewise greater than
     pure fn gt(&&a: ~[u8], &&b: ~[u8]) -> bool { cmp(a, b) > 0 }
 
-    #[doc = "String hash function"]
+    /// String hash function
     fn hash(&&s: ~[u8]) -> uint {
         /* Seems to have been tragically copy/pasted from str.rs,
            or vice versa. But I couldn't figure out how to abstract