diff --git a/src/libcore/arc.rs b/src/libcore/arc.rs
index 6b576afe50c1b..e2d9e669cfc64 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 cf7689c57ac30..1f0d9174c7359 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 881d736d2ba8f..bbafc87774d3e 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 8e204d89f3f4a..28645df1b46c0 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 aea97cf1649f5..1bdf3b9909ac4 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 ff6187a9f61d4..26672659cb0fb 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 fd1d20f9d6e2e..58f2281daf384 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 ed61c587116b7..f97d2727194eb 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 aae0ffb2519ad..f80972d50b33e 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 aad8825a52b71..9c1d6cae36b14 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 9dadd848415e6..d1ea214ef0a8d 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 d84438f484561..c72aa6e3aef0b 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 72f1b6b866a46..40488d9f8f4f7 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 fcca8e420e441..7d13602ecc01b 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 c70d123d4affd..69d31c9a270c7 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 ac11f2f1102c6..407b810e95d5c 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 51149d7e1fbf4..07acb4be8ce1f 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 f97dce5854dc8..d34ea38034dea 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 3f1f4db6a4dd6..efab0b70b5754 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 4ccc9f2010d36..740a78a6d9cee 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 261a18f6f7df3..1e233dfe8d534 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 79ace3af1e597..e78b8551c6dd4 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 2d192b4aab1dd..551b444d89cfe 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 6e8e556775600..ac7dd013be9ae 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 ec553ad5e2f1a..808552fca6c02 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 1b514b00759f6..67f4200255720 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 c4bcbdb36cdb8..a770cba36dfe2 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 b6913f9479e3c..704c0fcaf4b71 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 e004aa32dc712..4db2cdb086d5e 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 64d5ff9c73c76..677d19e096444 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 8481793a8ff64..981a33c30da52 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 b87a575fdef24..43a9e8f6981bf 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 992083c484b02..e99860a6250e7 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 e636a1007b921..7ebec38cf1470 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 98840dadc1115..d50ee4ac6872e 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 7f4ffe97c014f..91b9eb856e495 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 843215bd4b9b3..19d0a3e9e4562 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 de120b8cc78ad..716a59f8ea91e 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 a4e4c4fe16672..ad7017444dd78 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 81039ec552174..895377170bc0b 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
diff --git a/src/libstd/bitv.rs b/src/libstd/bitv.rs
index adc3a7969d62a..f6c7b573f65ed 100644
--- a/src/libstd/bitv.rs
+++ b/src/libstd/bitv.rs
@@ -21,19 +21,19 @@ export eq_vec;
 // write an optimizing version of this module that produces a different obj
 // for the case where nbits <= 32.
 
-#[doc = "The bitvector type"]
+/// The bitvector type
 type bitv = @{storage: ~[mut uint], nbits: uint};
 
 const uint_bits: uint = 32u + (1u << 32u >> 27u);
 
-#[doc = "
-Constructs a bitvector
-
-# Arguments
-
-* nbits - The number of bits in the bitvector
-* init - If true then the bits are initialized to 1, otherwise 0
-"]
+/**
+ * Constructs a bitvector
+ *
+ * # Arguments
+ *
+ * * nbits - The number of bits in the bitvector
+ * * init - If true then the bits are initialized to 1, otherwise 0
+ */
 fn bitv(nbits: uint, init: bool) -> bitv {
     let elt = if init { !0u } else { 0u };
     let storage = vec::to_mut(vec::from_elem(nbits / uint_bits + 1u, elt));
@@ -63,12 +63,12 @@ fn union(v0: bitv, v1: bitv) -> bool {
 
 fn land(w0: uint, w1: uint) -> uint { ret w0 & w1; }
 
-#[doc = "
-Calculates the intersection of two bitvectors
-
-Sets `v0` to the intersection of `v0` and `v1`. Both bitvectors must be the
-same length. Returns 'true' if `v0` was changed.
-"]
+/**
+ * Calculates the intersection of two bitvectors
+ *
+ * Sets `v0` to the intersection of `v0` and `v1`. Both bitvectors must be the
+ * same length. Returns 'true' if `v0` was changed.
+ */
 fn intersect(v0: bitv, v1: bitv) -> bool {
     let sub = land;
     ret process(v0, v1, sub);
@@ -76,16 +76,16 @@ fn intersect(v0: bitv, v1: bitv) -> bool {
 
 fn right(_w0: uint, w1: uint) -> uint { ret w1; }
 
-#[doc = "
-Assigns the value of `v1` to `v0`
-
-Both bitvectors must be the same length. Returns `true` if `v0` was changed
-"]
+/**
+ * Assigns the value of `v1` to `v0`
+ *
+ * Both bitvectors must be the same length. Returns `true` if `v0` was changed
+ */
 fn assign(v0: bitv, v1: bitv) -> bool {
     let sub = right; ret process(v0, v1, sub);
 }
 
-#[doc = "Makes a copy of a bitvector"]
+/// Makes a copy of a bitvector
 fn clone(v: bitv) -> bitv {
     let storage = vec::to_mut(vec::from_elem(v.nbits / uint_bits + 1u, 0u));
     let len = vec::len(v.storage);
@@ -93,7 +93,7 @@ fn clone(v: bitv) -> bitv {
     ret @{storage: storage, nbits: v.nbits};
 }
 
-#[doc = "Retrieve the value at index `i`"]
+/// Retrieve the value at index `i`
 #[inline(always)]
 pure fn get(v: bitv, i: uint) -> bool {
     assert (i < v.nbits);
@@ -104,12 +104,12 @@ pure fn get(v: bitv, i: uint) -> bool {
     ret x == 1u;
 }
 
-#[doc = "
-Compares two bitvectors
-
-Both bitvectors must be the same length. Returns `true` if both bitvectors
-contain identical elements.
-"]
+/**
+ * Compares two bitvectors
+ *
+ * Both bitvectors must be the same length. Returns `true` if both bitvectors
+ * contain identical elements.
+ */
 fn equal(v0: bitv, v1: bitv) -> bool {
     if v0.nbits != v1.nbits { ret false; }
     let len = vec::len(v1.storage);
@@ -118,26 +118,26 @@ fn equal(v0: bitv, v1: bitv) -> bool {
     }
 }
 
-#[doc = "Set all bits to 0"]
+/// Set all bits to 0
 #[inline(always)]
 fn clear(v: bitv) { for each_storage(v) |w| { w = 0u } }
 
-#[doc = "Set all bits to 1"]
+/// Set all bits to 1
 #[inline(always)]
 fn set_all(v: bitv) { for each_storage(v) |w| { w = !0u } }
 
-#[doc = "Invert all bits"]
+/// Invert all bits
 #[inline(always)]
 fn invert(v: bitv) { for each_storage(v) |w| { w = !w } }
 
-#[doc = "
-Calculate the difference between two bitvectors
-
-Sets each element of `v0` to the value of that element minus the element
-of `v1` at the same index. Both bitvectors must be the same length.
-
-Returns `true` if `v0` was changed.
-"]
+/**
+ * Calculate the difference between two bitvectors
+ *
+ * Sets each element of `v0` to the value of that element minus the element
+ * of `v1` at the same index. Both bitvectors must be the same length.
+ *
+ * Returns `true` if `v0` was changed.
+ */
 fn difference(v0: bitv, v1: bitv) -> bool {
     invert(v1);
     let b = intersect(v0, v1);
@@ -145,11 +145,11 @@ fn difference(v0: bitv, v1: bitv) -> bool {
     ret b;
 }
 
-#[doc = "
-Set the value of a bit at a given index
-
-`i` must be less than the length of the bitvector.
-"]
+/**
+ * Set the value of a bit at a given index
+ *
+ * `i` must be less than the length of the bitvector.
+ */
 #[inline(always)]
 fn set(v: bitv, i: uint, x: bool) {
     assert (i < v.nbits);
@@ -161,14 +161,14 @@ fn set(v: bitv, i: uint, x: bool) {
 }
 
 
-#[doc = "Returns true if all bits are 1"]
+/// Returns true if all bits are 1
 fn is_true(v: bitv) -> bool {
     for each(v) |i| { if !i { ret false; } }
     ret true;
 }
 
 
-#[doc = "Returns true if all bits are 0"]
+/// Returns true if all bits are 0
 fn is_false(v: bitv) -> bool {
     for each(v) |i| { if i { ret false; } }
     ret true;
@@ -178,11 +178,11 @@ fn init_to_vec(v: bitv, i: uint) -> uint {
     ret if get(v, i) { 1u } else { 0u };
 }
 
-#[doc = "
-Converts the bitvector to a vector of uint with the same length.
-
-Each uint in the resulting vector has either value 0u or 1u.
-"]
+/**
+ * Converts the bitvector to a vector of uint with the same length.
+ *
+ * Each uint in the resulting vector has either value 0u or 1u.
+ */
 fn to_vec(v: bitv) -> ~[uint] {
     let sub = |x| init_to_vec(v, x);
     ret vec::from_fn::<uint>(v.nbits, sub);
@@ -207,24 +207,24 @@ fn each_storage(v: bitv, op: fn(&uint) -> bool) {
     }
 }
 
-#[doc = "
-Converts the bitvector to a string.
-
-The resulting string has the same length as the bitvector, and each character
-is either '0' or '1'.
-"]
+/**
+ * Converts the bitvector to a string.
+ *
+ * The resulting string has the same length as the bitvector, and each
+ * character is either '0' or '1'.
+ */
 fn to_str(v: bitv) -> str {
     let mut rs = "";
     for each(v) |i| { if i { rs += "1"; } else { rs += "0"; } }
     ret rs;
 }
 
-#[doc = "
-Compare a bitvector to a vector of uint
-
-The uint vector is expected to only contain the values 0u and 1u. Both the
-bitvector and vector must have the same length
-"]
+/**
+ * Compare a bitvector to a vector of uint
+ *
+ * The uint vector is expected to only contain the values 0u and 1u. Both the
+ * bitvector and vector must have the same length
+ */
 fn eq_vec(v0: bitv, v1: ~[uint]) -> bool {
     assert (v0.nbits == vec::len::<uint>(v1));
     let len = v0.nbits;
diff --git a/src/libstd/c_vec.rs b/src/libstd/c_vec.rs
index 258bc432da141..7f71b999d6f4f 100644
--- a/src/libstd/c_vec.rs
+++ b/src/libstd/c_vec.rs
@@ -1,29 +1,30 @@
-#[doc = "
-Library to interface with chunks of memory allocated in C.
-
-It is often desirable to safely interface with memory allocated from C,
-encapsulating the unsafety into allocation and destruction time.  Indeed,
-allocating memory externally is currently the only way to give Rust shared
-mut state with C programs that keep their own references; vectors are
-unsuitable because they could be reallocated or moved at any time, and
-importing C memory into a vector takes a one-time snapshot of the memory.
-
-This module simplifies the usage of such external blocks of memory.  Memory
-is encapsulated into an opaque object after creation; the lifecycle of the
-memory can be optionally managed by Rust, if an appropriate destructor
-closure is provided.  Safety is ensured by bounds-checking accesses, which
-are marshalled through get and set functions.
-
-There are three unsafe functions: the two introduction forms, and the
-pointer elimination form.  The introduction forms are unsafe for the obvious
-reason (they act on a pointer that cannot be checked inside the method), but
-the elimination form is somewhat more subtle in its unsafety.  By using a
-pointer taken from a c_vec::t without keeping a reference to the c_vec::t
-itself around, the c_vec could be garbage collected, and the memory within
-could be destroyed.  There are legitimate uses for the pointer elimination
-form -- for instance, to pass memory back into C -- but great care must be
-taken to ensure that a reference to the c_vec::t is still held if needed.
-"];
+/*!
+ * Library to interface with chunks of memory allocated in C.
+ *
+ * It is often desirable to safely interface with memory allocated from C,
+ * encapsulating the unsafety into allocation and destruction time.  Indeed,
+ * allocating memory externally is currently the only way to give Rust shared
+ * mut state with C programs that keep their own references; vectors are
+ * unsuitable because they could be reallocated or moved at any time, and
+ * importing C memory into a vector takes a one-time snapshot of the memory.
+ *
+ * This module simplifies the usage of such external blocks of memory.  Memory
+ * is encapsulated into an opaque object after creation; the lifecycle of the
+ * memory can be optionally managed by Rust, if an appropriate destructor
+ * closure is provided.  Safety is ensured by bounds-checking accesses, which
+ * are marshalled through get and set functions.
+ *
+ * There are three unsafe functions: the two introduction forms, and the
+ * pointer elimination form.  The introduction forms are unsafe for the
+ * obvious reason (they act on a pointer that cannot be checked inside the
+ * method), but the elimination form is somewhat more subtle in its unsafety.
+ * By using a pointer taken from a c_vec::t without keeping a reference to the
+ * c_vec::t itself around, the c_vec could be garbage collected, and the
+ * memory within could be destroyed.  There are legitimate uses for the
+ * pointer elimination form -- for instance, to pass memory back into C -- but
+ * great care must be taken to ensure that a reference to the c_vec::t is
+ * still held if needed.
+ */
 
 export c_vec;
 export c_vec, c_vec_with_dtor;
@@ -31,12 +32,12 @@ export get, set;
 export len;
 export ptr;
 
-#[doc = "
-The type representing a foreign chunk of memory
-
-Wrapped in a enum for opacity; FIXME #818 when it is possible to have
-truly opaque types, this should be revisited.
-"]
+/**
+ * The type representing a foreign chunk of memory
+ *
+ * Wrapped in a enum for opacity; FIXME #818 when it is possible to have
+ * truly opaque types, this should be revisited.
+ */
 enum c_vec<T> {
     c_vec_({ base: *mut T, len: uint, rsrc: @dtor_res})
 }
@@ -56,14 +57,14 @@ class dtor_res {
  Section: Introduction forms
  */
 
-#[doc = "
-Create a `c_vec` from a foreign buffer with a given length.
-
-# Arguments
-
-* base - A foreign pointer to a buffer
-* len - The number of elements in the buffer
-"]
+/**
+ * Create a `c_vec` from a foreign buffer with a given length.
+ *
+ * # Arguments
+ *
+ * * base - A foreign pointer to a buffer
+ * * len - The number of elements in the buffer
+ */
 unsafe fn c_vec<T>(base: *mut T, len: uint) -> c_vec<T> {
     ret c_vec_({
         base: base,
@@ -72,17 +73,17 @@ unsafe fn c_vec<T>(base: *mut T, len: uint) -> c_vec<T> {
     });
 }
 
-#[doc = "
-Create a `c_vec` from a foreign buffer, with a given length,
-and a function to run upon destruction.
-
-# Arguments
-
-* base - A foreign pointer to a buffer
-* len - The number of elements in the buffer
-* dtor - A function to run when the value is destructed, useful
-         for freeing the buffer, etc.
-"]
+/**
+ * Create a `c_vec` from a foreign buffer, with a given length,
+ * and a function to run upon destruction.
+ *
+ * # Arguments
+ *
+ * * base - A foreign pointer to a buffer
+ * * len - The number of elements in the buffer
+ * * dtor - A function to run when the value is destructed, useful
+ *          for freeing the buffer, etc.
+ */
 unsafe fn c_vec_with_dtor<T>(base: *mut T, len: uint, dtor: fn@())
   -> c_vec<T> {
     ret c_vec_({
@@ -96,21 +97,21 @@ unsafe fn c_vec_with_dtor<T>(base: *mut T, len: uint, dtor: fn@())
  Section: Operations
  */
 
-#[doc = "
-Retrieves an element at a given index
-
-Fails if `ofs` is greater or equal to the length of the vector
-"]
+/**
+ * Retrieves an element at a given index
+ *
+ * Fails if `ofs` is greater or equal to the length of the vector
+ */
 fn get<T: copy>(t: c_vec<T>, ofs: uint) -> T {
     assert ofs < len(t);
     ret unsafe { *ptr::mut_offset((*t).base, ofs) };
 }
 
-#[doc = "
-Sets the value of an element at a given index
-
-Fails if `ofs` is greater or equal to the length of the vector
-"]
+/**
+ * Sets the value of an element at a given index
+ *
+ * Fails if `ofs` is greater or equal to the length of the vector
+ */
 fn set<T: copy>(t: c_vec<T>, ofs: uint, v: T) {
     assert ofs < len(t);
     unsafe { *ptr::mut_offset((*t).base, ofs) = v };
@@ -120,12 +121,12 @@ fn set<T: copy>(t: c_vec<T>, ofs: uint, v: T) {
  Section: Elimination forms
  */
 
-#[doc = "Returns the length of the vector"]
+/// Returns the length of the vector
 fn len<T>(t: c_vec<T>) -> uint {
     ret (*t).len;
 }
 
-#[doc = "Returns a pointer to the first element of the vector"]
+/// Returns a pointer to the first element of the vector
 unsafe fn ptr<T>(t: c_vec<T>) -> *mut T {
     ret (*t).base;
 }
@@ -183,4 +184,4 @@ mod tests {
         set(cv, 2u, 34u8); /* safety */
     }
 
-}
\ No newline at end of file
+}
diff --git a/src/libstd/cmp.rs b/src/libstd/cmp.rs
index f94c0a7c6afe0..a89148ecec9de 100644
--- a/src/libstd/cmp.rs
+++ b/src/libstd/cmp.rs
@@ -1,4 +1,4 @@
-#[doc="Additional general-purpose comparison functionality."]
+/// Additional general-purpose comparison functionality.
 
 const fuzzy_epsilon: float = 1.0e-6;
 
diff --git a/src/libstd/dbg.rs b/src/libstd/dbg.rs
index be0330e543ac6..ddc0d3b4450a8 100644
--- a/src/libstd/dbg.rs
+++ b/src/libstd/dbg.rs
@@ -1,4 +1,4 @@
-#[doc = "Unsafe debugging functions for inspecting values."];
+//! Unsafe debugging functions for inspecting values.
 
 import unsafe::reinterpret_cast;
 
@@ -47,7 +47,7 @@ unsafe fn ptr_cast<T, U>(x: @T) -> @U {
                               reinterpret_cast(x)))
 }
 
-#[doc = "Triggers a debugger breakpoint"]
+/// Triggers a debugger breakpoint
 fn breakpoint() {
     rustrt::rust_dbg_breakpoint();
 }
diff --git a/src/libstd/deque.rs b/src/libstd/deque.rs
index 32516de2524a1..416a52cde5b60 100644
--- a/src/libstd/deque.rs
+++ b/src/libstd/deque.rs
@@ -1,4 +1,4 @@
-#[doc = "A deque. Untested as of yet. Likely buggy"];
+//! A deque. Untested as of yet. Likely buggy
 
 import option::{some, none};
 import dvec::{dvec, extensions};
diff --git a/src/libstd/fun_treemap.rs b/src/libstd/fun_treemap.rs
index 3e1a11665fe36..6a3b40b88ff50 100644
--- a/src/libstd/fun_treemap.rs
+++ b/src/libstd/fun_treemap.rs
@@ -1,13 +1,13 @@
-#[doc = "
-A functional key,value store that works on anything.
-
-This works using a binary search tree. In the first version, it's a
-very naive algorithm, but it will probably be updated to be a
-red-black tree or something else.
-
-This is copied and modified from treemap right now. It's missing a lot
-of features.
-"];
+/*!
+ * A functional key,value store that works on anything.
+ *
+ * This works using a binary search tree. In the first version, it's a
+ * very naive algorithm, but it will probably be updated to be a
+ * red-black tree or something else.
+ *
+ * This is copied and modified from treemap right now. It's missing a lot
+ * of features.
+ */
 
 import option::{some, none};
 import option = option;
@@ -25,10 +25,10 @@ enum tree_node<K, V> {
     node(@K, @V, @tree_node<K, V>, @tree_node<K, V>)
 }
 
-#[doc = "Create a treemap"]
+/// Create a treemap
 fn init<K, V>() -> treemap<K, V> { @empty }
 
-#[doc = "Insert a value into the map"]
+/// Insert a value into the map
 fn insert<K: copy, V: copy>(m: treemap<K, V>, k: K, v: V) -> treemap<K, V> {
     @alt m {
        @empty { node(@k, @v, @empty, @empty) }
@@ -42,7 +42,7 @@ fn insert<K: copy, V: copy>(m: treemap<K, V>, k: K, v: V) -> treemap<K, V> {
      }
 }
 
-#[doc = "Find a value based on the key"]
+/// Find a value based on the key
 fn find<K, V: copy>(m: treemap<K, V>, k: K) -> option<V> {
     alt *m {
       empty { none }
@@ -54,7 +54,7 @@ fn find<K, V: copy>(m: treemap<K, V>, k: K) -> option<V> {
     }
 }
 
-#[doc = "Visit all pairs in the map in order."]
+/// Visit all pairs in the map in order.
 fn traverse<K, V: copy>(m: treemap<K, V>, f: fn(K, V)) {
     alt *m {
       empty { }
diff --git a/src/libstd/getopts.rs b/src/libstd/getopts.rs
index a82d131f516ed..292c7b8005fed 100644
--- a/src/libstd/getopts.rs
+++ b/src/libstd/getopts.rs
@@ -1,67 +1,66 @@
-#[doc = "
-Simple getopt alternative.
-
-Construct a vector of options, either by using reqopt, optopt, and optflag or
-by building them from components yourself, and pass them to getopts, along
-with a vector of actual arguments (not including argv[0]). You'll either get a
-failure code back, or a match. You'll have to verify whether the amount of
-'free' arguments in the match is what you expect. Use opt_* accessors to get
-argument values out of the match object.
-
-Single-character options are expected to appear on the command line with a
-single preceding dash; multiple-character options are expected to be
-proceeded by two dashes. Options that expect an argument accept their argument
-following either a space or an equals sign.
-
-# Example
-
-The following example shows simple command line parsing for an application
-that requires an input file to be specified, accepts an optional output file
-name following -o, and accepts both -h and --help as optional flags.
-
-    use std;
-    import std::getopts::{optopt,optflag,getopts,opt_present,opt_maybe_str,
-        fail_str};
-
-    fn do_work(in: str, out: option<str>) {
-        // ...
-    }
-
-    fn print_usage(program: str) {
-        io::println(\"Usage: \" + program + \" [options]/~\");
-        io::println(\"-o\t\tOutput\");
-        io::println(\"-h --help\tUsage\");
-    }
-
-    fn main(args: [str]/~) {
-        check vec::is_not_empty(args);
-
-        let program : str = vec::head(args);
-
-        let opts = [
-            optopt(\"o\"),
-            optflag(\"h\"),
-            optflag(\"help\")
-        ]/~;
-        let match = alt getopts(vec::tail(args), opts) {
-            result::ok(m) { m }
-            result::err(f) { fail fail_str(f) }
-        };
-        if opt_present(match, \"h\") || opt_present(match, \"help\") {
-            print_usage(program);
-            ret;
-        }
-        let output = opt_maybe_str(match, \"o\");
-        let input = if vec::is_not_empty(match.free) {
-            match.free[0]
-        } else {
-            print_usage(program);
-            ret;
-        };
-        do_work(input, output);
-    }
-
-"];
+/*!
+ * Simple getopt alternative.
+ *
+ * Construct a vector of options, either by using reqopt, optopt, and optflag
+ * or by building them from components yourself, and pass them to getopts,
+ * along with a vector of actual arguments (not including argv[0]). You'll
+ * either get a failure code back, or a match. You'll have to verify whether
+ * the amount of 'free' arguments in the match is what you expect. Use opt_*
+ * accessors to get argument values out of the match object.
+ *
+ * Single-character options are expected to appear on the command line with a
+ * single preceding dash; multiple-character options are expected to be
+ * proceeded by two dashes. Options that expect an argument accept their
+ * argument following either a space or an equals sign.
+ *
+ * # Example
+ *
+ * The following example shows simple command line parsing for an application
+ * that requires an input file to be specified, accepts an optional output
+ * file name following -o, and accepts both -h and --help as optional flags.
+ *
+ *     use std;
+ *     import std::getopts::{optopt,optflag,getopts,opt_present,opt_maybe_str,
+ *         fail_str};
+ *
+ *     fn do_work(in: str, out: option<str>) {
+ *         // ...
+ *     }
+ *
+ *     fn print_usage(program: str) {
+ *         io::println("Usage: " + program + " [options]/~");
+ *         io::println("-o\t\tOutput");
+ *         io::println("-h --help\tUsage");
+ *     }
+ *
+ *     fn main(args: [str]/~) {
+ *         check vec::is_not_empty(args);
+ *
+ *         let program : str = vec::head(args);
+ *
+ *         let opts = [
+ *             optopt("o"),
+ *             optflag("h"),
+ *             optflag("help")
+ *         ]/~;
+ *         let match = alt getopts(vec::tail(args), opts) {
+ *             result::ok(m) { m }
+ *             result::err(f) { fail fail_str(f) }
+ *         };
+ *         if opt_present(match, "h") || opt_present(match, "help") {
+ *             print_usage(program);
+ *             ret;
+ *         }
+ *         let output = opt_maybe_str(match, "o");
+ *         let input = if vec::is_not_empty(match.free) {
+ *             match.free[0]
+ *         } else {
+ *             print_usage(program);
+ *             ret;
+ *         };
+ *         do_work(input, output);
+ *     }
+ */
 
 import core::result::{err, ok};
 import core::option;
@@ -91,7 +90,7 @@ enum hasarg { yes, no, maybe, }
 
 enum occur { req, optional, multi, }
 
-#[doc = "A description of a possible option"]
+/// A description of a possible option
 type opt = {name: name, hasarg: hasarg, occur: occur};
 
 fn mkname(nm: str) -> name {
@@ -100,40 +99,40 @@ fn mkname(nm: str) -> name {
         } else { long(nm) };
 }
 
-#[doc = "Create an option that is required and takes an argument"]
+/// Create an option that is required and takes an argument
 fn reqopt(name: str) -> opt {
     ret {name: mkname(name), hasarg: yes, occur: req};
 }
 
-#[doc = "Create an option that is optional and takes an argument"]
+/// Create an option that is optional and takes an argument
 fn optopt(name: str) -> opt {
     ret {name: mkname(name), hasarg: yes, occur: optional};
 }
 
-#[doc = "Create an option that is optional and does not take an argument"]
+/// Create an option that is optional and does not take an argument
 fn optflag(name: str) -> opt {
     ret {name: mkname(name), hasarg: no, occur: optional};
 }
 
-#[doc = "Create an option that is optional and takes an optional argument"]
+/// Create an option that is optional and takes an optional argument
 fn optflagopt(name: str) -> opt {
     ret {name: mkname(name), hasarg: maybe, occur: optional};
 }
 
-#[doc = "
-Create an option that is optional, takes an argument, and may occur
-multiple times
-"]
+/**
+ * Create an option that is optional, takes an argument, and may occur
+ * multiple times
+ */
 fn optmulti(name: str) -> opt {
     ret {name: mkname(name), hasarg: yes, occur: multi};
 }
 
 enum optval { val(str), given, }
 
-#[doc = "
-The result of checking command line arguments. Contains a vector
-of matches and a vector of free strings.
-"]
+/**
+ * The result of checking command line arguments. Contains a vector
+ * of matches and a vector of free strings.
+ */
 type match = {opts: ~[opt], vals: ~[~[optval]], free: ~[str]};
 
 fn is_arg(arg: str) -> bool {
@@ -148,10 +147,10 @@ fn find_opt(opts: ~[opt], nm: name) -> option<uint> {
     vec::position(opts, |opt| opt.name == nm)
 }
 
-#[doc = "
-The type returned when the command line does not conform to the
-expected format. Pass this value to <fail_str> to get an error message.
-"]
+/**
+ * The type returned when the command line does not conform to the
+ * expected format. Pass this value to <fail_str> to get an error message.
+ */
 enum fail_ {
     argument_missing(str),
     unrecognized_option(str),
@@ -160,7 +159,7 @@ enum fail_ {
     unexpected_argument(str),
 }
 
-#[doc = "Convert a `fail_` enum into an error string"]
+/// Convert a `fail_` enum into an error string
 fn fail_str(f: fail_) -> str {
     ret alt f {
           argument_missing(nm) { "Argument to option '" + nm + "' missing." }
@@ -175,19 +174,19 @@ fn fail_str(f: fail_) -> str {
         };
 }
 
-#[doc = "
-The result of parsing a command line with a set of options
-(result::t<match, fail_>)
-"]
+/**
+ * The result of parsing a command line with a set of options
+ * (result::t<match, fail_>)
+ */
 type result = result::result<match, fail_>;
 
-#[doc = "
-Parse command line arguments according to the provided options
-
-On success returns `ok(opt)`. Use functions such as `opt_present` `opt_str`,
-etc. to interrogate results.  Returns `err(fail_)` on failure. Use <fail_str>
-to get an error message.
-"]
+/**
+ * Parse command line arguments according to the provided options
+ *
+ * On success returns `ok(opt)`. Use functions such as `opt_present`
+ * `opt_str`, etc. to interrogate results.  Returns `err(fail_)` on failure.
+ * Use <fail_str> to get an error message.
+ */
 fn getopts(args: ~[str], opts: ~[opt]) -> result unsafe {
     let n_opts = vec::len::<opt>(opts);
     fn f(_x: uint) -> ~[optval] { ret ~[]; }
@@ -290,12 +289,12 @@ fn opt_vals(m: match, nm: str) -> ~[optval] {
 
 fn opt_val(m: match, nm: str) -> optval { ret opt_vals(m, nm)[0]; }
 
-#[doc = "Returns true if an option was matched"]
+/// Returns true if an option was matched
 fn opt_present(m: match, nm: str) -> bool {
     ret vec::len::<optval>(opt_vals(m, nm)) > 0u;
 }
 
-#[doc = "Returns true if any of several options were matched"]
+/// Returns true if any of several options were matched
 fn opts_present(m: match, names: ~[str]) -> bool {
     for vec::each(names) |nm| {
         alt find_opt(m.opts, mkname(nm)) {
@@ -307,21 +306,22 @@ fn opts_present(m: match, names: ~[str]) -> bool {
 }
 
 
-#[doc = "
-Returns the string argument supplied to a matching option
-
-Fails if the option was not matched or if the match did not take an argument
-"]
+/**
+ * Returns the string argument supplied to a matching option
+ *
+ * Fails if the option was not matched or if the match did not take an
+ * argument
+ */
 fn opt_str(m: match, nm: str) -> str {
     ret alt opt_val(m, nm) { val(s) { s } _ { fail } };
 }
 
-#[doc = "
-Returns the string argument supplied to one of several matching options
-
-Fails if the no option was provided from the given list, or if the no such
-option took an argument
-"]
+/**
+ * Returns the string argument supplied to one of several matching options
+ *
+ * Fails if the no option was provided from the given list, or if the no such
+ * option took an argument
+ */
 fn opts_str(m: match, names: ~[str]) -> str {
     for vec::each(names) |nm| {
         alt opt_val(m, nm) {
@@ -333,11 +333,12 @@ fn opts_str(m: match, names: ~[str]) -> str {
 }
 
 
-#[doc = "
-Returns a vector of the arguments provided to all matches of the given option.
-
-Used when an option accepts multiple values.
-"]
+/**
+ * Returns a vector of the arguments provided to all matches of the given
+ * option.
+ *
+ * Used when an option accepts multiple values.
+ */
 fn opt_strs(m: match, nm: str) -> ~[str] {
     let mut acc: ~[str] = ~[];
     for vec::each(opt_vals(m, nm)) |v| {
@@ -346,9 +347,7 @@ fn opt_strs(m: match, nm: str) -> ~[str] {
     ret acc;
 }
 
-#[doc = "
-Returns the string argument supplied to a matching option or none
-"]
+/// Returns the string argument supplied to a matching option or none
 fn opt_maybe_str(m: match, nm: str) -> option<str> {
     let vals = opt_vals(m, nm);
     if vec::len::<optval>(vals) == 0u { ret none::<str>; }
@@ -356,13 +355,13 @@ fn opt_maybe_str(m: match, nm: str) -> option<str> {
 }
 
 
-#[doc = "
-Returns the matching string, a default, or none
-
-Returns none if the option was not present, `def` if the option was
-present but no argument was provided, and the argument if the option was
-present and an argument was provided.
-"]
+/**
+ * Returns the matching string, a default, or none
+ *
+ * Returns none if the option was not present, `def` if the option was
+ * present but no argument was provided, and the argument if the option was
+ * present and an argument was provided.
+ */
 fn opt_default(m: match, nm: str, def: str) -> option<str> {
     let vals = opt_vals(m, nm);
     if vec::len::<optval>(vals) == 0u { ret none::<str>; }
diff --git a/src/libstd/json.rs b/src/libstd/json.rs
index 45983654eec89..9f51ab157b76d 100644
--- a/src/libstd/json.rs
+++ b/src/libstd/json.rs
@@ -1,7 +1,7 @@
 // Rust JSON serialization library
 // Copyright (c) 2011 Google Inc.
 
-#[doc = "json serialization"];
+//! json serialization
 
 import result::{result, ok, err};
 import io;
@@ -26,7 +26,7 @@ export list;
 export dict;
 export null;
 
-#[doc = "Represents a json value"]
+/// Represents a json value
 enum json {
     num(float),
     string(@str),
@@ -42,7 +42,7 @@ type error = {
     msg: @str,
 };
 
-#[doc = "Serializes a json value into a io::writer"]
+/// Serializes a json value into a io::writer
 fn to_writer(wr: io::writer, j: json) {
     alt j {
       num(n) { wr.write_str(float::to_str(n, 6u)); }
@@ -109,7 +109,7 @@ fn escape_str(s: str) -> str {
     escaped
 }
 
-#[doc = "Serializes a json value into a string"]
+/// Serializes a json value into a string
 fn to_str(j: json) -> str {
     io::with_str_writer(|wr| to_writer(wr, j))
 }
@@ -461,7 +461,7 @@ impl parser for parser {
     }
 }
 
-#[doc = "Deserializes a json value from an io::reader"]
+/// Deserializes a json value from an io::reader
 fn from_reader(rdr: io::reader) -> result<json, error> {
     let parser = {
         rdr: rdr,
@@ -473,12 +473,12 @@ fn from_reader(rdr: io::reader) -> result<json, error> {
     parser.parse()
 }
 
-#[doc = "Deserializes a json value from a string"]
+/// Deserializes a json value from a string
 fn from_str(s: str) -> result<json, error> {
     io::with_str_reader(s, from_reader)
 }
 
-#[doc = "Test if two json values are equal"]
+/// Test if two json values are equal
 fn eq(value0: json, value1: json) -> bool {
     alt (value0, value1) {
       (num(f0), num(f1)) { f0 == f1 }
diff --git a/src/libstd/list.rs b/src/libstd/list.rs
index 665b2d38f8f19..3a7b0ffd79a25 100644
--- a/src/libstd/list.rs
+++ b/src/libstd/list.rs
@@ -1,4 +1,4 @@
-#[doc = "A standard linked list"];
+//! A standard linked list
 
 import core::option;
 import option::*;
@@ -9,37 +9,37 @@ enum list<T> {
     nil,
 }
 
-#[doc = "Create a list from a vector"]
+/// Create a list from a vector
 fn from_vec<T: copy>(v: &[T]) -> @list<T> {
     vec::foldr(v, @nil::<T>, |h, t| @cons(h, t))
 }
 
-#[doc = "
-Left fold
-
-Applies `f` to `u` and the first element in the list, then applies `f` to the
-result of the previous call and the second element, and so on, returning the
-accumulated result.
-
-# Arguments
-
-* ls - The list to fold
-* z - The initial value
-* f - The function to apply
-"]
+/**
+ * Left fold
+ *
+ * Applies `f` to `u` and the first element in the list, then applies `f` to
+ * the result of the previous call and the second element, and so on,
+ * returning the accumulated result.
+ *
+ * # Arguments
+ *
+ * * ls - The list to fold
+ * * z - The initial value
+ * * f - The function to apply
+ */
 fn foldl<T: copy, U>(z: T, ls: @list<U>, f: fn(T, U) -> T) -> T {
     let mut accum: T = z;
     do iter(ls) |elt| { accum = f(accum, elt);}
     accum
 }
 
-#[doc = "
-Search for an element that matches a given predicate
-
-Apply function `f` to each element of `v`, starting from the first.
-When function `f` returns true then an option containing the element
-is returned. If `f` matches no elements then none is returned.
-"]
+/**
+ * Search for an element that matches a given predicate
+ *
+ * Apply function `f` to each element of `v`, starting from the first.
+ * When function `f` returns true then an option containing the element
+ * is returned. If `f` matches no elements then none is returned.
+ */
 fn find<T: copy>(ls: @list<T>, f: fn(T) -> bool) -> option<T> {
     let mut ls = ls;
     loop {
@@ -53,7 +53,7 @@ fn find<T: copy>(ls: @list<T>, f: fn(T) -> bool) -> option<T> {
     };
 }
 
-#[doc = "Returns true if a list contains an element with the given value"]
+/// Returns true if a list contains an element with the given value
 fn has<T: copy>(ls: @list<T>, elt: T) -> bool {
     for each(ls) |e| {
         if e == elt { ret true; }
@@ -61,7 +61,7 @@ fn has<T: copy>(ls: @list<T>, elt: T) -> bool {
     ret false;
 }
 
-#[doc = "Returns true if the list is empty"]
+/// Returns true if the list is empty
 pure fn is_empty<T: copy>(ls: @list<T>) -> bool {
     alt *ls {
         nil { true }
@@ -69,19 +69,19 @@ pure fn is_empty<T: copy>(ls: @list<T>) -> bool {
     }
 }
 
-#[doc = "Returns true if the list is not empty"]
+/// Returns true if the list is not empty
 pure fn is_not_empty<T: copy>(ls: @list<T>) -> bool {
     ret !is_empty(ls);
 }
 
-#[doc = "Returns the length of a list"]
+/// Returns the length of a list
 fn len<T>(ls: @list<T>) -> uint {
     let mut count = 0u;
     iter(ls, |_e| count += 1u);
     count
 }
 
-#[doc = "Returns all but the first element of a list"]
+/// Returns all but the first element of a list
 pure fn tail<T: copy>(ls: @list<T>) -> @list<T> {
     alt *ls {
         cons(_, tl) { ret tl; }
@@ -89,12 +89,12 @@ pure fn tail<T: copy>(ls: @list<T>) -> @list<T> {
     }
 }
 
-#[doc = "Returns the first element of a list"]
+/// Returns the first element of a list
 pure fn head<T: copy>(ls: @list<T>) -> T {
     alt check *ls { cons(hd, _) { hd } }
 }
 
-#[doc = "Appends one list to another"]
+/// Appends one list to another
 pure fn append<T: copy>(l: @list<T>, m: @list<T>) -> @list<T> {
     alt *l {
       nil { ret m; }
@@ -102,12 +102,12 @@ pure fn append<T: copy>(l: @list<T>, m: @list<T>) -> @list<T> {
     }
 }
 
-#[doc = "Push an element to the front of a list"]
+/// Push an element to the front of a list
 fn push<T: copy>(&l: list<T>, v: T) {
     l = cons(v, @l);
 }
 
-#[doc = "Iterate over a list"]
+/// Iterate over a list
 fn iter<T>(l: @list<T>, f: fn(T)) {
     let mut cur = l;
     loop {
@@ -121,7 +121,7 @@ fn iter<T>(l: @list<T>, f: fn(T)) {
     }
 }
 
-#[doc = "Iterate over a list"]
+/// Iterate over a list
 fn each<T>(l: @list<T>, f: fn(T) -> bool) {
     let mut cur = l;
     loop {
diff --git a/src/libstd/map.rs b/src/libstd/map.rs
index ddcf15257e0af..46f2ca053ad9d 100644
--- a/src/libstd/map.rs
+++ b/src/libstd/map.rs
@@ -1,4 +1,4 @@
-#[doc = "A map type"];
+//! A map type
 
 import chained::hashmap;
 export hashmap, hashfn, eqfn, set, map, chained, hashmap, str_hash;
@@ -8,65 +8,65 @@ export hash_from_vec, hash_from_strs, hash_from_bytes;
 export hash_from_ints, hash_from_uints;
 export vec_from_set;
 
-#[doc = "
-A function that returns a hash of a value
-
-The hash should concentrate entropy in the lower bits.
-"]
+/**
+ * A function that returns a hash of a value
+ *
+ * The hash should concentrate entropy in the lower bits.
+ */
 type hashfn<K> = fn@(K) -> uint;
 
 type eqfn<K> = fn@(K, K) -> bool;
 
-#[doc = "A convenience type to treat a hashmap as a set"]
+/// A convenience type to treat a hashmap as a set
 type set<K> = hashmap<K, ()>;
 
 type hashmap<K, V> = chained::t<K, V>;
 
 iface map<K, V: copy> {
-    #[doc = "Return the number of elements in the map"]
+    /// Return the number of elements in the map
     fn size() -> uint;
 
-    #[doc = "
-    Add a value to the map.
-
-    If the map already contains a value for the specified key then the
-    original value is replaced.
-
-    Returns true if the key did not already exist in the map
-    "]
+    /**
+     * Add a value to the map.
+     *
+     * If the map already contains a value for the specified key then the
+     * original value is replaced.
+     *
+     * Returns true if the key did not already exist in the map
+     */
     fn insert(+K, +V) -> bool;
 
-    #[doc = "Returns true if the map contains a value for the specified key"]
+    /// Returns true if the map contains a value for the specified key
     fn contains_key(K) -> bool;
 
-    #[doc = "
-    Get the value for the specified key. Fails if the key does not exist in
-    the map.
-    "]
+    /**
+     * Get the value for the specified key. Fails if the key does not exist in
+     * the map.
+     */
     fn get(K) -> V;
 
-    #[doc = "Like get, but as an operator."]
+    /// Like get, but as an operator.
     fn [](K) -> V;
 
-    #[doc = "
-    Get the value for the specified key. If the key does not exist in
-    the map then returns none.
-    "]
+    /**
+     * Get the value for the specified key. If the key does not exist in
+     * the map then returns none.
+     */
     fn find(K) -> option<V>;
 
-    #[doc = "
-    Remove and return a value from the map. If the key does not exist
-    in the map then returns none.
-    "]
+    /**
+     * Remove and return a value from the map. If the key does not exist
+     * in the map then returns none.
+     */
     fn remove(K) -> option<V>;
 
-    #[doc = "Iterate over all the key/value pairs in the map"]
+    /// Iterate over all the key/value pairs in the map
     fn each(fn(K, V) -> bool);
 
-    #[doc = "Iterate over all the keys in the map"]
+    /// Iterate over all the keys in the map
     fn each_key(fn(K) -> bool);
 
-    #[doc = "Iterate over all the values in the map"]
+    /// Iterate over all the values in the map
     fn each_value(fn(V) -> bool);
 }
 
@@ -295,41 +295,37 @@ fn hashmap<K: const, V: copy>(hasher: hashfn<K>, eqer: eqfn<K>)
     chained::mk(hasher, eqer)
 }
 
-#[doc = "Construct a hashmap for string keys"]
+/// Construct a hashmap for string keys
 fn str_hash<V: copy>() -> hashmap<str, V> {
     ret hashmap(str::hash, str::eq);
 }
 
-#[doc = "Construct a hashmap for boxed string keys"]
+/// Construct a hashmap for boxed string keys
 fn box_str_hash<V: copy>() -> hashmap<@str, V> {
     ret hashmap(|x: @str| str::hash(*x), |x,y| str::eq(*x,*y));
 }
 
-#[doc = "Construct a hashmap for byte string keys"]
+/// Construct a hashmap for byte string keys
 fn bytes_hash<V: copy>() -> hashmap<~[u8], V> {
     ret hashmap(vec::u8::hash, vec::u8::eq);
 }
 
-#[doc = "Construct a hashmap for int keys"]
+/// Construct a hashmap for int keys
 fn int_hash<V: copy>() -> hashmap<int, V> {
     ret hashmap(int::hash, int::eq);
 }
 
-#[doc = "Construct a hashmap for uint keys"]
+/// Construct a hashmap for uint keys
 fn uint_hash<V: copy>() -> hashmap<uint, V> {
     ret hashmap(uint::hash, uint::eq);
 }
 
-#[doc = "
-Convenience function for adding keys to a hashmap with nil type keys
-"]
+/// Convenience function for adding keys to a hashmap with nil type keys
 fn set_add<K: const copy>(set: set<K>, key: K) -> bool {
     ret set.insert(key, ());
 }
 
-#[doc = "
-Convert a set into a vector.
-"]
+/// Convert a set into a vector.
 fn vec_from_set<T: copy>(s: set<T>) -> ~[T] {
     let mut v = ~[];
     do s.each_key() |k| {
@@ -339,7 +335,7 @@ fn vec_from_set<T: copy>(s: set<T>) -> ~[T] {
     v
 }
 
-#[doc = "Construct a hashmap from a vector"]
+/// Construct a hashmap from a vector
 fn hash_from_vec<K: const copy, V: copy>(hasher: hashfn<K>, eqer: eqfn<K>,
                                          items: ~[(K, V)]) -> hashmap<K, V> {
     let map = hashmap(hasher, eqer);
@@ -350,22 +346,22 @@ fn hash_from_vec<K: const copy, V: copy>(hasher: hashfn<K>, eqer: eqfn<K>,
     map
 }
 
-#[doc = "Construct a hashmap from a vector with string keys"]
+/// Construct a hashmap from a vector with string keys
 fn hash_from_strs<V: copy>(items: ~[(str, V)]) -> hashmap<str, V> {
     hash_from_vec(str::hash, str::eq, items)
 }
 
-#[doc = "Construct a hashmap from a vector with byte keys"]
+/// Construct a hashmap from a vector with byte keys
 fn hash_from_bytes<V: copy>(items: ~[(~[u8], V)]) -> hashmap<~[u8], V> {
     hash_from_vec(vec::u8::hash, vec::u8::eq, items)
 }
 
-#[doc = "Construct a hashmap from a vector with int keys"]
+/// Construct a hashmap from a vector with int keys
 fn hash_from_ints<V: copy>(items: ~[(int, V)]) -> hashmap<int, V> {
     hash_from_vec(int::hash, int::eq, items)
 }
 
-#[doc = "Construct a hashmap from a vector with uint keys"]
+/// Construct a hashmap from a vector with uint keys
 fn hash_from_uints<V: copy>(items: ~[(uint, V)]) -> hashmap<uint, V> {
     hash_from_vec(uint::hash, uint::eq, items)
 }
diff --git a/src/libstd/net.rs b/src/libstd/net.rs
index 11425c2b61233..8b71de2632eee 100644
--- a/src/libstd/net.rs
+++ b/src/libstd/net.rs
@@ -1,6 +1,4 @@
-#[doc="
-Top-level module for network-related functionality
-"];
+//! Top-level module for network-related functionality
 
 import tcp = net_tcp;
 export tcp;
diff --git a/src/libstd/net_ip.rs b/src/libstd/net_ip.rs
index bd1266e10d370..2353a983dc2bd 100644
--- a/src/libstd/net_ip.rs
+++ b/src/libstd/net_ip.rs
@@ -1,6 +1,4 @@
-#[doc="
-Types/fns concerning Internet Protocol (IP), versions 4 & 6
-"];
+//! Types/fns concerning Internet Protocol (IP), versions 4 & 6
 
 import vec;
 import uint;
@@ -28,27 +26,25 @@ export format_addr;
 export v4, v6;
 export get_addr;
 
-#[doc = "An IP address"]
+/// An IP address
 enum ip_addr {
-    #[doc="An IPv4 address"]
+    /// An IPv4 address
     ipv4(sockaddr_in),
     ipv6(sockaddr_in6)
 }
 
-#[doc="
-Human-friendly feedback on why a parse_addr attempt failed
-"]
+/// Human-friendly feedback on why a parse_addr attempt failed
 type parse_addr_err = {
     err_msg: str
 };
 
-#[doc="
-Convert a `ip_addr` to a str
-
-# Arguments
-
-* ip - a `std::net::ip::ip_addr`
-"]
+/**
+ * Convert a `ip_addr` to a str
+ *
+ * # Arguments
+ *
+ * * ip - a `std::net::ip::ip_addr`
+ */
 fn format_addr(ip: ip_addr) -> str {
     alt ip {
       ipv4(addr) {
@@ -72,27 +68,25 @@ fn format_addr(ip: ip_addr) -> str {
     }
 }
 
-#[doc="
-Represents errors returned from `net::ip::get_addr()`
-"]
+/// Represents errors returned from `net::ip::get_addr()`
 enum ip_get_addr_err {
     get_addr_unknown_error
 }
 
-#[doc="
-Attempts name resolution on the provided `node` string
-
-# Arguments
-
-* `node` - a string representing some host address
-* `iotask` - a `uv::iotask` used to interact with the underlying event loop
-
-# Returns
-
-A `result<[ip_addr]/~, ip_get_addr_err>` instance that will contain
-a vector of `ip_addr` results, in the case of success, or an error
-object in the case of failure
-"]
+/**
+ * Attempts name resolution on the provided `node` string
+ *
+ * # Arguments
+ *
+ * * `node` - a string representing some host address
+ * * `iotask` - a `uv::iotask` used to interact with the underlying event loop
+ *
+ * # Returns
+ *
+ * A `result<[ip_addr]/~, ip_get_addr_err>` instance that will contain
+ * a vector of `ip_addr` results, in the case of success, or an error
+ * object in the case of failure
+ */
 fn get_addr(++node: str, iotask: iotask)
         -> result::result<[ip_addr]/~, ip_get_addr_err> unsafe {
     do comm::listen |output_ch| {
@@ -127,21 +121,21 @@ fn get_addr(++node: str, iotask: iotask)
 }
 
 mod v4 {
-    #[doc = "
-    Convert a str to `ip_addr`
-
-    # Failure
-
-    Fails if the string is not a valid IPv4 address
-
-    # Arguments
-
-    * ip - a string of the format `x.x.x.x`
-
-    # Returns
-
-    * an `ip_addr` of the `ipv4` variant
-    "]
+    /**
+     * Convert a str to `ip_addr`
+     *
+     * # Failure
+     *
+     * Fails if the string is not a valid IPv4 address
+     *
+     * # Arguments
+     *
+     * * ip - a string of the format `x.x.x.x`
+     *
+     * # Returns
+     *
+     * * an `ip_addr` of the `ipv4` variant
+     */
     fn parse_addr(ip: str) -> ip_addr {
         alt try_parse_addr(ip) {
           result::ok(addr) { copy(addr) }
@@ -210,21 +204,21 @@ mod v4 {
     }
 }
 mod v6 {
-    #[doc = "
-    Convert a str to `ip_addr`
-
-    # Failure
-
-    Fails if the string is not a valid IPv6 address
-
-    # Arguments
-
-    * ip - an ipv6 string. See RFC2460 for spec.
-
-    # Returns
-
-    * an `ip_addr` of the `ipv6` variant
-    "]
+    /**
+     * Convert a str to `ip_addr`
+     *
+     * # Failure
+     *
+     * Fails if the string is not a valid IPv6 address
+     *
+     * # Arguments
+     *
+     * * ip - an ipv6 string. See RFC2460 for spec.
+     *
+     * # Returns
+     *
+     * * an `ip_addr` of the `ipv6` variant
+     */
     fn parse_addr(ip: str) -> ip_addr {
         alt try_parse_addr(ip) {
           result::ok(addr) { copy(addr) }
diff --git a/src/libstd/net_tcp.rs b/src/libstd/net_tcp.rs
index f847896e934d8..0579e432e6fb3 100644
--- a/src/libstd/net_tcp.rs
+++ b/src/libstd/net_tcp.rs
@@ -1,6 +1,4 @@
-#[doc="
-High-level interface to libuv's TCP functionality
-"];
+//! High-level interface to libuv's TCP functionality
 
 import ip = net_ip;
 import uv::iotask;
@@ -34,13 +32,13 @@ extern mod rustrt {
     fn rust_uv_helper_uv_tcp_t_size() -> libc::c_uint;
 }
 
-#[doc="
-Encapsulates an open TCP/IP connection through libuv
-
-`tcp_socket` is non-copyable/sendable and automagically handles closing the
-underlying libuv data structures when it goes out of scope. This is the
-data structure that is used for read/write operations over a TCP stream.
-"]
+/**
+ * Encapsulates an open TCP/IP connection through libuv
+ *
+ * `tcp_socket` is non-copyable/sendable and automagically handles closing the
+ * underlying libuv data structures when it goes out of scope. This is the
+ * data structure that is used for read/write operations over a TCP stream.
+ */
 class tcp_socket {
   let socket_data: @tcp_socket_data;
   new(socket_data: @tcp_socket_data) { self.socket_data = socket_data; }
@@ -51,84 +49,76 @@ class tcp_socket {
   }
 }
 
-#[doc="
-A buffered wrapper for `net::tcp::tcp_socket`
-
-It is created with a call to `net::tcp::socket_buf()` and has impls that
-satisfy both the `io::reader` and `io::writer` ifaces.
-"]
+/**
+ * A buffered wrapper for `net::tcp::tcp_socket`
+ *
+ * It is created with a call to `net::tcp::socket_buf()` and has impls that
+ * satisfy both the `io::reader` and `io::writer` ifaces.
+ */
 class tcp_socket_buf {
   let data: @tcp_buffered_socket_data;
   new(data: @tcp_buffered_socket_data) { self.data = data; }
 }
 
-#[doc="
-Contains raw, string-based, error information returned from libuv
-"]
+/// Contains raw, string-based, error information returned from libuv
 type tcp_err_data = {
     err_name: str,
     err_msg: str
 };
-#[doc="
-Details returned as part of a `result::err` result from `tcp::listen`
-"]
+/// Details returned as part of a `result::err` result from `tcp::listen`
 enum tcp_listen_err_data {
-    #[doc="
-    Some unplanned-for error. The first and second fields correspond
-    to libuv's `err_name` and `err_msg` fields, respectively.
-    "]
+    /**
+     * Some unplanned-for error. The first and second fields correspond
+     * to libuv's `err_name` and `err_msg` fields, respectively.
+     */
     generic_listen_err(str, str),
-    #[doc="
-    Failed to bind to the requested IP/Port, because it is already in use.
-
-    # Possible Causes
-
-    * Attempting to bind to a port already bound to another listener
-    "]
+    /**
+     * Failed to bind to the requested IP/Port, because it is already in use.
+     *
+     * # Possible Causes
+     *
+     * * Attempting to bind to a port already bound to another listener
+     */
     address_in_use,
-    #[doc="
-    Request to bind to an IP/Port was denied by the system.
-
-    # Possible Causes
-
-    * Attemping to binding to an IP/Port as a non-Administrator
-      on Windows Vista+
-    * Attempting to bind, as a non-priv'd
-      user, to 'privileged' ports (< 1024) on *nix
-    "]
+    /**
+     * Request to bind to an IP/Port was denied by the system.
+     *
+     * # Possible Causes
+     *
+     * * Attemping to binding to an IP/Port as a non-Administrator
+     *   on Windows Vista+
+     * * Attempting to bind, as a non-priv'd
+     *   user, to 'privileged' ports (< 1024) on *nix
+     */
     access_denied
 }
-#[doc="
-Details returned as part of a `result::err` result from `tcp::connect`
-"]
+/// Details returned as part of a `result::err` result from `tcp::connect`
 enum tcp_connect_err_data {
-    #[doc="
-    Some unplanned-for error. The first and second fields correspond
-    to libuv's `err_name` and `err_msg` fields, respectively.
-    "]
+    /**
+     * Some unplanned-for error. The first and second fields correspond
+     * to libuv's `err_name` and `err_msg` fields, respectively.
+     */
     generic_connect_err(str, str),
-    #[doc="
-    Invalid IP or invalid port
-    "]
+    /// Invalid IP or invalid port
     connection_refused
 }
 
-#[doc="
-Initiate a client connection over TCP/IP
-
-# Arguments
-
-* `input_ip` - The IP address (versions 4 or 6) of the remote host
-* `port` - the unsigned integer of the desired remote host port
-* `iotask` - a `uv::iotask` that the tcp request will run on
-
-# Returns
-
-A `result` that, if the operation succeeds, contains a `net::net::tcp_socket`
-that can be used to send and receive data to/from the remote host. In the
-event of failure, a `net::tcp::tcp_connect_err_data` instance will be
-returned
-"]
+/**
+ * Initiate a client connection over TCP/IP
+ *
+ * # Arguments
+ *
+ * * `input_ip` - The IP address (versions 4 or 6) of the remote host
+ * * `port` - the unsigned integer of the desired remote host port
+ * * `iotask` - a `uv::iotask` that the tcp request will run on
+ *
+ * # Returns
+ *
+ * A `result` that, if the operation succeeds, contains a
+ * `net::net::tcp_socket` that can be used to send and receive data to/from
+ * the remote host. In the event of failure, a
+ * `net::tcp::tcp_connect_err_data` instance will be returned
+ */
 fn connect(-input_ip: ip::ip_addr, port: uint,
            iotask: iotask)
     -> result::result<tcp_socket, tcp_connect_err_data> unsafe {
@@ -252,56 +242,57 @@ fn connect(-input_ip: ip::ip_addr, port: uint,
     }
 }
 
-#[doc="
-Write binary data to a tcp stream; Blocks until operation completes
-
-# Arguments
-
-* sock - a `tcp_socket` to write to
-* raw_write_data - a vector of `[u8]/~` that will be written to the stream.
-This value must remain valid for the duration of the `write` call
-
-# Returns
-
-A `result` object with a `nil` value as the `ok` variant, or a `tcp_err_data`
-value as the `err` variant
-"]
+/**
+ * Write binary data to a tcp stream; Blocks until operation completes
+ *
+ * # Arguments
+ *
+ * * sock - a `tcp_socket` to write to
+ * * raw_write_data - a vector of `[u8]/~` that will be written to the stream.
+ * This value must remain valid for the duration of the `write` call
+ *
+ * # Returns
+ *
+ * A `result` object with a `nil` value as the `ok` variant, or a
+ * `tcp_err_data` value as the `err` variant
+ */
 fn write(sock: tcp_socket, raw_write_data: ~[u8])
     -> result::result<(), tcp_err_data> unsafe {
     let socket_data_ptr = ptr::addr_of(*(sock.socket_data));
     write_common_impl(socket_data_ptr, raw_write_data)
 }
 
-#[doc="
-Write binary data to tcp stream; Returns a `future::future` value immediately
-
-# Safety
-
-This function can produce unsafe results if:
-
-1. the call to `write_future` is made
-2. the `future::future` value returned is never resolved via
-`future::get`
-3. and then the `tcp_socket` passed in to `write_future` leaves
-scope and is destructed before the task that runs the libuv write
-operation completes.
-
-As such: If using `write_future`, always be sure to resolve the returned
-`future` so as to ensure libuv doesn't try to access a released write handle.
-Otherwise, use the blocking `tcp::write` function instead.
-
-# Arguments
-
-* sock - a `tcp_socket` to write to
-* raw_write_data - a vector of `[u8]/~` that will be written to the stream.
-This value must remain valid for the duration of the `write` call
-
-# Returns
-
-A `future` value that, once the `write` operation completes, resolves to a
-`result` object with a `nil` value as the `ok` variant, or a `tcp_err_data`
-value as the `err` variant
-"]
+/**
+ * Write binary data to tcp stream; Returns a `future::future` value
+ * immediately
+ *
+ * # Safety
+ *
+ * This function can produce unsafe results if:
+ *
+ * 1. the call to `write_future` is made
+ * 2. the `future::future` value returned is never resolved via
+ * `future::get`
+ * 3. and then the `tcp_socket` passed in to `write_future` leaves
+ * scope and is destructed before the task that runs the libuv write
+ * operation completes.
+ *
+ * As such: If using `write_future`, always be sure to resolve the returned
+ * `future` so as to ensure libuv doesn't try to access a released write
+ * handle. Otherwise, use the blocking `tcp::write` function instead.
+ *
+ * # Arguments
+ *
+ * * sock - a `tcp_socket` to write to
+ * * raw_write_data - a vector of `[u8]/~` that will be written to the stream.
+ * This value must remain valid for the duration of the `write` call
+ *
+ * # Returns
+ *
+ * A `future` value that, once the `write` operation completes, resolves to a
+ * `result` object with a `nil` value as the `ok` variant, or a `tcp_err_data`
+ * value as the `err` variant
+ */
 fn write_future(sock: tcp_socket, raw_write_data: ~[u8])
     -> future::future<result::result<(), tcp_err_data>> unsafe {
     let socket_data_ptr = ptr::addr_of(*(sock.socket_data));
@@ -311,19 +302,20 @@ fn write_future(sock: tcp_socket, raw_write_data: ~[u8])
     }
 }
 
-#[doc="
-Begin reading binary data from an open TCP connection; used with `read_stop`
-
-# Arguments
-
-* sock -- a `net::tcp::tcp_socket` for the connection to read from
-
-# Returns
-
-* A `result` instance that will either contain a
-`comm::port<tcp_read_result>` that the user can read (and optionally, loop
-on) from until `read_stop` is called, or a `tcp_err_data` record
-"]
+/**
+ * Begin reading binary data from an open TCP connection; used with
+ * `read_stop`
+ *
+ * # Arguments
+ *
+ * * sock -- a `net::tcp::tcp_socket` for the connection to read from
+ *
+ * # Returns
+ *
+ * * A `result` instance that will either contain a
+ * `comm::port<tcp_read_result>` that the user can read (and optionally, loop
+ * on) from until `read_stop` is called, or a `tcp_err_data` record
+ */
 fn read_start(sock: tcp_socket)
     -> result::result<comm::port<
         result::result<~[u8], tcp_err_data>>, tcp_err_data> unsafe {
@@ -331,13 +323,13 @@ fn read_start(sock: tcp_socket)
     read_start_common_impl(socket_data)
 }
 
-#[doc="
-Stop reading from an open TCP connection; used with `read_start`
-
-# Arguments
-
-* `sock` - a `net::tcp::tcp_socket` that you wish to stop reading on
-"]
+/**
+ * Stop reading from an open TCP connection; used with `read_start`
+ *
+ * # Arguments
+ *
+ * * `sock` - a `net::tcp::tcp_socket` that you wish to stop reading on
+ */
 fn read_stop(sock: tcp_socket,
              -read_port: comm::port<result::result<[u8]/~, tcp_err_data>>) ->
     result::result<(), tcp_err_data> unsafe {
@@ -346,54 +338,56 @@ fn read_stop(sock: tcp_socket,
     read_stop_common_impl(socket_data)
 }
 
-#[doc="
-Reads a single chunk of data from `tcp_socket`; block until data/error recv'd
-
-Does a blocking read operation for a single chunk of data from a `tcp_socket`
-until a data arrives or an error is received. The provided `timeout_msecs`
-value is used to raise an error if the timeout period passes without any
-data received.
-
-# Arguments
-
-* `sock` - a `net::tcp::tcp_socket` that you wish to read from
-* `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
-read attempt. Pass `0u` to wait indefinitely
-"]
+/**
+ * Reads a single chunk of data from `tcp_socket`; block until data/error
+ * recv'd
+ *
+ * Does a blocking read operation for a single chunk of data from a
+ * `tcp_socket` until a data arrives or an error is received. The provided
+ * `timeout_msecs` value is used to raise an error if the timeout period
+ * passes without any data received.
+ *
+ * # Arguments
+ *
+ * * `sock` - a `net::tcp::tcp_socket` that you wish to read from
+ * * `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
+ * read attempt. Pass `0u` to wait indefinitely
+ */
 fn read(sock: tcp_socket, timeout_msecs: uint)
     -> result::result<~[u8],tcp_err_data> {
     let socket_data = ptr::addr_of(*(sock.socket_data));
     read_common_impl(socket_data, timeout_msecs)
 }
 
-#[doc="
-Reads a single chunk of data; returns a `future::future<[u8]/~>` immediately
-
-Does a non-blocking read operation for a single chunk of data from a
-`tcp_socket` and immediately returns a `future` value representing the
-result. When resolving the returned `future`, it will block until data
-arrives or an error is received. The provided `timeout_msecs`
-value is used to raise an error if the timeout period passes without any
-data received.
-
-# Safety
-
-This function can produce unsafe results if the call to `read_future` is
-made, the `future::future` value returned is never resolved via
-`future::get`, and then the `tcp_socket` passed in to `read_future` leaves
-scope and is destructed before the task that runs the libuv read
-operation completes.
-
-As such: If using `read_future`, always be sure to resolve the returned
-`future` so as to ensure libuv doesn't try to access a released read handle.
-Otherwise, use the blocking `tcp::read` function instead.
-
-# Arguments
-
-* `sock` - a `net::tcp::tcp_socket` that you wish to read from
-* `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
-read attempt. Pass `0u` to wait indefinitely
-"]
+/**
+ * Reads a single chunk of data; returns a `future::future<[u8]/~>`
+ * immediately
+ *
+ * Does a non-blocking read operation for a single chunk of data from a
+ * `tcp_socket` and immediately returns a `future` value representing the
+ * result. When resolving the returned `future`, it will block until data
+ * arrives or an error is received. The provided `timeout_msecs`
+ * value is used to raise an error if the timeout period passes without any
+ * data received.
+ *
+ * # Safety
+ *
+ * This function can produce unsafe results if the call to `read_future` is
+ * made, the `future::future` value returned is never resolved via
+ * `future::get`, and then the `tcp_socket` passed in to `read_future` leaves
+ * scope and is destructed before the task that runs the libuv read
+ * operation completes.
+ *
+ * As such: If using `read_future`, always be sure to resolve the returned
+ * `future` so as to ensure libuv doesn't try to access a released read
+ * handle. Otherwise, use the blocking `tcp::read` function instead.
+ *
+ * # Arguments
+ *
+ * * `sock` - a `net::tcp::tcp_socket` that you wish to read from
+ * * `timeout_msecs` - a `uint` value, in msecs, to wait before dropping the
+ * read attempt. Pass `0u` to wait indefinitely
+ */
 fn read_future(sock: tcp_socket, timeout_msecs: uint)
     -> future::future<result::result<~[u8],tcp_err_data>> {
     let socket_data = ptr::addr_of(*(sock.socket_data));
@@ -402,75 +396,75 @@ fn read_future(sock: tcp_socket, timeout_msecs: uint)
     }
 }
 
-#[doc="
-Bind an incoming client connection to a `net::tcp::tcp_socket`
-
-# Notes
-
-It is safe to call `net::tcp::accept` _only_ within the context of the
-`new_connect_cb` callback provided as the final argument to the
-`net::tcp::listen` function.
-
-The `new_conn` opaque value is provided _only_ as the first argument to the
-`new_connect_cb` provided as a part of `net::tcp::listen`.
-It can be safely sent to another task but it _must_ be
-used (via `net::tcp::accept`) before the `new_connect_cb` call it was
-provided to returns.
-
-This implies that a port/chan pair must be used to make sure that the
-`new_connect_cb` call blocks until an attempt to create a
-`net::tcp::tcp_socket` is completed.
-
-# Example
-
-Here, the `new_conn` is used in conjunction with `accept` from within
-a task spawned by the `new_connect_cb` passed into `listen`
-
-~~~~~~~~~~~
-net::tcp::listen(remote_ip, remote_port, backlog)
-    // this callback is ran once after the connection is successfully
-    // set up
-    {|kill_ch|
-      // pass the kill_ch to your main loop or wherever you want
-      // to be able to externally kill the server from
-    }
-    // this callback is ran when a new connection arrives
-    {|new_conn, kill_ch|
-    let cont_po = comm::port::<option<tcp_err_data>>();
-    let cont_ch = comm::chan(cont_po);
-    task::spawn {||
-        let accept_result = net::tcp::accept(new_conn);
-        if accept_result.is_err() {
-            comm::send(cont_ch, result::get_err(accept_result));
-            // fail?
-        }
-        else {
-            let sock = result::get(accept_result);
-            comm::send(cont_ch, true);
-            // do work here
-        }
-    };
-    alt comm::recv(cont_po) {
-      // shut down listen()
-      some(err_data) { comm::send(kill_chan, some(err_data)) }
-      // wait for next connection
-      none {}
-    }
-};
-~~~~~~~~~~~
-
-# Arguments
-
-* `new_conn` - an opaque value used to create a new `tcp_socket`
-
-# Returns
-
-On success, this function will return a `net::tcp::tcp_socket` as the
-`ok` variant of a `result`. The `net::tcp::tcp_socket` is anchored within
-the task that `accept` was called within for its lifetime. On failure,
-this function will return a `net::tcp::tcp_err_data` record
-as the `err` variant of a `result`.
-"]
+/**
+ * Bind an incoming client connection to a `net::tcp::tcp_socket`
+ *
+ * # Notes
+ *
+ * It is safe to call `net::tcp::accept` _only_ within the context of the
+ * `new_connect_cb` callback provided as the final argument to the
+ * `net::tcp::listen` function.
+ *
+ * The `new_conn` opaque value is provided _only_ as the first argument to the
+ * `new_connect_cb` provided as a part of `net::tcp::listen`.
+ * It can be safely sent to another task but it _must_ be
+ * used (via `net::tcp::accept`) before the `new_connect_cb` call it was
+ * provided to returns.
+ *
+ * This implies that a port/chan pair must be used to make sure that the
+ * `new_connect_cb` call blocks until an attempt to create a
+ * `net::tcp::tcp_socket` is completed.
+ *
+ * # Example
+ *
+ * Here, the `new_conn` is used in conjunction with `accept` from within
+ * a task spawned by the `new_connect_cb` passed into `listen`
+ *
+ * ~~~~~~~~~~~
+ * net::tcp::listen(remote_ip, remote_port, backlog)
+ *     // this callback is ran once after the connection is successfully
+ *     // set up
+ *     {|kill_ch|
+ *       // pass the kill_ch to your main loop or wherever you want
+ *       // to be able to externally kill the server from
+ *     }
+ *     // this callback is ran when a new connection arrives
+ *     {|new_conn, kill_ch|
+ *     let cont_po = comm::port::<option<tcp_err_data>>();
+ *     let cont_ch = comm::chan(cont_po);
+ *     task::spawn {||
+ *         let accept_result = net::tcp::accept(new_conn);
+ *         if accept_result.is_err() {
+ *             comm::send(cont_ch, result::get_err(accept_result));
+ *             // fail?
+ *         }
+ *         else {
+ *             let sock = result::get(accept_result);
+ *             comm::send(cont_ch, true);
+ *             // do work here
+ *         }
+ *     };
+ *     alt comm::recv(cont_po) {
+ *       // shut down listen()
+ *       some(err_data) { comm::send(kill_chan, some(err_data)) }
+ *       // wait for next connection
+ *       none {}
+ *     }
+ * };
+ * ~~~~~~~~~~~
+ *
+ * # Arguments
+ *
+ * * `new_conn` - an opaque value used to create a new `tcp_socket`
+ *
+ * # Returns
+ *
+ * On success, this function will return a `net::tcp::tcp_socket` as the
+ * `ok` variant of a `result`. The `net::tcp::tcp_socket` is anchored within
+ * the task that `accept` was called within for its lifetime. On failure,
+ * this function will return a `net::tcp::tcp_err_data` record
+ * as the `err` variant of a `result`.
+ */
 fn accept(new_conn: tcp_new_connection)
     -> result::result<tcp_socket, tcp_err_data> unsafe {
 
@@ -545,34 +539,34 @@ fn accept(new_conn: tcp_new_connection)
     }
 }
 
-#[doc="
-Bind to a given IP/port and listen for new connections
-
-# Arguments
-
-* `host_ip` - a `net::ip::ip_addr` representing a unique IP
-(versions 4 or 6)
-* `port` - a uint representing the port to listen on
-* `backlog` - a uint representing the number of incoming connections
-to cache in memory
-* `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
-* `on_establish_cb` - a callback that is evaluated if/when the listener
-is successfully established. it takes no parameters
-* `new_connect_cb` - a callback to be evaluated, on the libuv thread,
-whenever a client attempts to conect on the provided ip/port. the
-callback's arguments are:
-    * `new_conn` - an opaque type that can be passed to
-    `net::tcp::accept` in order to be converted to a `tcp_socket`.
-    * `kill_ch` - channel of type `comm::chan<option<tcp_err_data>>`. this
-    channel can be used to send a message to cause `listen` to begin
-    closing the underlying libuv data structures.
-
-# returns
-
-a `result` instance containing empty data of type `()` on a
-successful/normal shutdown, and a `tcp_listen_err_data` enum in the event
-of listen exiting because of an error
-"]
+/**
+ * Bind to a given IP/port and listen for new connections
+ *
+ * # Arguments
+ *
+ * * `host_ip` - a `net::ip::ip_addr` representing a unique IP
+ * (versions 4 or 6)
+ * * `port` - a uint representing the port to listen on
+ * * `backlog` - a uint representing the number of incoming connections
+ * to cache in memory
+ * * `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
+ * * `on_establish_cb` - a callback that is evaluated if/when the listener
+ * is successfully established. it takes no parameters
+ * * `new_connect_cb` - a callback to be evaluated, on the libuv thread,
+ * whenever a client attempts to conect on the provided ip/port. the
+ * callback's arguments are:
+ *     * `new_conn` - an opaque type that can be passed to
+ *     `net::tcp::accept` in order to be converted to a `tcp_socket`.
+ *     * `kill_ch` - channel of type `comm::chan<option<tcp_err_data>>`. this
+ *     channel can be used to send a message to cause `listen` to begin
+ *     closing the underlying libuv data structures.
+ *
+ * # returns
+ *
+ * a `result` instance containing empty data of type `()` on a
+ * successful/normal shutdown, and a `tcp_listen_err_data` enum in the event
+ * of listen exiting because of an error
+ */
 fn listen(-host_ip: ip::ip_addr, port: uint, backlog: uint,
           iotask: iotask,
           on_establish_cb: fn~(comm::chan<option<tcp_err_data>>),
@@ -721,28 +715,26 @@ fn listen_common(-host_ip: ip::ip_addr, port: uint, backlog: uint,
     }
 }
 
-#[doc="
-Convert a `net::tcp::tcp_socket` to a `net::tcp::tcp_socket_buf`.
-
-This function takes ownership of a `net::tcp::tcp_socket`, returning it
-stored within a buffered wrapper, which can be converted to a `io::reader`
-or `io::writer`
-
-# Arguments
-
-* `sock` -- a `net::tcp::tcp_socket` that you want to buffer
-
-# Returns
-
-A buffered wrapper that you can cast as an `io::reader` or `io::writer`
-"]
+/**
+ * Convert a `net::tcp::tcp_socket` to a `net::tcp::tcp_socket_buf`.
+ *
+ * This function takes ownership of a `net::tcp::tcp_socket`, returning it
+ * stored within a buffered wrapper, which can be converted to a `io::reader`
+ * or `io::writer`
+ *
+ * # Arguments
+ *
+ * * `sock` -- a `net::tcp::tcp_socket` that you want to buffer
+ *
+ * # Returns
+ *
+ * A buffered wrapper that you can cast as an `io::reader` or `io::writer`
+ */
 fn socket_buf(-sock: tcp_socket) -> tcp_socket_buf {
     tcp_socket_buf(@{ sock: sock, mut buf: []/~ })
 }
 
-#[doc="
-Convenience methods extending `net::tcp::tcp_socket`
-"]
+/// Convenience methods extending `net::tcp::tcp_socket`
 impl tcp_socket for tcp_socket {
     fn read_start() -> result::result<comm::port<
         result::result<~[u8], tcp_err_data>>, tcp_err_data> {
@@ -771,9 +763,7 @@ impl tcp_socket for tcp_socket {
     }
 }
 
-#[doc="
-Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
-"]
+/// Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
 impl tcp_socket_buf of io::reader for @tcp_socket_buf {
     fn read_bytes(amt: uint) -> [u8]/~ {
         let has_amt_available =
@@ -819,9 +809,7 @@ impl tcp_socket_buf of io::reader for @tcp_socket_buf {
     }
 }
 
-#[doc="
-Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
-"]
+/// Implementation of `io::reader` iface for a buffered `net::tcp::tcp_socket`
 impl tcp_socket_buf of io::writer for @tcp_socket_buf {
     fn write(data: [const u8]/&) unsafe {
         let socket_data_ptr =
diff --git a/src/libstd/par.rs b/src/libstd/par.rs
index 167eded03cbac..9bf6a0212828a 100644
--- a/src/libstd/par.rs
+++ b/src/libstd/par.rs
@@ -8,18 +8,22 @@ import core::vec::extensions;
 
 export map, mapi, alli, any, mapi_factory;
 
-#[doc="The maximum number of tasks this module will spawn for a single
-operation."]
+/**
+ * The maximum number of tasks this module will spawn for a single
+ * operation.
+ */
 const max_tasks : uint = 32u;
 
-#[doc="The minimum number of elements each task will process."]
+/// The minimum number of elements each task will process.
 const min_granularity : uint = 1024u;
 
-#[doc="An internal helper to map a function over a large vector and
-return the intermediate results.
-
-This is used to build most of the other parallel vector functions,
-like map or alli."]
+/**
+ * An internal helper to map a function over a large vector and
+ * return the intermediate results.
+ *
+ * This is used to build most of the other parallel vector functions,
+ * like map or alli.
+ */
 fn map_slices<A: copy send, B: copy send>(
     xs: ~[A],
     f: fn() -> fn~(uint, v: &[A]) -> B)
@@ -75,7 +79,7 @@ fn map_slices<A: copy send, B: copy send>(
     }
 }
 
-#[doc="A parallel version of map."]
+/// A parallel version of map.
 fn map<A: copy send, B: copy send>(xs: ~[A], f: fn~(A) -> B) -> ~[B] {
     vec::concat(map_slices(xs, || {
         fn~(_base: uint, slice : &[A], copy f) -> ~[B] {
@@ -84,7 +88,7 @@ fn map<A: copy send, B: copy send>(xs: ~[A], f: fn~(A) -> B) -> ~[B] {
     }))
 }
 
-#[doc="A parallel version of mapi."]
+/// A parallel version of mapi.
 fn mapi<A: copy send, B: copy send>(xs: ~[A],
                                     f: fn~(uint, A) -> B) -> ~[B] {
     let slices = map_slices(xs, || {
@@ -100,10 +104,12 @@ fn mapi<A: copy send, B: copy send>(xs: ~[A],
     r
 }
 
-#[doc="A parallel version of mapi.
-
-In this case, f is a function that creates functions to run over the
-inner elements. This is to skirt the need for copy constructors."]
+/**
+ * A parallel version of mapi.
+ *
+ * In this case, f is a function that creates functions to run over the
+ * inner elements. This is to skirt the need for copy constructors.
+ */
 fn mapi_factory<A: copy send, B: copy send>(
     xs: ~[A], f: fn() -> fn~(uint, A) -> B) -> ~[B] {
     let slices = map_slices(xs, || {
@@ -120,7 +126,7 @@ fn mapi_factory<A: copy send, B: copy send>(
     r
 }
 
-#[doc="Returns true if the function holds for all elements in the vector."]
+/// Returns true if the function holds for all elements in the vector.
 fn alli<A: copy send>(xs: ~[A], f: fn~(uint, A) -> bool) -> bool {
     do vec::all(map_slices(xs, || {
         fn~(base: uint, slice : &[A], copy f) -> bool {
@@ -131,7 +137,7 @@ fn alli<A: copy send>(xs: ~[A], f: fn~(uint, A) -> bool) -> bool {
     })) |x| { x }
 }
 
-#[doc="Returns true if the function holds for any elements in the vector."]
+/// Returns true if the function holds for any elements in the vector.
 fn any<A: copy send>(xs: ~[A], f: fn~(A) -> bool) -> bool {
     do vec::any(map_slices(xs, || {
         fn~(_base : uint, slice: &[A], copy f) -> bool {
diff --git a/src/libstd/rope.rs b/src/libstd/rope.rs
index a7d54daba9a3d..1a90612869bdc 100644
--- a/src/libstd/rope.rs
+++ b/src/libstd/rope.rs
@@ -1,84 +1,84 @@
-#[doc = "
-High-level text containers.
-
-Ropes are a high-level representation of text that offers
-much better performance than strings for common operations,
-and generally reduce memory allocations and copies, while only
-entailing a small degradation of less common operations.
-
-More precisely, where a string is represented as a memory buffer,
-a rope is a tree structure whose leaves are slices of immutable
-strings. Therefore, concatenation, appending, prepending, substrings,
-etc. are operations that require only trivial tree manipulation,
-generally without having to copy memory. In addition, the tree
-structure of ropes makes them suitable as a form of index to speed-up
-access to Unicode characters by index in long chunks of text.
-
-The following operations are algorithmically faster in ropes:
-
-* extracting a subrope is logarithmic (linear in strings);
-* appending/prepending is near-constant time (linear in strings);
-* concatenation is near-constant time (linear in strings);
-* char length is constant-time (linear in strings);
-* access to a character by index is logarithmic (linear in strings);
-"];
+/*!
+ * High-level text containers.
+ *
+ * Ropes are a high-level representation of text that offers
+ * much better performance than strings for common operations,
+ * and generally reduce memory allocations and copies, while only
+ * entailing a small degradation of less common operations.
+ *
+ * More precisely, where a string is represented as a memory buffer,
+ * a rope is a tree structure whose leaves are slices of immutable
+ * strings. Therefore, concatenation, appending, prepending, substrings,
+ * etc. are operations that require only trivial tree manipulation,
+ * generally without having to copy memory. In addition, the tree
+ * structure of ropes makes them suitable as a form of index to speed-up
+ * access to Unicode characters by index in long chunks of text.
+ *
+ * The following operations are algorithmically faster in ropes:
+ *
+ * * extracting a subrope is logarithmic (linear in strings);
+ * * appending/prepending is near-constant time (linear in strings);
+ * * concatenation is near-constant time (linear in strings);
+ * * char length is constant-time (linear in strings);
+ * * access to a character by index is logarithmic (linear in strings);
+ */
 
 
-#[doc = "The type of ropes."]
+/// The type of ropes.
 type rope = node::root;
 
 /*
  Section: Creating a rope
  */
 
-#[doc = "Create an empty rope"]
+/// Create an empty rope
 fn empty() -> rope {
    ret node::empty;
 }
 
-#[doc = "
-Adopt a string as a rope.
-
-# Arguments
-
-* str - A valid string.
-
-# Return value
-
-A rope representing the same string as `str`. Depending of the length
-of `str`, this rope may be empty, flat or complex.
-
-# Performance notes
-
-* this operation does not copy the string;
-* the function runs in linear time.
-"]
+/**
+ * Adopt a string as a rope.
+ *
+ * # Arguments
+ *
+ * * str - A valid string.
+ *
+ * # Return value
+ *
+ * A rope representing the same string as `str`. Depending of the length
+ * of `str`, this rope may be empty, flat or complex.
+ *
+ * # Performance notes
+ *
+ * * this operation does not copy the string;
+ * * the function runs in linear time.
+ */
 fn of_str(str: @str) -> rope {
     ret of_substr(str, 0u, str::len(*str));
 }
 
-#[doc = "
-As `of_str` but for a substring.
-
-# Arguments
-* byte_offset - The offset of `str` at which the rope starts.
-* byte_len - The number of bytes of `str` to use.
-
-# Return value
-
-A rope representing the same string as `str::substr(str, byte_offset,
-byte_len)`.  Depending on `byte_len`, this rope may be empty, flat or
-complex.
-
-# Performance note
-
-This operation does not copy the substring.
-
-# Safety notes
-
-* this function does _not_ check the validity of the substring;
-* this function fails if `byte_offset` or `byte_len` do not match `str`.
-"]
+/**
+ * As `of_str` but for a substring.
+ *
+ * # Arguments
+ * * byte_offset - The offset of `str` at which the rope starts.
+ * * byte_len - The number of bytes of `str` to use.
+ *
+ * # Return value
+ *
+ * A rope representing the same string as `str::substr(str, byte_offset,
+ * byte_len)`.  Depending on `byte_len`, this rope may be empty, flat or
+ * complex.
+ *
+ * # Performance note
+ *
+ * This operation does not copy the substring.
+ *
+ * # Safety notes
+ *
+ * * this function does _not_ check the validity of the substring;
+ * * this function fails if `byte_offset` or `byte_len` do not match `str`.
+ */
 fn of_substr(str: @str, byte_offset: uint, byte_len: uint) -> rope {
     if byte_len == 0u { ret node::empty; }
     if byte_offset + byte_len  > str::len(*str) { fail; }
@@ -89,49 +89,49 @@ fn of_substr(str: @str, byte_offset: uint, byte_len: uint) -> rope {
 Section: Adding things to a rope
  */
 
-#[doc = "
-Add one char to the end of the rope
-
-# Performance note
-
-* this function executes in near-constant time
-"]
+/**
+ * Add one char to the end of the rope
+ *
+ * # Performance note
+ *
+ * * this function executes in near-constant time
+ */
 fn append_char(rope: rope, char: char) -> rope {
     ret append_str(rope, @str::from_chars(~[char]));
 }
 
-#[doc = "
-Add one string to the end of the rope
-
-# Performance note
-
-* this function executes in near-linear time
-"]
+/**
+ * Add one string to the end of the rope
+ *
+ * # Performance note
+ *
+ * * this function executes in near-linear time
+ */
 fn append_str(rope: rope, str: @str) -> rope {
     ret append_rope(rope, of_str(str))
 }
 
-#[doc = "
-Add one char to the beginning of the rope
-
-# Performance note
-* this function executes in near-constant time
-"]
+/**
+ * Add one char to the beginning of the rope
+ *
+ * # Performance note
+ * * this function executes in near-constant time
+ */
 fn prepend_char(rope: rope, char: char) -> rope {
     ret prepend_str(rope, @str::from_chars(~[char]));
 }
 
-#[doc = "
-Add one string to the beginning of the rope
-
-# Performance note
-* this function executes in near-linear time
-"]
+/**
+ * Add one string to the beginning of the rope
+ *
+ * # Performance note
+ * * this function executes in near-linear time
+ */
 fn prepend_str(rope: rope, str: @str) -> rope {
     ret append_rope(of_str(str), rope)
 }
 
-#[doc = "Concatenate two ropes"]
+/// Concatenate two ropes
 fn append_rope(left: rope, right: rope) -> rope {
    alt(left) {
      node::empty { ret right; }
@@ -146,13 +146,13 @@ fn append_rope(left: rope, right: rope) -> rope {
    }
 }
 
-#[doc = "
-Concatenate many ropes.
-
-If the ropes are balanced initially and have the same height, the resulting
-rope remains balanced. However, this function does not take any further
-measure to ensure that the result is balanced.
-"]
+/**
+ * Concatenate many ropes.
+ *
+ * If the ropes are balanced initially and have the same height, the resulting
+ * rope remains balanced. However, this function does not take any further
+ * measure to ensure that the result is balanced.
+ */
 fn concat(v: ~[rope]) -> rope {
     //Copy `v` into a mut vector
     let mut len = vec::len(v);
@@ -185,17 +185,17 @@ Section: Keeping ropes healthy
  */
 
 
-#[doc = "
-Balance a rope.
-
-# Return value
-
-A copy of the rope in which small nodes have been grouped in memory,
-and with a reduced height.
-
-If you perform numerous rope concatenations, it is generally a good idea
-to rebalance your rope at some point, before using it for other purposes.
-"]
+/**
+ * Balance a rope.
+ *
+ * # Return value
+ *
+ * A copy of the rope in which small nodes have been grouped in memory,
+ * and with a reduced height.
+ *
+ * If you perform numerous rope concatenations, it is generally a good idea
+ * to rebalance your rope at some point, before using it for other purposes.
+ */
 fn bal(rope:rope) -> rope {
     alt(rope) {
       node::empty { ret rope }
@@ -213,19 +213,19 @@ Section: Transforming ropes
  */
 
 
-#[doc = "
-Extract a subrope from a rope.
-
-# Performance note
-
-* on a balanced rope, this operation takes algorithmic time;
-* this operation does not involve any copying
-
-# Safety note
-
-* this function fails if char_offset/char_len do not represent
-  valid positions in rope
-"]
+/**
+ * Extract a subrope from a rope.
+ *
+ * # Performance note
+ *
+ * * on a balanced rope, this operation takes algorithmic time;
+ * * this operation does not involve any copying
+ *
+ * # Safety note
+ *
+ * * this function fails if char_offset/char_len do not represent
+ *   valid positions in rope
+ */
 fn sub_chars(rope: rope, char_offset: uint, char_len: uint) -> rope {
     if char_len == 0u { ret node::empty; }
     alt(rope) {
@@ -239,19 +239,19 @@ fn sub_chars(rope: rope, char_offset: uint, char_len: uint) -> rope {
     }
 }
 
-#[doc = "
-Extract a subrope from a rope.
-
-# Performance note
-
-* on a balanced rope, this operation takes algorithmic time;
-* this operation does not involve any copying
-
-# Safety note
-
-* this function fails if byte_offset/byte_len do not represent
-  valid positions in rope
-"]
+/**
+ * Extract a subrope from a rope.
+ *
+ * # Performance note
+ *
+ * * on a balanced rope, this operation takes algorithmic time;
+ * * this operation does not involve any copying
+ *
+ * # Safety note
+ *
+ * * this function fails if byte_offset/byte_len do not represent
+ *   valid positions in rope
+ */
 fn sub_bytes(rope: rope, byte_offset: uint, byte_len: uint) -> rope {
     if byte_len == 0u { ret node::empty; }
     alt(rope) {
@@ -269,16 +269,16 @@ fn sub_bytes(rope: rope, byte_offset: uint, byte_len: uint) -> rope {
 Section: Comparing ropes
  */
 
-#[doc = "
-Compare two ropes by Unicode lexicographical order.
-
-This function compares only the contents of the rope, not their structure.
-
-# Return value
-
-A negative value if `left < right`, 0 if eq(left, right) or a positive
-value if `left > right`
-"]
+/**
+ * Compare two ropes by Unicode lexicographical order.
+ *
+ * This function compares only the contents of the rope, not their structure.
+ *
+ * # Return value
+ *
+ * A negative value if `left < right`, 0 if eq(left, right) or a positive
+ * value if `left > right`
+ */
 fn cmp(left: rope, right: rope) -> int {
     alt((left, right)) {
       (node::empty, node::empty) { ret 0; }
@@ -290,70 +290,70 @@ fn cmp(left: rope, right: rope) -> int {
     }
 }
 
-#[doc = "
-Returns `true` if both ropes have the same content (regardless of
-their structure), `false` otherwise
-"]
+/**
+ * Returns `true` if both ropes have the same content (regardless of
+ * their structure), `false` otherwise
+ */
 fn eq(left: rope, right: rope) -> bool {
     ret cmp(left, right) == 0;
 }
 
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
-`true` if `left <= right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ * `true` if `left <= right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
 fn le(left: rope, right: rope) -> bool {
     ret cmp(left, right) <= 0;
 }
 
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
-`true` if `left < right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ * `true` if `left < right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
 fn lt(left: rope, right: rope) -> bool {
     ret cmp(left, right) < 0;
 }
 
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
- `true` if `left >= right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ *  `true` if `left >= right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
 fn ge(left: rope, right: rope) -> bool {
     ret cmp(left, right) >= 0;
 }
 
-#[doc = "
-# Arguments
-
-* left - an arbitrary rope
-* right - an arbitrary rope
-
-# Return value
-
-`true` if `left > right` in lexicographical order (regardless of their
-structure), `false` otherwise
-"]
+/**
+ * # Arguments
+ *
+ * * left - an arbitrary rope
+ * * right - an arbitrary rope
+ *
+ * # Return value
+ *
+ * `true` if `left > right` in lexicographical order (regardless of their
+ * structure), `false` otherwise
+ */
 fn gt(left: rope, right: rope) -> bool {
     ret cmp(left, right) > 0;
 }
@@ -362,26 +362,26 @@ fn gt(left: rope, right: rope) -> bool {
 Section: Iterating
  */
 
-#[doc = "
-Loop through a rope, char by char
-
-While other mechanisms are available, this is generally the best manner
-of looping through the contents of a rope char by char. If you prefer a
-loop that iterates through the contents string by string (e.g. to print
-the contents of the rope or output it to the system), however,
-you should rather use `traverse_components`.
-
-# Arguments
-
-* rope - A rope to traverse. It may be empty.
-* it - A block to execute with each consecutive character of the rope.
-       Return `true` to continue, `false` to stop.
-
-# Return value
-
-`true` If execution proceeded correctly, `false` if it was interrupted,
-that is if `it` returned `false` at any point.
-"]
+/**
+ * Loop through a rope, char by char
+ *
+ * While other mechanisms are available, this is generally the best manner
+ * of looping through the contents of a rope char by char. If you prefer a
+ * loop that iterates through the contents string by string (e.g. to print
+ * the contents of the rope or output it to the system), however,
+ * you should rather use `traverse_components`.
+ *
+ * # Arguments
+ *
+ * * rope - A rope to traverse. It may be empty.
+ * * it - A block to execute with each consecutive character of the rope.
+ *        Return `true` to continue, `false` to stop.
+ *
+ * # Return value
+ *
+ * `true` If execution proceeded correctly, `false` if it was interrupted,
+ * that is if `it` returned `false` at any point.
+ */
 fn loop_chars(rope: rope, it: fn(char) -> bool) -> bool {
    alt(rope) {
       node::empty { ret true }
@@ -389,13 +389,13 @@ fn loop_chars(rope: rope, it: fn(char) -> bool) -> bool {
    }
 }
 
-#[doc = "
-Loop through a rope, char by char, until the end.
-
-# Arguments
-* rope - A rope to traverse. It may be empty
-* it - A block to execute with each consecutive character of the rope.
-"]
+/**
+ * Loop through a rope, char by char, until the end.
+ *
+ * # Arguments
+ * * rope - A rope to traverse. It may be empty
+ * * it - A block to execute with each consecutive character of the rope.
+ */
 fn iter_chars(rope: rope, it: fn(char)) {
     do loop_chars(rope) |x| {
         it(x);
@@ -403,28 +403,28 @@ fn iter_chars(rope: rope, it: fn(char)) {
     };
 }
 
-#[doc ="
-Loop through a rope, string by string
-
-While other mechanisms are available, this is generally the best manner of
-looping through the contents of a rope string by string, which may be useful
-e.g. to print strings as you see them (without having to copy their
-contents into a new string), to send them to then network, to write them to
-a file, etc.. If you prefer a loop that iterates through the contents
-char by char (e.g. to search for a char), however, you should rather
-use `traverse`.
-
-# Arguments
-
-* rope - A rope to traverse. It may be empty
-* it - A block to execute with each consecutive string component of the rope.
-       Return `true` to continue, `false` to stop
-
-# Return value
-
-`true` If execution proceeded correctly, `false` if it was interrupted,
-that is if `it` returned `false` at any point.
-"]
+/**
+ * Loop through a rope, string by string
+ *
+ * While other mechanisms are available, this is generally the best manner of
+ * looping through the contents of a rope string by string, which may be
+ * useful e.g. to print strings as you see them (without having to copy their
+ * contents into a new string), to send them to then network, to write them to
+ * a file, etc.. If you prefer a loop that iterates through the contents
+ * char by char (e.g. to search for a char), however, you should rather
+ * use `traverse`.
+ *
+ * # Arguments
+ *
+ * * rope - A rope to traverse. It may be empty
+ * * it - A block to execute with each consecutive string component of the
+ *        rope. Return `true` to continue, `false` to stop
+ *
+ * # Return value
+ *
+ * `true` If execution proceeded correctly, `false` if it was interrupted,
+ * that is if `it` returned `false` at any point.
+ */
 fn loop_leaves(rope: rope, it: fn(node::leaf) -> bool) -> bool{
    alt(rope) {
       node::empty { ret true }
@@ -461,17 +461,17 @@ mod iterator {
  Section: Rope properties
  */
 
-#[doc ="
-Returns the height of the rope.
-
-The height of the rope is a bound on the number of operations which
-must be performed during a character access before finding the leaf in
-which a character is contained.
-
-# Performance note
-
-Constant time.
-"]
+/**
+ * Returns the height of the rope.
+ *
+ * The height of the rope is a bound on the number of operations which
+ * must be performed during a character access before finding the leaf in
+ * which a character is contained.
+ *
+ * # Performance note
+ *
+ * Constant time.
+ */
 fn height(rope: rope) -> uint {
    alt(rope) {
       node::empty    { ret 0u; }
@@ -481,13 +481,13 @@ fn height(rope: rope) -> uint {
 
 
 
-#[doc ="
-The number of character in the rope
-
-# Performance note
-
-Constant time.
-"]
+/**
+ * The number of character in the rope
+ *
+ * # Performance note
+ *
+ * Constant time.
+ */
 pure fn char_len(rope: rope) -> uint {
    alt(rope) {
      node::empty           { ret 0u; }
@@ -495,13 +495,13 @@ pure fn char_len(rope: rope) -> uint {
    }
 }
 
-#[doc = "
-The number of bytes in the rope
-
-# Performance note
-
-Constant time.
-"]
+/**
+ * The number of bytes in the rope
+ *
+ * # Performance note
+ *
+ * Constant time.
+ */
 pure fn byte_len(rope: rope) -> uint {
    alt(rope) {
      node::empty           { ret 0u; }
@@ -509,22 +509,22 @@ pure fn byte_len(rope: rope) -> uint {
    }
 }
 
-#[doc = "
-The character at position `pos`
-
-# Arguments
-
-* pos - A position in the rope
-
-# Safety notes
-
-The function will fail if `pos` is not a valid position in the rope.
-
-# Performance note
-
-This function executes in a time proportional to the height of the
-rope + the (bounded) length of the largest leaf.
-"]
+/**
+ * The character at position `pos`
+ *
+ * # Arguments
+ *
+ * * pos - A position in the rope
+ *
+ * # Safety notes
+ *
+ * The function will fail if `pos` is not a valid position in the rope.
+ *
+ * # Performance note
+ *
+ * This function executes in a time proportional to the height of the
+ * rope + the (bounded) length of the largest leaf.
+ */
 fn char_at(rope: rope, pos: uint) -> char {
    alt(rope) {
       node::empty { fail }
@@ -538,31 +538,31 @@ fn char_at(rope: rope, pos: uint) -> char {
 */
 mod node {
 
-    #[doc = "Implementation of type `rope`"]
+    /// Implementation of type `rope`
     enum root {
-        #[doc = "An empty rope"]
+        /// An empty rope
         empty,
-        #[doc = "A non-empty rope"]
+        /// A non-empty rope
         content(@node),
     }
 
-    #[doc = "
-    A text component in a rope.
-
-    This is actually a slice in a rope, so as to ensure maximal sharing.
-
-    # Fields
-
-    * byte_offset = The number of bytes skippen in `content`
-    * byte_len - The number of bytes of `content` to use
-    * char_len - The number of chars in the leaf.
-    * content - Contents of the leaf.
-
-        Note that we can have `char_len < str::char_len(content)`, if
-        this leaf is only a subset of the string. Also note that the
-        string can be shared between several ropes, e.g. for indexing
-        purposes.
-    "]
+    /**
+     * A text component in a rope.
+     *
+     * This is actually a slice in a rope, so as to ensure maximal sharing.
+     *
+     * # Fields
+     *
+     * * byte_offset = The number of bytes skippen in `content`
+     * * byte_len - The number of bytes of `content` to use
+     * * char_len - The number of chars in the leaf.
+     * * content - Contents of the leaf.
+     *
+     *     Note that we can have `char_len < str::char_len(content)`, if
+     *     this leaf is only a subset of the string. Also note that the
+     *     string can be shared between several ropes, e.g. for indexing
+     *     purposes.
+     */
     type leaf = {
         byte_offset: uint,
         byte_len:    uint,
@@ -570,22 +570,23 @@ mod node {
         content:    @str
     };
 
-    #[doc = "
-    A node obtained from the concatenation of two other nodes
-
-    # Fields
-
-    * left - The node containing the beginning of the text.
-    * right - The node containing the end of the text.
-    * char_len - The number of chars contained in all leaves of this node.
-    * byte_len - The number of bytes in the subrope.
-
-        Used to pre-allocate the correct amount of storage for serialization.
-
-    * height - Height of the subrope.
-
-        Used for rebalancing and to allocate stacks for traversals.
-    "]
+    /**
+     * A node obtained from the concatenation of two other nodes
+     *
+     * # Fields
+     *
+     * * left - The node containing the beginning of the text.
+     * * right - The node containing the end of the text.
+     * * char_len - The number of chars contained in all leaves of this node.
+     * * byte_len - The number of bytes in the subrope.
+     *
+     *     Used to pre-allocate the correct amount of storage for
+     *     serialization.
+     *
+     * * height - Height of the subrope.
+     *
+     *     Used for rebalancing and to allocate stacks for traversals.
+     */
     type concat = {
         left:     @node,//TODO: Perhaps a `vec` instead of `left`/`right`
         right:    @node,
@@ -595,83 +596,83 @@ mod node {
     };
 
     enum node {
-        #[doc = "A leaf consisting in a `str`"]
+        /// A leaf consisting in a `str`
         leaf(leaf),
-        #[doc = "The concatenation of two ropes"]
+        /// The concatenation of two ropes
         concat(concat),
     }
 
-    #[doc = "
-    The maximal number of chars that _should_ be permitted in a single node.
-
-    This is not a strict value
-    "]
+    /**
+     * The maximal number of chars that _should_ be permitted in a single node
+     *
+     * This is not a strict value
+     */
     const hint_max_leaf_char_len: uint = 256u;
 
-    #[doc = "
-    The maximal height that _should_ be permitted in a tree.
-
-    This is not a strict value
-    "]
+    /**
+     * The maximal height that _should_ be permitted in a tree.
+     *
+     * This is not a strict value
+     */
     const hint_max_node_height:   uint = 16u;
 
-    #[doc = "
-    Adopt a string as a node.
-
-    If the string is longer than `max_leaf_char_len`, it is
-    logically split between as many leaves as necessary. Regardless,
-    the string itself is not copied.
-
-    Performance note: The complexity of this function is linear in
-    the length of `str`.
-    "]
+    /**
+     * Adopt a string as a node.
+     *
+     * If the string is longer than `max_leaf_char_len`, it is
+     * logically split between as many leaves as necessary. Regardless,
+     * the string itself is not copied.
+     *
+     * Performance note: The complexity of this function is linear in
+     * the length of `str`.
+     */
     fn of_str(str: @str) -> @node {
         ret of_substr(str, 0u, str::len(*str));
     }
 
-    #[doc ="
-    Adopt a slice of a string as a node.
-
-    If the slice is longer than `max_leaf_char_len`, it is logically split
-    between as many leaves as necessary. Regardless, the string itself
-    is not copied
-
-    # Arguments
-
-    * byte_start - The byte offset where the slice of `str` starts.
-    * byte_len   - The number of bytes from `str` to use.
-
-    # Safety note
-
-    Behavior is undefined if `byte_start` or `byte_len` do not represent
-    valid positions in `str`
-    "]
+    /**
+     * Adopt a slice of a string as a node.
+     *
+     * If the slice is longer than `max_leaf_char_len`, it is logically split
+     * between as many leaves as necessary. Regardless, the string itself
+     * is not copied
+     *
+     * # Arguments
+     *
+     * * byte_start - The byte offset where the slice of `str` starts.
+     * * byte_len   - The number of bytes from `str` to use.
+     *
+     * # Safety note
+     *
+     * Behavior is undefined if `byte_start` or `byte_len` do not represent
+     * valid positions in `str`
+     */
     fn of_substr(str: @str, byte_start: uint, byte_len: uint) -> @node {
         ret of_substr_unsafer(str, byte_start, byte_len,
                               str::count_chars(*str, byte_start, byte_len));
     }
 
-    #[doc = "
-    Adopt a slice of a string as a node.
-
-    If the slice is longer than `max_leaf_char_len`, it is logically split
-    between as many leaves as necessary. Regardless, the string itself
-    is not copied
-
-    # Arguments
-
-    * byte_start - The byte offset where the slice of `str` starts.
-    * byte_len - The number of bytes from `str` to use.
-    * char_len - The number of chars in `str` in the interval
-                 [byte_start, byte_start+byte_len)
-
-    # Safety notes
-
-    * Behavior is undefined if `byte_start` or `byte_len` do not represent
-      valid positions in `str`
-    * Behavior is undefined if `char_len` does not accurately represent the
-      number of chars between byte_start and byte_start+byte_len
-    "]
+    /**
+     * Adopt a slice of a string as a node.
+     *
+     * If the slice is longer than `max_leaf_char_len`, it is logically split
+     * between as many leaves as necessary. Regardless, the string itself
+     * is not copied
+     *
+     * # Arguments
+     *
+     * * byte_start - The byte offset where the slice of `str` starts.
+     * * byte_len - The number of bytes from `str` to use.
+     * * char_len - The number of chars in `str` in the interval
+     *              [byte_start, byte_start+byte_len)
+     *
+     * # Safety notes
+     *
+     * * Behavior is undefined if `byte_start` or `byte_len` do not represent
+     *   valid positions in `str`
+     * * Behavior is undefined if `char_len` does not accurately represent the
+     *   number of chars between byte_start and byte_start+byte_len
+     */
     fn of_substr_unsafer(str: @str, byte_start: uint, byte_len: uint,
                           char_len: uint) -> @node {
         assert(byte_start + byte_len <= str::len(*str));
@@ -744,14 +745,14 @@ mod node {
         }
     }
 
-    #[doc ="
-    Concatenate a forest of nodes into one tree.
-
-    # Arguments
-
-    * forest - The forest. This vector is progressively rewritten during
-               execution and should be discarded as meaningless afterwards.
-    "]
+    /**
+     * Concatenate a forest of nodes into one tree.
+     *
+     * # Arguments
+     *
+     * * forest - The forest. This vector is progressively rewritten during
+     *            execution and should be discarded as meaningless afterwards.
+     */
     fn tree_from_forest_destructive(forest: ~[mut @node]) -> @node {
         let mut i;
         let mut len = vec::len(forest);
@@ -820,13 +821,13 @@ mod node {
         ret unsafe::transmute(buf);
     }
 
-    #[doc ="
-    Replace a subtree by a single leaf with the same contents.
-
-    * Performance note
-
-    This function executes in linear time.
-    "]
+    /**
+     * Replace a subtree by a single leaf with the same contents.
+     *
+     * * Performance note
+     *
+     * This function executes in linear time.
+     */
     fn flatten(node: @node) -> @node unsafe {
         alt(*node) {
           leaf(_) { ret node }
@@ -841,21 +842,21 @@ mod node {
         }
     }
 
-    #[doc ="
-    Balance a node.
-
-    # Algorithm
-
-    * if the node height is smaller than `hint_max_node_height`, do nothing
-    * otherwise, gather all leaves as a forest, rebuild a balanced node,
-      concatenating small leaves along the way
-
-    # Return value
-
-    * `option::none` if no transformation happened
-    * `option::some(x)` otherwise, in which case `x` has the same contents
-       as `node` bot lower height and/or fragmentation.
-    "]
+    /**
+     * Balance a node.
+     *
+     * # Algorithm
+     *
+     * * if the node height is smaller than `hint_max_node_height`, do nothing
+     * * otherwise, gather all leaves as a forest, rebuild a balanced node,
+     *   concatenating small leaves along the way
+     *
+     * # Return value
+     *
+     * * `option::none` if no transformation happened
+     * * `option::some(x)` otherwise, in which case `x` has the same contents
+     *    as `node` bot lower height and/or fragmentation.
+     */
     fn bal(node: @node) -> option<@node> {
         if height(node) < hint_max_node_height { ret option::none; }
         //1. Gather all leaves as a forest
@@ -873,25 +874,25 @@ mod node {
 
     }
 
-    #[doc ="
-    Compute the subnode of a node.
-
-    # Arguments
-
-    * node        - A node
-    * byte_offset - A byte offset in `node`
-    * byte_len    - The number of bytes to return
-
-    # Performance notes
-
-    * this function performs no copying;
-    * this function executes in a time proportional to the height of `node`.
-
-    # Safety notes
-
-    This function fails if `byte_offset` or `byte_len` do not represent
-    valid positions in `node`.
-    "]
+    /**
+     * Compute the subnode of a node.
+     *
+     * # Arguments
+     *
+     * * node        - A node
+     * * byte_offset - A byte offset in `node`
+     * * byte_len    - The number of bytes to return
+     *
+     * # Performance notes
+     *
+     * * this function performs no copying;
+     * * this function executes in a time proportional to the height of `node`
+     *
+     * # Safety notes
+     *
+     * This function fails if `byte_offset` or `byte_len` do not represent
+     * valid positions in `node`.
+     */
     fn sub_bytes(node: @node, byte_offset: uint, byte_len: uint) -> @node {
         let mut node        = node;
         let mut byte_offset = byte_offset;
@@ -934,25 +935,25 @@ mod node {
         };
     }
 
-    #[doc ="
-    Compute the subnode of a node.
-
-    # Arguments
-
-    * node        - A node
-    * char_offset - A char offset in `node`
-    * char_len    - The number of chars to return
-
-    # Performance notes
-
-    * this function performs no copying;
-    * this function executes in a time proportional to the height of `node`.
-
-    # Safety notes
-
-    This function fails if `char_offset` or `char_len` do not represent
-    valid positions in `node`.
-    "]
+    /**
+     * Compute the subnode of a node.
+     *
+     * # Arguments
+     *
+     * * node        - A node
+     * * char_offset - A char offset in `node`
+     * * char_len    - The number of chars to return
+     *
+     * # Performance notes
+     *
+     * * this function performs no copying;
+     * * this function executes in a time proportional to the height of `node`
+     *
+     * # Safety notes
+     *
+     * This function fails if `char_offset` or `char_len` do not represent
+     * valid positions in `node`.
+     */
     fn sub_chars(node: @node, char_offset: uint, char_len: uint) -> @node {
         let mut node        = node;
         let mut char_offset = char_offset;
@@ -1045,20 +1046,20 @@ mod node {
         });
     }
 
-    #[doc ="
-    Loop through a node, leaf by leaf
-
-    # Arguments
-
-    * rope - A node to traverse.
-    * it - A block to execute with each consecutive leaf of the node.
-           Return `true` to continue, `false` to stop
-
-    # Arguments
-
-    `true` If execution proceeded correctly, `false` if it was interrupted,
-    that is if `it` returned `false` at any point.
-    "]
+    /**
+     * Loop through a node, leaf by leaf
+     *
+     * # Arguments
+     *
+     * * rope - A node to traverse.
+     * * it - A block to execute with each consecutive leaf of the node.
+     *        Return `true` to continue, `false` to stop
+     *
+     * # Arguments
+     *
+     * `true` If execution proceeded correctly, `false` if it was interrupted,
+     * that is if `it` returned `false` at any point.
+     */
     fn loop_leaves(node: @node, it: fn(leaf) -> bool) -> bool{
         let mut current = node;
         loop {
@@ -1077,23 +1078,23 @@ mod node {
         };
     }
 
-    #[doc ="
-    # Arguments
-
-    * pos - A position in the rope
-
-    # Return value
-
-    The character at position `pos`
-
-    # Safety notes
-
-    The function will fail if `pos` is not a valid position in the rope.
-
-    Performance note: This function executes in a time
-    proportional to the height of the rope + the (bounded)
-    length of the largest leaf.
-    "]
+    /**
+     * # Arguments
+     *
+     * * pos - A position in the rope
+     *
+     * # Return value
+     *
+     * The character at position `pos`
+     *
+     * # Safety notes
+     *
+     * The function will fail if `pos` is not a valid position in the rope.
+     *
+     * Performance note: This function executes in a time
+     * proportional to the height of the rope + the (bounded)
+     * length of the largest leaf.
+     */
     fn char_at(node: @node, pos: uint) -> char {
         let mut node    = node;
         let mut pos     = pos;
diff --git a/src/libstd/serialization.rs b/src/libstd/serialization.rs
index a5d56bda0efe7..f752dcc7d59e6 100644
--- a/src/libstd/serialization.rs
+++ b/src/libstd/serialization.rs
@@ -1,4 +1,4 @@
-#[doc = "Support code for serialization."];
+//! Support code for serialization.
 
 use core;
 
diff --git a/src/libstd/sha1.rs b/src/libstd/sha1.rs
index 6aed645283db1..607388bd55912 100644
--- a/src/libstd/sha1.rs
+++ b/src/libstd/sha1.rs
@@ -1,16 +1,16 @@
-#[doc ="
-An implementation of the SHA-1 cryptographic hash.
-
-First create a `sha1` object using the `sha1` constructor, then
-feed it input using the `input` or `input_str` methods, which may be
-called any number of times.
-
-After the entire input has been fed to the hash read the result using
-the `result` or `result_str` methods.
-
-The `sha1` object may be reused to create multiple hashes by calling
-the `reset` method.
-"];
+/*!
+ * An implementation of the SHA-1 cryptographic hash.
+ *
+ * First create a `sha1` object using the `sha1` constructor, then
+ * feed it input using the `input` or `input_str` methods, which may be
+ * called any number of times.
+ *
+ * After the entire input has been fed to the hash read the result using
+ * the `result` or `result_str` methods.
+ *
+ * The `sha1` object may be reused to create multiple hashes by calling
+ * the `reset` method.
+ */
 
 /*
  * A SHA-1 implementation derived from Paul E. Jones's reference
@@ -19,23 +19,23 @@ the `reset` method.
  */
 export sha1;
 
-#[doc = "The SHA-1 interface"]
+/// The SHA-1 interface
 iface sha1 {
-    #[doc = "Provide message input as bytes"]
+    /// Provide message input as bytes
     fn input(~[u8]);
-    #[doc = "Provide message input as string"]
+    /// Provide message input as string
     fn input_str(str);
-    #[doc = "
-    Read the digest as a vector of 20 bytes. After calling this no further
-    input may be provided until reset is called.
-    "]
+    /**
+     * Read the digest as a vector of 20 bytes. After calling this no further
+     * input may be provided until reset is called.
+     */
     fn result() -> ~[u8];
-    #[doc = "
-    Read the digest as a hex string. After calling this no further
-    input may be provided until reset is called.
-    "]
+    /**
+     * Read the digest as a hex string. After calling this no further
+     * input may be provided until reset is called.
+     */
     fn result_str() -> str;
-    #[doc = "Reset the SHA-1 state for reuse"]
+    /// Reset the SHA-1 state for reuse
     fn reset();
 }
 
@@ -49,7 +49,7 @@ const k2: u32 = 0x8F1BBCDCu32;
 const k3: u32 = 0xCA62C1D6u32;
 
 
-#[doc = "Construct a `sha` object"]
+/// Construct a `sha` object
 fn sha1() -> sha1 {
     type sha1state =
         {h: ~[mut u32],
diff --git a/src/libstd/smallintmap.rs b/src/libstd/smallintmap.rs
index 6583d97908d3e..9fb4be4804de2 100644
--- a/src/libstd/smallintmap.rs
+++ b/src/libstd/smallintmap.rs
@@ -1,7 +1,7 @@
-#[doc = "
-A simple map based on a vector for small integer keys. Space requirements
-are O(highest integer key).
-"];
+/*!
+ * A simple map based on a vector for small integer keys. Space requirements
+ * are O(highest integer key).
+ */
 import core::option;
 import core::option::{some, none};
 import dvec::{dvec, extensions};
@@ -10,36 +10,36 @@ import dvec::{dvec, extensions};
 // requires this to be.
 type smallintmap<T: copy> = @{v: dvec<option<T>>};
 
-#[doc = "Create a smallintmap"]
+/// Create a smallintmap
 fn mk<T: copy>() -> smallintmap<T> {
     ret @{v: dvec()};
 }
 
-#[doc = "
-Add a value to the map. If the map already contains a value for
-the specified key then the original value is replaced.
-"]
+/**
+ * Add a value to the map. If the map already contains a value for
+ * the specified key then the original value is replaced.
+ */
 #[inline(always)]
 fn insert<T: copy>(self: smallintmap<T>, key: uint, val: T) {
     self.v.grow_set_elt(key, none, some(val));
 }
 
-#[doc = "
-Get the value for the specified key. If the key does not exist
-in the map then returns none
-"]
+/**
+ * Get the value for the specified key. If the key does not exist
+ * in the map then returns none
+ */
 fn find<T: copy>(self: smallintmap<T>, key: uint) -> option<T> {
     if key < self.v.len() { ret self.v.get_elt(key); }
     ret none::<T>;
 }
 
-#[doc = "
-Get the value for the specified key
-
-# Failure
-
-If the key does not exist in the map
-"]
+/**
+ * Get the value for the specified key
+ *
+ * # Failure
+ *
+ * If the key does not exist in the map
+ */
 fn get<T: copy>(self: smallintmap<T>, key: uint) -> T {
     alt find(self, key) {
       none { #error("smallintmap::get(): key not present"); fail; }
@@ -47,14 +47,12 @@ fn get<T: copy>(self: smallintmap<T>, key: uint) -> T {
     }
 }
 
-#[doc = "
-Returns true if the map contains a value for the specified key
-"]
+/// Returns true if the map contains a value for the specified key
 fn contains_key<T: copy>(self: smallintmap<T>, key: uint) -> bool {
     ret !option::is_none(find(self, key));
 }
 
-#[doc = "Implements the map::map interface for smallintmap"]
+/// Implements the map::map interface for smallintmap
 impl <V: copy> of map::map<uint, V> for smallintmap<V> {
     fn size() -> uint {
         let mut sz = 0u;
@@ -106,7 +104,7 @@ impl <V: copy> of map::map<uint, V> for smallintmap<V> {
     }
 }
 
-#[doc = "Cast the given smallintmap to a map::map"]
+/// Cast the given smallintmap to a map::map
 fn as_map<V: copy>(s: smallintmap<V>) -> map::map<uint, V> {
     s as map::map::<uint, V>
 }
diff --git a/src/libstd/sort.rs b/src/libstd/sort.rs
index 7de8f0cfab830..d0092e97cb3fd 100644
--- a/src/libstd/sort.rs
+++ b/src/libstd/sort.rs
@@ -1,4 +1,4 @@
-#[doc = "Sorting methods"];
+//! Sorting methods
 import vec::{len, push};
 import int::{eq, ord};
 
@@ -9,12 +9,12 @@ export quick_sort3;
 
 type le<T> = fn(T, T) -> bool;
 
-#[doc = "
-Merge sort. Returns a new vector containing the sorted list.
-
-Has worst case O(n log n) performance, best case O(n), but
-is not space efficient. This is a stable sort.
-"]
+/**
+ * Merge sort. Returns a new vector containing the sorted list.
+ *
+ * Has worst case O(n log n) performance, best case O(n), but
+ * is not space efficient. This is a stable sort.
+ */
 fn merge_sort<T: copy>(le: le<T>, v: ~[const T]) -> ~[T] {
     type slice = (uint, uint);
 
@@ -84,12 +84,12 @@ fn qsort<T: copy>(compare_func: le<T>, arr: ~[mut T], left: uint,
     }
 }
 
-#[doc = "
-Quicksort. Sorts a mut vector in place.
-
-Has worst case O(n^2) performance, average case O(n log n).
-This is an unstable sort.
-"]
+/**
+ * Quicksort. Sorts a mut vector in place.
+ *
+ * Has worst case O(n^2) performance, average case O(n log n).
+ * This is an unstable sort.
+ */
 fn quick_sort<T: copy>(compare_func: le<T>, arr: ~[mut T]) {
     if len::<T>(arr) == 0u { ret; }
     qsort::<T>(compare_func, arr, 0u, len::<T>(arr) - 1u);
@@ -143,16 +143,16 @@ fn qsort3<T: copy>(compare_func_lt: le<T>, compare_func_eq: le<T>,
     qsort3::<T>(compare_func_lt, compare_func_eq, arr, i, right);
 }
 
-#[doc = "
-Fancy quicksort. Sorts a mut vector in place.
-
-Based on algorithm presented by [Sedgewick and Bentley]/~
-(http://www.cs.princeton.edu/~rs/talks/QuicksortIsOptimal.pdf).
-According to these slides this is the algorithm of choice for
-'randomly ordered keys, abstract compare' & 'small number of key values'.
-
-This is an unstable sort.
-"]
+/**
+ * Fancy quicksort. Sorts a mut vector in place.
+ *
+ * Based on algorithm presented by [Sedgewick and Bentley]/~
+ * (http://www.cs.princeton.edu/~rs/talks/QuicksortIsOptimal.pdf).
+ * According to these slides this is the algorithm of choice for
+ * 'randomly ordered keys, abstract compare' & 'small number of key values'.
+ *
+ * This is an unstable sort.
+ */
 fn quick_sort3<T: copy ord eq>(arr: ~[mut T]) {
     if len::<T>(arr) == 0u { ret; }
     qsort3::<T>(|x, y| x.lt(y), |x, y| x.eq(y), arr, 0,
diff --git a/src/libstd/std.rc b/src/libstd/std.rc
index 3470727121755..e30e9fc477438 100644
--- a/src/libstd/std.rc
+++ b/src/libstd/std.rc
@@ -6,7 +6,7 @@
 #[comment = "The Rust standard library"];
 #[license = "MIT"];
 #[crate_type = "lib"];
-#[doc = "The Rust standard library"];
+//! The Rust standard library
 
 #[no_core];
 
diff --git a/src/libstd/tempfile.rs b/src/libstd/tempfile.rs
index 11956ff8a259d..536f633f8a76f 100644
--- a/src/libstd/tempfile.rs
+++ b/src/libstd/tempfile.rs
@@ -1,4 +1,4 @@
-#[doc = "Temporary files and directories"];
+//! Temporary files and directories
 
 import core::option;
 import option::{none, some};
diff --git a/src/libstd/term.rs b/src/libstd/term.rs
index 43e1765f50b3d..fb134e852959c 100644
--- a/src/libstd/term.rs
+++ b/src/libstd/term.rs
@@ -1,4 +1,4 @@
-#[doc = "Simple ANSI color library"];
+//! Simple ANSI color library
 
 import core::option;
 
@@ -25,13 +25,13 @@ const color_bright_white: u8 = 15u8;
 
 fn esc(writer: io::writer) { writer.write([0x1bu8, '[' as u8]/~); }
 
-#[doc = "Reset the foreground and background colors to default"]
+/// Reset the foreground and background colors to default
 fn reset(writer: io::writer) {
     esc(writer);
     writer.write(~['0' as u8, 'm' as u8]);
 }
 
-#[doc = "Returns true if the terminal supports color"]
+/// Returns true if the terminal supports color
 fn color_supported() -> bool {
     let supported_terms = ~["xterm-color", "xterm",
                            "screen-bce", "xterm-256color"];
@@ -54,12 +54,12 @@ fn set_color(writer: io::writer, first_char: u8, color: u8) {
     writer.write(~[first_char, ('0' as u8) + color, 'm' as u8]);
 }
 
-#[doc = "Set the foreground color"]
+/// Set the foreground color
 fn fg(writer: io::writer, color: u8) {
     ret set_color(writer, '3' as u8, color);
 }
 
-#[doc = "Set the background color"]
+/// Set the background color
 fn bg(writer: io::writer, color: u8) {
     ret set_color(writer, '4' as u8, color);
 }
diff --git a/src/libstd/time.rs b/src/libstd/time.rs
index ba53bdbf01417..3f3749cb0648b 100644
--- a/src/libstd/time.rs
+++ b/src/libstd/time.rs
@@ -29,13 +29,13 @@ extern mod rustrt {
     fn rust_mktime(&&tm: tm, &sec: i64);
 }
 
-#[doc = "A record specifying a time value in seconds and microseconds."]
+/// A record specifying a time value in seconds and microseconds.
 type timespec = {sec: i64, nsec: i32};
 
-#[doc = "
-Returns the current time as a `timespec` containing the seconds and
-microseconds since 1970-01-01T00:00:00Z.
-"]
+/**
+ * Returns the current time as a `timespec` containing the seconds and
+ * microseconds since 1970-01-01T00:00:00Z.
+ */
 fn get_time() -> timespec {
     let mut sec = 0i64;
     let mut nsec = 0i32;
@@ -43,20 +43,20 @@ fn get_time() -> timespec {
     ret {sec: sec, nsec: nsec};
 }
 
-#[doc = "
-Returns the current value of a high-resolution performance counter
-in nanoseconds since an unspecified epoch.
-"]
+/**
+ * Returns the current value of a high-resolution performance counter
+ * in nanoseconds since an unspecified epoch.
+ */
 fn precise_time_ns() -> u64 {
     let mut ns = 0u64;
     rustrt::precise_time_ns(ns);
     ns
 }
 
-#[doc = "
-Returns the current value of a high-resolution performance counter
-in seconds since an unspecified epoch.
-"]
+/**
+ * Returns the current value of a high-resolution performance counter
+ * in seconds since an unspecified epoch.
+ */
 fn precise_time_s() -> float {
     ret (precise_time_ns() as float) / 1000000000.;
 }
@@ -97,7 +97,7 @@ fn empty_tm() -> tm {
     }
 }
 
-#[doc = "Returns the specified time in UTC"]
+/// Returns the specified time in UTC
 fn at_utc(clock: timespec) -> tm {
     let mut {sec, nsec} = clock;
     let mut tm = empty_tm();
@@ -105,12 +105,12 @@ fn at_utc(clock: timespec) -> tm {
     tm
 }
 
-#[doc = "Returns the current time in UTC"]
+/// Returns the current time in UTC
 fn now_utc() -> tm {
     at_utc(get_time())
 }
 
-#[doc = "Returns the specified time in the local timezone"]
+/// Returns the specified time in the local timezone
 fn at(clock: timespec) -> tm {
     let mut {sec, nsec} = clock;
     let mut tm = empty_tm();
@@ -118,12 +118,12 @@ fn at(clock: timespec) -> tm {
     tm
 }
 
-#[doc = "Returns the current time in the local timezone"]
+/// Returns the current time in the local timezone
 fn now() -> tm {
     at(get_time())
 }
 
-#[doc = "Parses the time from the string according to the format string."]
+/// Parses the time from the string according to the format string.
 fn strptime(s: str, format: str) -> result<tm, str> {
     type tm_mut = {
        mut tm_sec: i32,
@@ -751,7 +751,7 @@ fn strftime(format: str, tm: tm) -> str {
 }
 
 impl tm for tm {
-    #[doc = "Convert time to the seconds from January 1, 1970"]
+    /// Convert time to the seconds from January 1, 1970
     fn to_timespec() -> timespec {
         let mut sec = 0i64;
         if self.tm_gmtoff == 0_i32 {
@@ -762,31 +762,31 @@ impl tm for tm {
         { sec: sec, nsec: self.tm_nsec }
     }
 
-    #[doc = "Convert time to the local timezone"]
+    /// Convert time to the local timezone
     fn to_local() -> tm {
         at(self.to_timespec())
     }
 
-    #[doc = "Convert time to the UTC"]
+    /// Convert time to the UTC
     fn to_utc() -> tm {
         at_utc(self.to_timespec())
     }
 
-    #[doc = "
-    Return a string of the current time in the form
-    \"Thu Jan  1 00:00:00 1970\".
-    "]
+    /**
+     * Return a string of the current time in the form
+     * "Thu Jan  1 00:00:00 1970".
+     */
     fn ctime() -> str { self.strftime("%c") }
 
-    #[doc = "Formats the time according to the format string."]
+    /// Formats the time according to the format string.
     fn strftime(format: str) -> str { strftime(format, self) }
 
-    #[doc = "
-    Returns a time string formatted according to RFC 822.
-
-    local: \"Thu, 22 Mar 2012 07:53:18 PST\"
-    utc:   \"Thu, 22 Mar 2012 14:53:18 UTC\"
-    "]
+    /**
+     * Returns a time string formatted according to RFC 822.
+     *
+     * local: "Thu, 22 Mar 2012 07:53:18 PST"
+     * utc:   "Thu, 22 Mar 2012 14:53:18 UTC"
+     */
     fn rfc822() -> str {
         if self.tm_gmtoff == 0_i32 {
             self.strftime("%a, %d %b %Y %T GMT")
@@ -795,22 +795,22 @@ impl tm for tm {
         }
     }
 
-    #[doc = "
-    Returns a time string formatted according to RFC 822 with Zulu time.
-
-    local: \"Thu, 22 Mar 2012 07:53:18 -0700\"
-    utc:   \"Thu, 22 Mar 2012 14:53:18 -0000\"
-    "]
+    /**
+     * Returns a time string formatted according to RFC 822 with Zulu time.
+     *
+     * local: "Thu, 22 Mar 2012 07:53:18 -0700"
+     * utc:   "Thu, 22 Mar 2012 14:53:18 -0000"
+     */
     fn rfc822z() -> str {
         self.strftime("%a, %d %b %Y %T %z")
     }
 
-    #[doc = "
-    Returns a time string formatted according to ISO 8601.
-
-    local: \"2012-02-22T07:53:18-07:00\"
-    utc:   \"2012-02-22T14:53:18Z\"
-    "]
+    /**
+     * Returns a time string formatted according to ISO 8601.
+     *
+     * local: "2012-02-22T07:53:18-07:00"
+     * utc:   "2012-02-22T14:53:18Z"
+     */
     fn rfc3339() -> str {
         if self.tm_gmtoff == 0_i32 {
             self.strftime("%Y-%m-%dT%H:%M:%SZ")
diff --git a/src/libstd/timer.rs b/src/libstd/timer.rs
index 15e91691c72e2..ea7da3741d1fb 100644
--- a/src/libstd/timer.rs
+++ b/src/libstd/timer.rs
@@ -1,28 +1,26 @@
-#[doc ="
-Utilities that leverage libuv's `uv_timer_*` API
-"];
+//! Utilities that leverage libuv's `uv_timer_*` API
 
 import uv = uv;
 import uv::iotask;
 import iotask::iotask;
 export delayed_send, sleep, recv_timeout;
 
-#[doc = "
-Wait for timeout period then send provided value over a channel
-
-This call returns immediately. Useful as the building block for a number
-of higher-level timer functions.
-
-Is not guaranteed to wait for exactly the specified time, but will wait
-for *at least* that period of time.
-
-# Arguments
-
-* `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
-* msecs - a timeout period, in milliseconds, to wait
-* ch - a channel of type T to send a `val` on
-* val - a value of type T to send over the provided `ch`
-"]
+/**
+ * Wait for timeout period then send provided value over a channel
+ *
+ * This call returns immediately. Useful as the building block for a number
+ * of higher-level timer functions.
+ *
+ * Is not guaranteed to wait for exactly the specified time, but will wait
+ * for *at least* that period of time.
+ *
+ * # Arguments
+ *
+ * * `hl_loop` - a `uv::hl::high_level_loop` that the tcp request will run on
+ * * msecs - a timeout period, in milliseconds, to wait
+ * * ch - a channel of type T to send a `val` on
+ * * val - a value of type T to send over the provided `ch`
+ */
 fn delayed_send<T: copy send>(iotask: iotask,
                               msecs: uint, ch: comm::chan<T>, val: T) {
         unsafe {
@@ -60,17 +58,17 @@ fn delayed_send<T: copy send>(iotask: iotask,
     };
 }
 
-#[doc = "
-Blocks the current task for (at least) the specified time period.
-
-Is not guaranteed to sleep for exactly the specified time, but will sleep
-for *at least* that period of time.
-
-# Arguments
-
-* `iotask` - a `uv::iotask` that the tcp request will run on
-* msecs - an amount of time, in milliseconds, for the current task to block
-"]
+/**
+ * Blocks the current task for (at least) the specified time period.
+ *
+ * Is not guaranteed to sleep for exactly the specified time, but will sleep
+ * for *at least* that period of time.
+ *
+ * # Arguments
+ *
+ * * `iotask` - a `uv::iotask` that the tcp request will run on
+ * * msecs - an amount of time, in milliseconds, for the current task to block
+ */
 fn sleep(iotask: iotask, msecs: uint) {
     let exit_po = comm::port::<()>();
     let exit_ch = comm::chan(exit_po);
@@ -78,25 +76,26 @@ fn sleep(iotask: iotask, msecs: uint) {
     comm::recv(exit_po);
 }
 
-#[doc = "
-Receive on a port for (up to) a specified time, then return an `option<T>`
-
-This call will block to receive on the provided port for up to the specified
-timeout. Depending on whether the provided port receives in that time period,
-`recv_timeout` will return an `option<T>` representing the result.
-
-# Arguments
-
-* `iotask' - `uv::iotask` that the tcp request will run on
-* msecs - an mount of time, in milliseconds, to wait to receive
-* wait_port - a `comm::port<T>` to receive on
-
-# Returns
-
-An `option<T>` representing the outcome of the call. If the call `recv`'d on
-the provided port in the allotted timeout period, then the result will be a
-`some(T)`. If not, then `none` will be returned.
-"]
+/**
+ * Receive on a port for (up to) a specified time, then return an `option<T>`
+ *
+ * This call will block to receive on the provided port for up to the
+ * specified timeout. Depending on whether the provided port receives in that
+ * time period, `recv_timeout` will return an `option<T>` representing the
+ * result.
+ *
+ * # Arguments
+ *
+ * * `iotask' - `uv::iotask` that the tcp request will run on
+ * * msecs - an mount of time, in milliseconds, to wait to receive
+ * * wait_port - a `comm::port<T>` to receive on
+ *
+ * # Returns
+ *
+ * An `option<T>` representing the outcome of the call. If the call `recv`'d
+ * on the provided port in the allotted timeout period, then the result will
+ * be a `some(T)`. If not, then `none` will be returned.
+ */
 fn recv_timeout<T: copy send>(iotask: iotask,
                               msecs: uint,
                               wait_po: comm::port<T>) -> option<T> {
diff --git a/src/libstd/treemap.rs b/src/libstd/treemap.rs
index 066d2a6501f7e..1fde1c4fd6ae6 100644
--- a/src/libstd/treemap.rs
+++ b/src/libstd/treemap.rs
@@ -1,10 +1,10 @@
-#[doc = "
-A key,value store that works on anything.
-
-This works using a binary search tree. In the first version, it's a
-very naive algorithm, but it will probably be updated to be a
-red-black tree or something else.
-"];
+/*!
+ * A key,value store that works on anything.
+ *
+ * This works using a binary search tree. In the first version, it's a
+ * very naive algorithm, but it will probably be updated to be a
+ * red-black tree or something else.
+ */
 
 import core::option::{some, none};
 import option = core::option;
@@ -25,10 +25,10 @@ enum tree_node<K, V> = {
     mut right: tree_edge<K, V>
 };
 
-#[doc = "Create a treemap"]
+/// Create a treemap
 fn treemap<K, V>() -> treemap<K, V> { @mut none }
 
-#[doc = "Insert a value into the map"]
+/// Insert a value into the map
 fn insert<K: copy, V: copy>(m: &mut tree_edge<K, V>, k: K, v: V) {
     alt copy *m {
       none {
@@ -50,7 +50,7 @@ fn insert<K: copy, V: copy>(m: &mut tree_edge<K, V>, k: K, v: V) {
     };
 }
 
-#[doc = "Find a value based on the key"]
+/// Find a value based on the key
 fn find<K: copy, V: copy>(m: &const tree_edge<K, V>, k: K) -> option<V> {
     alt copy *m {
       none { none }
@@ -68,7 +68,7 @@ fn find<K: copy, V: copy>(m: &const tree_edge<K, V>, k: K) -> option<V> {
     }
 }
 
-#[doc = "Visit all pairs in the map in order."]
+/// Visit all pairs in the map in order.
 fn traverse<K, V: copy>(m: &const tree_edge<K, V>, f: fn(K, V)) {
     alt copy *m {
       none { }
diff --git a/src/libstd/util.rs b/src/libstd/util.rs
index fc0a326dee764..1101be170bac9 100644
--- a/src/libstd/util.rs
+++ b/src/libstd/util.rs
@@ -1,9 +1,9 @@
-#[doc = "The identity function"]
+/// The identity function
 pure fn id<T: copy>(x: T) -> T { x }
 
 /* FIXME (issue #141):  See test/run-pass/constrained-type.rs.  Uncomment
  * the constraint once fixed. */
-#[doc = "A rational number"]
+/// A rational number
 type rational = {num: int, den: int}; // : int::positive(*.den);
 
 pure fn rational_leq(x: rational, y: rational) -> bool {
diff --git a/src/libstd/uv.rs b/src/libstd/uv.rs
index c2e4c55d61eea..50f5d9704faeb 100644
--- a/src/libstd/uv.rs
+++ b/src/libstd/uv.rs
@@ -1,27 +1,27 @@
-#[doc = "
-Rust bindings to libuv
-
-This is the base-module for various levels of bindings to
-the libuv library.
-
-These modules are seeing heavy work, currently, and the final
-API layout should not be inferred from its current form.
-
-This base module currently contains a historical, rust-based
-implementation of a few libuv operations that hews closely to
-the patterns of the libuv C-API. It was used, mostly, to explore
-some implementation details and will most likely be deprecated
-in the near future.
-
-The `ll` module contains low-level mappings for working directly
-with the libuv C-API.
-
-The `hl` module contains a set of tools library developers can
-use for interacting with an active libuv loop. This modules's
-API is meant to be used to write high-level,
-rust-idiomatic abstractions for utilizes libuv's asynchronous IO
-facilities.
-"];
+/*!
+ * Rust bindings to libuv
+ *
+ * This is the base-module for various levels of bindings to
+ * the libuv library.
+ *
+ * These modules are seeing heavy work, currently, and the final
+ * API layout should not be inferred from its current form.
+ *
+ * This base module currently contains a historical, rust-based
+ * implementation of a few libuv operations that hews closely to
+ * the patterns of the libuv C-API. It was used, mostly, to explore
+ * some implementation details and will most likely be deprecated
+ * in the near future.
+ *
+ * The `ll` module contains low-level mappings for working directly
+ * with the libuv C-API.
+ *
+ * The `hl` module contains a set of tools library developers can
+ * use for interacting with an active libuv loop. This modules's
+ * API is meant to be used to write high-level,
+ * rust-idiomatic abstractions for utilizes libuv's asynchronous IO
+ * facilities.
+ */
 
 import ll = uv_ll;
 export ll;
diff --git a/src/libstd/uv_global_loop.rs b/src/libstd/uv_global_loop.rs
index d9009aa05036f..60c5dae4d42c4 100644
--- a/src/libstd/uv_global_loop.rs
+++ b/src/libstd/uv_global_loop.rs
@@ -1,6 +1,4 @@
-#[doc="
-A process-wide libuv event loop for library use.
-"];
+//! A process-wide libuv event loop for library use.
 
 export get;
 
@@ -16,18 +14,18 @@ extern mod rustrt {
     fn rust_uv_get_kernel_global_chan_ptr() -> *libc::uintptr_t;
 }
 
-#[doc ="
-Race-free helper to get access to a global task where a libuv
-loop is running.
-
-Use `uv::hl::interact` to do operations against the global
-loop that this function returns.
-
-# Return
-
-* A `hl::high_level_loop` that encapsulates communication with the global
-loop.
-"]
+/**
+ * Race-free helper to get access to a global task where a libuv
+ * loop is running.
+ *
+ * Use `uv::hl::interact` to do operations against the global
+ * loop that this function returns.
+ *
+ * # Return
+ *
+ * * A `hl::high_level_loop` that encapsulates communication with the global
+ * loop.
+ */
 fn get() -> iotask {
     ret get_monitor_task_gl();
 }
diff --git a/src/libstd/uv_iotask.rs b/src/libstd/uv_iotask.rs
index 27c79d7a6d16c..65956d8e22bec 100644
--- a/src/libstd/uv_iotask.rs
+++ b/src/libstd/uv_iotask.rs
@@ -1,11 +1,9 @@
-#[doc = "
-
-A task-based interface to the uv loop
-
-The I/O task runs in its own single-threaded scheduler.  By using the
-`interact` function you can execute code in a uv callback.
-
-"];
+/*!
+ * A task-based interface to the uv loop
+ *
+ * The I/O task runs in its own single-threaded scheduler.  By using the
+ * `interact` function you can execute code in a uv callback.
+ */
 
 export iotask;
 export spawn_iotask;
@@ -17,9 +15,7 @@ import ptr::addr_of;
 import comm::{port, chan, methods, listen};
 import ll = uv_ll;
 
-#[doc = "
-Used to abstract-away direct interaction with a libuv loop.
-"]
+/// Used to abstract-away direct interaction with a libuv loop.
 enum iotask {
     iotask_({
         async_handle: *ll::uv_async_t,
@@ -52,40 +48,40 @@ fn spawn_iotask(-builder: task::builder) -> iotask {
 }
 
 
-#[doc = "
-Provide a callback to be processed by `iotask`
-
-The primary way to do operations again a running `iotask` that
-doesn't involve creating a uv handle via `safe_handle`
-
-# Warning
-
-This function is the only safe way to interact with _any_ `iotask`.
-Using functions in the `uv::ll` module outside of the `cb` passed into
-this function is _very dangerous_.
-
-# Arguments
-
-* iotask - a uv I/O task that you want to do operations against
-* cb - a function callback to be processed on the running loop's
-thread. The only parameter passed in is an opaque pointer representing the
-running `uv_loop_t*`. In the context of this callback, it is safe to use
-this pointer to do various uv_* API calls contained within the `uv::ll`
-module. It is not safe to send the `loop_ptr` param to this callback out
-via ports/chans.
-"]
+/**
+ * Provide a callback to be processed by `iotask`
+ *
+ * The primary way to do operations again a running `iotask` that
+ * doesn't involve creating a uv handle via `safe_handle`
+ *
+ * # Warning
+ *
+ * This function is the only safe way to interact with _any_ `iotask`.
+ * Using functions in the `uv::ll` module outside of the `cb` passed into
+ * this function is _very dangerous_.
+ *
+ * # Arguments
+ *
+ * * iotask - a uv I/O task that you want to do operations against
+ * * cb - a function callback to be processed on the running loop's
+ * thread. The only parameter passed in is an opaque pointer representing the
+ * running `uv_loop_t*`. In the context of this callback, it is safe to use
+ * this pointer to do various uv_* API calls contained within the `uv::ll`
+ * module. It is not safe to send the `loop_ptr` param to this callback out
+ * via ports/chans.
+ */
 unsafe fn interact(iotask: iotask,
                    -cb: fn~(*c_void)) {
     send_msg(iotask, interaction(cb));
 }
 
-#[doc="
-Shut down the I/O task
-
-Is used to signal to the loop that it should close the internally-held
-async handle and do a sanity check to make sure that all other handles are
-closed, causing a failure otherwise.
-"]
+/**
+ * Shut down the I/O task
+ *
+ * Is used to signal to the loop that it should close the internally-held
+ * async handle and do a sanity check to make sure that all other handles are
+ * closed, causing a failure otherwise.
+ */
 fn exit(iotask: iotask) unsafe {
     send_msg(iotask, teardown_loop);
 }
@@ -98,9 +94,7 @@ enum iotask_msg {
     teardown_loop
 }
 
-#[doc = "
-Run the loop and begin handling messages
-"]
+/// Run the loop and begin handling messages
 fn run_loop(iotask_ch: chan<iotask>) unsafe {
 
     let loop_ptr = ll::loop_new();
@@ -147,7 +141,7 @@ fn send_msg(iotask: iotask,
     ll::async_send(iotask.async_handle);
 }
 
-#[doc ="Dispatch all pending messages"]
+/// Dispatch all pending messages
 extern fn wake_up_cb(async_handle: *ll::uv_async_t,
                     status: int) unsafe {
 
diff --git a/src/libstd/uv_ll.rs b/src/libstd/uv_ll.rs
index e282c7c15f43c..1a8deb937ace6 100644
--- a/src/libstd/uv_ll.rs
+++ b/src/libstd/uv_ll.rs
@@ -1,24 +1,24 @@
-#[doc = "
-Low-level bindings to the libuv library.
-
-This module contains a set of direct, 'bare-metal' wrappers around
-the libuv C-API.
-
-Also contained herein are a set of rust records that map, in
-approximate memory-size, to the libuv data structures. The record
-implementations are adjusted, per-platform, to match their respective
-representations.
-
-There are also a collection of helper functions to ease interacting
-with the low-level API (such as a function to return the latest
-libuv error as a rust-formatted string).
-
-As new functionality, existant in uv.h, is added to the rust stdlib,
-the mappings should be added in this module.
-
-This module's implementation will hopefully be, eventually, replaced
-with per-platform, generated source files from rust-bindgen.
-"];
+/*!
+ * Low-level bindings to the libuv library.
+ *
+ * This module contains a set of direct, 'bare-metal' wrappers around
+ * the libuv C-API.
+ *
+ * Also contained herein are a set of rust records that map, in
+ * approximate memory-size, to the libuv data structures. The record
+ * implementations are adjusted, per-platform, to match their respective
+ * representations.
+ *
+ * There are also a collection of helper functions to ease interacting
+ * with the low-level API (such as a function to return the latest
+ * libuv error as a rust-formatted string).
+ *
+ * As new functionality, existant in uv.h, is added to the rust stdlib,
+ * the mappings should be added in this module.
+ *
+ * This module's implementation will hopefully be, eventually, replaced
+ * with per-platform, generated source files from rust-bindgen.
+ */
 
 import libc::size_t;
 
diff --git a/src/libsyntax/ast_util.rs b/src/libsyntax/ast_util.rs
index c6fb9349ad5f4..551c6817405dc 100644
--- a/src/libsyntax/ast_util.rs
+++ b/src/libsyntax/ast_util.rs
@@ -365,7 +365,7 @@ fn is_self(d: ast::def) -> bool {
   }
 }
 
-#[doc = "Maps a binary operator to its precedence"]
+/// Maps a binary operator to its precedence
 fn operator_prec(op: ast::binop) -> uint {
   alt op {
       mul | div | rem   { 12u }
diff --git a/src/libsyntax/attr.rs b/src/libsyntax/attr.rs
index e1cfa4830ae6e..838e275332b87 100644
--- a/src/libsyntax/attr.rs
+++ b/src/libsyntax/attr.rs
@@ -120,10 +120,10 @@ fn get_meta_item_name(meta: @ast::meta_item) -> ast::ident {
     }
 }
 
-#[doc = "
-Gets the string value if the meta_item is a meta_name_value variant
-containing a string, otherwise none
-"]
+/**
+ * Gets the string value if the meta_item is a meta_name_value variant
+ * containing a string, otherwise none
+ */
 fn get_meta_item_value_str(meta: @ast::meta_item) -> option<@str> {
     alt meta.node {
       ast::meta_name_value(_, v) {
@@ -140,7 +140,7 @@ fn get_meta_item_value_str(meta: @ast::meta_item) -> option<@str> {
     }
 }
 
-#[doc = "Gets a list of inner meta items from a list meta_item type"]
+/// Gets a list of inner meta items from a list meta_item type
 fn get_meta_item_list(meta: @ast::meta_item) -> option<~[@ast::meta_item]> {
     alt meta.node {
       ast::meta_list(_, l) { option::some(/* FIXME (#2543) */ copy l) }
@@ -148,10 +148,10 @@ fn get_meta_item_list(meta: @ast::meta_item) -> option<~[@ast::meta_item]> {
     }
 }
 
-#[doc = "
-If the meta item is a nam-value type with a string value then returns
-a tuple containing the name and string value, otherwise `none`
-"]
+/**
+ * If the meta item is a nam-value type with a string value then returns
+ * a tuple containing the name and string value, otherwise `none`
+ */
 fn get_name_value_str_pair(
     item: @ast::meta_item
 ) -> option<(ast::ident, @str)> {
@@ -167,9 +167,7 @@ fn get_name_value_str_pair(
 
 /* Searching */
 
-#[doc = "
-Search a list of attributes and return only those with a specific name
-"]
+/// Search a list of attributes and return only those with a specific name
 fn find_attrs_by_name(attrs: ~[ast::attribute], +name: str) ->
    ~[ast::attribute] {
     let filter = (
@@ -182,9 +180,7 @@ fn find_attrs_by_name(attrs: ~[ast::attribute], +name: str) ->
     ret vec::filter_map(attrs, filter);
 }
 
-#[doc = "
-Searcha list of meta items and return only those with a specific name
-"]
+/// Searcha list of meta items and return only those with a specific name
 fn find_meta_items_by_name(metas: ~[@ast::meta_item], +name: str) ->
    ~[@ast::meta_item] {
     let filter = fn@(&&m: @ast::meta_item) -> option<@ast::meta_item> {
@@ -195,10 +191,10 @@ fn find_meta_items_by_name(metas: ~[@ast::meta_item], +name: str) ->
     ret vec::filter_map(metas, filter);
 }
 
-#[doc = "
-Returns true if a list of meta items contains another meta item. The
-comparison is performed structurally.
-"]
+/**
+ * Returns true if a list of meta items contains another meta item. The
+ * comparison is performed structurally.
+ */
 fn contains(haystack: ~[@ast::meta_item], needle: @ast::meta_item) -> bool {
     #debug("looking for %s",
            print::pprust::meta_item_to_str(*needle));
@@ -332,10 +328,10 @@ fn find_linkage_attrs(attrs: ~[ast::attribute]) -> ~[ast::attribute] {
     ret found;
 }
 
-#[doc = "
-From a list of crate attributes get only the meta_items that impact crate
-linkage
-"]
+/**
+ * From a list of crate attributes get only the meta_items that impact crate
+ * linkage
+ */
 fn find_linkage_metas(attrs: ~[ast::attribute]) -> ~[@ast::meta_item] {
     do find_linkage_attrs(attrs).flat_map |attr| {
         alt check attr.node.value.node {
@@ -370,7 +366,7 @@ enum inline_attr {
     ia_always
 }
 
-#[doc = "True if something like #[inline] is found in the list of attrs."]
+/// True if something like #[inline] is found in the list of attrs.
 fn find_inline_attr(attrs: ~[ast::attribute]) -> inline_attr {
     // TODO---validate the usage of #[inline] and #[inline(always)]
     do vec::foldl(ia_none, attrs) |ia,attr| {
diff --git a/src/libsyntax/parse.rs b/src/libsyntax/parse.rs
index 7ddc763fac971..04f533be5bf87 100644
--- a/src/libsyntax/parse.rs
+++ b/src/libsyntax/parse.rs
@@ -1,4 +1,4 @@
-#[doc = "The main parser interface"];
+//! The main parser interface
 import dvec::extensions;
 
 export parse_sess;
diff --git a/src/libsyntax/parse/lexer.rs b/src/libsyntax/parse/lexer.rs
index 8a32ecdac646b..a85e791696ff9 100644
--- a/src/libsyntax/parse/lexer.rs
+++ b/src/libsyntax/parse/lexer.rs
@@ -24,7 +24,7 @@ enum tt_frame_up { /* to break a circularity */
 }
 
 /* TODO: figure out how to have a uniquely linked stack, and change to `~` */
-#[doc = "an unzipping of `token_tree`s"]
+/// an unzipping of `token_tree`s
 type tt_frame = @{
     readme: ~[ast::token_tree],
     mut idx: uint,
diff --git a/src/libsyntax/parse/parser.rs b/src/libsyntax/parse/parser.rs
index 747ca07bee5fc..c929230881046 100644
--- a/src/libsyntax/parse/parser.rs
+++ b/src/libsyntax/parse/parser.rs
@@ -1057,7 +1057,7 @@ class parser {
     }
 
     fn parse_token_tree() -> token_tree {
-        #[doc="what's the opposite delimiter?"]
+        /// what's the opposite delimiter?
         fn flip(&t: token::token) -> token::token {
             alt t {
               token::LPAREN { token::RPAREN }
diff --git a/src/libsyntax/parse/prec.rs b/src/libsyntax/parse/prec.rs
index e2e35447af3f4..8ea7306e18087 100644
--- a/src/libsyntax/parse/prec.rs
+++ b/src/libsyntax/parse/prec.rs
@@ -6,17 +6,19 @@ import token::*;
 import token::token;
 import ast::*;
 
-#[doc = "Unary operators have higher precedence than binary"]
+/// Unary operators have higher precedence than binary
 const unop_prec: uint = 100u;
 
-#[doc = "
-Precedence of the `as` operator, which is a binary operator
-but is not represented in the precedence table.
-"]
+/**
+ * Precedence of the `as` operator, which is a binary operator
+ * but is not represented in the precedence table.
+ */
 const as_prec: uint = 11u;
 
-#[doc = "Maps a token to a record specifying the corresponding binary
-         operator and its precedence"]
+/**
+ * Maps a token to a record specifying the corresponding binary
+ * operator and its precedence
+ */
 fn token_to_binop(tok: token) -> option<ast::binop> {
   alt tok {
       BINOP(STAR)    { some(mul) }
diff --git a/src/libsyntax/parse/token.rs b/src/libsyntax/parse/token.rs
index 4c573b45a1f22..c4ae9269914f9 100644
--- a/src/libsyntax/parse/token.rs
+++ b/src/libsyntax/parse/token.rs
@@ -85,7 +85,7 @@ enum token {
 }
 
 #[auto_serialize]
-#[doc = "For interpolation during macro expansion."]
+/// For interpolation during macro expansion.
 enum whole_nt {
     w_item(@ast::item),
     w_block(ast::blk),
@@ -233,14 +233,14 @@ pure fn is_bar(t: token) -> bool {
     alt t { BINOP(OR) | OROR { true } _ { false } }
 }
 
-#[doc = "
-All the valid words that have meaning in the Rust language.
-
-Rust keywords are either 'contextual' or 'restricted'. Contextual
-keywords may be used as identifiers because their appearance in
-the grammar is unambiguous. Restricted keywords may not appear
-in positions that might otherwise contain _value identifiers_.
-"]
+/**
+ * All the valid words that have meaning in the Rust language.
+ *
+ * Rust keywords are either 'contextual' or 'restricted'. Contextual
+ * keywords may be used as identifiers because their appearance in
+ * the grammar is unambiguous. Restricted keywords may not appear
+ * in positions that might otherwise contain _value identifiers_.
+ */
 fn keyword_table() -> hashmap<str, ()> {
     let keywords = str_hash();
     for contextual_keyword_table().each_key |word| {
@@ -252,7 +252,7 @@ fn keyword_table() -> hashmap<str, ()> {
     keywords
 }
 
-#[doc = "Keywords that may be used as identifiers"]
+/// Keywords that may be used as identifiers
 fn contextual_keyword_table() -> hashmap<str, ()> {
     let words = str_hash();
     let keys = ~[
@@ -274,19 +274,20 @@ fn contextual_keyword_table() -> hashmap<str, ()> {
     words
 }
 
-#[doc = "
-Keywords that may not appear in any position that might otherwise contain a
-_value identifier_. Restricted keywords may still be used as other types of
-identifiers.
-
-Reasons:
-
-* For some (most?), if used at the start of a line, they will cause the line
-  to be interpreted as a specific kind of statement, which would be confusing.
-
-* `true` or `false` as identifiers would always be shadowed by
-  the boolean constants
-"]
+/**
+ * Keywords that may not appear in any position that might otherwise contain a
+ * _value identifier_. Restricted keywords may still be used as other types of
+ * identifiers.
+ *
+ * Reasons:
+ *
+ * * For some (most?), if used at the start of a line, they will cause the
+ *   line to be interpreted as a specific kind of statement, which would be
+ *   confusing.
+ *
+ * * `true` or `false` as identifiers would always be shadowed by
+ *   the boolean constants
+ */
 fn restricted_keyword_table() -> hashmap<str, ()> {
     let words = str_hash();
     let keys = ~[
diff --git a/src/libsyntax/syntax.rc b/src/libsyntax/syntax.rc
index cf4d24b8599cc..bb0f82e89fc6a 100644
--- a/src/libsyntax/syntax.rc
+++ b/src/libsyntax/syntax.rc
@@ -44,13 +44,13 @@ mod parse {
     mod comments;
     mod attr;
 
-    #[doc = "Common routines shared by parser mods"]
+    /// Common routines shared by parser mods
     mod common;
 
-    #[doc = "Functions dealing with operator precedence"]
+    /// Functions dealing with operator precedence
     mod prec;
 
-    #[doc = "Routines the parser uses to classify AST nodes"]
+    /// Routines the parser uses to classify AST nodes
     mod classify;
 }
 
diff --git a/src/rustc/driver/driver.rs b/src/rustc/driver/driver.rs
index e5efbd1dc571f..799f34377ede4 100644
--- a/src/rustc/driver/driver.rs
+++ b/src/rustc/driver/driver.rs
@@ -18,10 +18,10 @@ import std::map::hashmap;
 enum pp_mode {ppm_normal, ppm_expanded, ppm_typed, ppm_identified,
               ppm_expanded_identified }
 
-#[doc = "
-The name used for source code that doesn't originate in a file
-(e.g. source from stdin or a string)
-"]
+/**
+ * The name used for source code that doesn't originate in a file
+ * (e.g. source from stdin or a string)
+ */
 fn anon_src() -> str { "<anon>" }
 
 fn source_name(input: input) -> str {
@@ -88,9 +88,9 @@ fn parse_cfgspecs(cfgspecs: ~[str]) -> ast::crate_cfg {
 }
 
 enum input {
-    #[doc = "Load source from file"]
+    /// Load source from file
     file_input(str),
-    #[doc = "The string is the source"]
+    /// The string is the source
     str_input(str)
 }
 
diff --git a/src/rustc/driver/session.rs b/src/rustc/driver/session.rs
index 634134ace33cf..49c829adc00ee 100644
--- a/src/rustc/driver/session.rs
+++ b/src/rustc/driver/session.rs
@@ -167,7 +167,7 @@ impl session for session {
     fn fast_resolve() -> bool { self.debugging_opt(fast_resolve) }
 }
 
-#[doc = "Some reasonable defaults"]
+/// Some reasonable defaults
 fn basic_options() -> @options {
     @{
         crate_type: session::lib_crate,
diff --git a/src/rustc/metadata/creader.rs b/src/rustc/metadata/creader.rs
index bb00142712101..c755235f4e896 100644
--- a/src/rustc/metadata/creader.rs
+++ b/src/rustc/metadata/creader.rs
@@ -1,8 +1,4 @@
-#[doc = "
-
-Validates all used crates and extern libraries and loads their metadata
-
-"];
+//! Validates all used crates and extern libraries and loads their metadata
 
 import syntax::diagnostic::span_handler;
 import syntax::{ast, ast_util};
diff --git a/src/rustc/metadata/csearch.rs b/src/rustc/metadata/csearch.rs
index 4943e3e3e6e8c..aec32aecc4309 100644
--- a/src/rustc/metadata/csearch.rs
+++ b/src/rustc/metadata/csearch.rs
@@ -82,7 +82,7 @@ fn resolve_path(cstore: cstore::cstore, cnum: ast::crate_num,
     ret result;
 }
 
-#[doc="Iterates over all the paths in the given crate."]
+/// Iterates over all the paths in the given crate.
 fn each_path(cstore: cstore::cstore, cnum: ast::crate_num,
              f: fn(decoder::path_entry) -> bool) {
     let crate_data = cstore::get_crate_data(cstore, cnum);
diff --git a/src/rustc/metadata/decoder.rs b/src/rustc/metadata/decoder.rs
index b35fb258b1cc2..21cfd77bd1604 100644
--- a/src/rustc/metadata/decoder.rs
+++ b/src/rustc/metadata/decoder.rs
@@ -414,7 +414,7 @@ class path_entry {
     }
 }
 
-#[doc="Iterates over all the paths in the given crate."]
+/// Iterates over all the paths in the given crate.
 fn each_path(cdata: cmd, f: fn(path_entry) -> bool) {
     let root = ebml::doc(cdata.data);
     let items = ebml::get_doc(root, tag_items);
diff --git a/src/rustc/metadata/loader.rs b/src/rustc/metadata/loader.rs
index 9b9571de413db..63f3658a4e93e 100644
--- a/src/rustc/metadata/loader.rs
+++ b/src/rustc/metadata/loader.rs
@@ -1,8 +1,4 @@
-#[doc = "
-
-Finds crate binaries and loads their metadata
-
-"];
+//! Finds crate binaries and loads their metadata
 
 import syntax::diagnostic::span_handler;
 import syntax::{ast, attr};
diff --git a/src/rustc/middle/borrowck.rs b/src/rustc/middle/borrowck.rs
index 69b38cc1b2cf5..38559aec28dd2 100644
--- a/src/rustc/middle/borrowck.rs
+++ b/src/rustc/middle/borrowck.rs
@@ -1,152 +1,150 @@
-#[doc = "
-
-# Borrow check
-
-This pass is in job of enforcing *memory safety* and *purity*.  As
-memory safety is by far the more complex topic, I'll focus on that in
-this description, but purity will be covered later on. In the context
-of Rust, memory safety means three basic things:
-
-- no writes to immutable memory;
-- all pointers point to non-freed memory;
-- all pointers point to memory of the same type as the pointer.
-
-The last point might seem confusing: after all, for the most part,
-this condition is guaranteed by the type check.  However, there are
-two cases where the type check effectively delegates to borrow check.
-
-The first case has to do with enums.  If there is a pointer to the
-interior of an enum, and the enum is in a mutable location (such as a
-local variable or field declared to be mutable), it is possible that
-the user will overwrite the enum with a new value of a different
-variant, and thus effectively change the type of the memory that the
-pointer is pointing at.
-
-The second case has to do with mutability.  Basically, the type
-checker has only a limited understanding of mutability.  It will allow
-(for example) the user to get an immutable pointer with the address of
-a mutable local variable.  It will also allow a `@mut T` or `~mut T`
-pointer to be borrowed as a `&r.T` pointer.  These seeming oversights
-are in fact intentional; they allow the user to temporarily treat a
-mutable value as immutable.  It is up to the borrow check to guarantee
-that the value in question is not in fact mutated during the lifetime
-`r` of the reference.
-
-# Summary of the safety check
-
-In order to enforce mutability, the borrow check has three tricks up
-its sleeve.
-
-First, data which is uniquely tied to the current stack frame (that'll
-be defined shortly) is tracked very precisely.  This means that, for
-example, if an immutable pointer to a mutable local variable is
-created, the borrowck will simply check for assignments to that
-particular local variable: no other memory is affected.
-
-Second, if the data is not uniquely tied to the stack frame, it may
-still be possible to ensure its validity by rooting garbage collected
-pointers at runtime.  For example, if there is a mutable local
-variable `x` of type `@T`, and its contents are borrowed with an
-expression like `&*x`, then the value of `x` will be rooted (today,
-that means its ref count will be temporary increased) for the lifetime
-of the reference that is created.  This means that the pointer remains
-valid even if `x` is reassigned.
-
-Finally, if neither of these two solutions are applicable, then we
-require that all operations within the scope of the reference be
-*pure*.  A pure operation is effectively one that does not write to
-any aliasable memory.  This means that it is still possible to write
-to local variables or other data that is uniquely tied to the stack
-frame (there's that term again; formal definition still pending) but
-not to data reached via a `&T` or `@T` pointer.  Such writes could
-possibly have the side-effect of causing the data which must remain
-valid to be overwritten.
-
-# Possible future directions
-
-There are numerous ways that the `borrowck` could be strengthened, but
-these are the two most likely:
-
-- flow-sensitivity: we do not currently consider flow at all but only
-  block-scoping.  This means that innocent code like the following is
-  rejected:
-
-      let mut x: int;
-      ...
-      x = 5;
-      let y: &int = &x; // immutable ptr created
-      ...
-
-  The reason is that the scope of the pointer `y` is the entire
-  enclosing block, and the assignment `x = 5` occurs within that
-  block.  The analysis is not smart enough to see that `x = 5` always
-  happens before the immutable pointer is created.  This is relatively
-  easy to fix and will surely be fixed at some point.
-
-- finer-grained purity checks: currently, our fallback for
-  guaranteeing random references into mutable, aliasable memory is to
-  require *total purity*.  This is rather strong.  We could use local
-  type-based alias analysis to distinguish writes that could not
-  possibly invalid the references which must be guaranteed.  This
-  would only work within the function boundaries; function calls would
-  still require total purity.  This seems less likely to be
-  implemented in the short term as it would make the code
-  significantly more complex; there is currently no code to analyze
-  the types and determine the possible impacts of a write.
-
-# Terminology
-
-A **loan** is .
-
-# How the code works
-
-The borrow check code is divided into several major modules, each of
-which is documented in its own file.
-
-The `gather_loans` and `check_loans` are the two major passes of the
-analysis.  The `gather_loans` pass runs over the IR once to determine
-what memory must remain valid and for how long.  Its name is a bit of
-a misnomer; it does in fact gather up the set of loans which are
-granted, but it also determines when @T pointers must be rooted and
-for which scopes purity must be required.
-
-The `check_loans` pass walks the IR and examines the loans and purity
-requirements computed in `gather_loans`.  It checks to ensure that (a)
-the conditions of all loans are honored; (b) no contradictory loans
-were granted (for example, loaning out the same memory as mutable and
-immutable simultaneously); and (c) any purity requirements are
-honored.
-
-The remaining modules are helper modules used by `gather_loans` and
-`check_loans`:
-
-- `categorization` has the job of analyzing an expression to determine
-  what kind of memory is used in evaluating it (for example, where
-  dereferences occur and what kind of pointer is dereferenced; whether
-  the memory is mutable; etc)
-- `loan` determines when data uniquely tied to the stack frame can be
-  loaned out.
-- `preserve` determines what actions (if any) must be taken to preserve
-  aliasable data.  This is the code which decides when to root
-  an @T pointer or to require purity.
-
-# Maps that are created
-
-Borrowck results in two maps.
-
-- `root_map`: identifies those expressions or patterns whose result
-  needs to be rooted.  Conceptually the root_map maps from an
-  expression or pattern node to a `node_id` identifying the scope for
-  which the expression must be rooted (this `node_id` should identify
-  a block or call).  The actual key to the map is not an expression id,
-  however, but a `root_map_key`, which combines an expression id with a
-  deref count and is used to cope with auto-deref.
-
-- `mutbl_map`: identifies those local variables which are modified or
-  moved. This is used by trans to guarantee that such variables are
-  given a memory location and not used as immediates.
-
-"];
+/*!
+ * # Borrow check
+ *
+ * This pass is in job of enforcing *memory safety* and *purity*.  As
+ * memory safety is by far the more complex topic, I'll focus on that in
+ * this description, but purity will be covered later on. In the context
+ * of Rust, memory safety means three basic things:
+ *
+ * - no writes to immutable memory;
+ * - all pointers point to non-freed memory;
+ * - all pointers point to memory of the same type as the pointer.
+ *
+ * The last point might seem confusing: after all, for the most part,
+ * this condition is guaranteed by the type check.  However, there are
+ * two cases where the type check effectively delegates to borrow check.
+ *
+ * The first case has to do with enums.  If there is a pointer to the
+ * interior of an enum, and the enum is in a mutable location (such as a
+ * local variable or field declared to be mutable), it is possible that
+ * the user will overwrite the enum with a new value of a different
+ * variant, and thus effectively change the type of the memory that the
+ * pointer is pointing at.
+ *
+ * The second case has to do with mutability.  Basically, the type
+ * checker has only a limited understanding of mutability.  It will allow
+ * (for example) the user to get an immutable pointer with the address of
+ * a mutable local variable.  It will also allow a `@mut T` or `~mut T`
+ * pointer to be borrowed as a `&r.T` pointer.  These seeming oversights
+ * are in fact intentional; they allow the user to temporarily treat a
+ * mutable value as immutable.  It is up to the borrow check to guarantee
+ * that the value in question is not in fact mutated during the lifetime
+ * `r` of the reference.
+ *
+ * # Summary of the safety check
+ *
+ * In order to enforce mutability, the borrow check has three tricks up
+ * its sleeve.
+ *
+ * First, data which is uniquely tied to the current stack frame (that'll
+ * be defined shortly) is tracked very precisely.  This means that, for
+ * example, if an immutable pointer to a mutable local variable is
+ * created, the borrowck will simply check for assignments to that
+ * particular local variable: no other memory is affected.
+ *
+ * Second, if the data is not uniquely tied to the stack frame, it may
+ * still be possible to ensure its validity by rooting garbage collected
+ * pointers at runtime.  For example, if there is a mutable local
+ * variable `x` of type `@T`, and its contents are borrowed with an
+ * expression like `&*x`, then the value of `x` will be rooted (today,
+ * that means its ref count will be temporary increased) for the lifetime
+ * of the reference that is created.  This means that the pointer remains
+ * valid even if `x` is reassigned.
+ *
+ * Finally, if neither of these two solutions are applicable, then we
+ * require that all operations within the scope of the reference be
+ * *pure*.  A pure operation is effectively one that does not write to
+ * any aliasable memory.  This means that it is still possible to write
+ * to local variables or other data that is uniquely tied to the stack
+ * frame (there's that term again; formal definition still pending) but
+ * not to data reached via a `&T` or `@T` pointer.  Such writes could
+ * possibly have the side-effect of causing the data which must remain
+ * valid to be overwritten.
+ *
+ * # Possible future directions
+ *
+ * There are numerous ways that the `borrowck` could be strengthened, but
+ * these are the two most likely:
+ *
+ * - flow-sensitivity: we do not currently consider flow at all but only
+ *   block-scoping.  This means that innocent code like the following is
+ *   rejected:
+ *
+ *       let mut x: int;
+ *       ...
+ *       x = 5;
+ *       let y: &int = &x; // immutable ptr created
+ *       ...
+ *
+ *   The reason is that the scope of the pointer `y` is the entire
+ *   enclosing block, and the assignment `x = 5` occurs within that
+ *   block.  The analysis is not smart enough to see that `x = 5` always
+ *   happens before the immutable pointer is created.  This is relatively
+ *   easy to fix and will surely be fixed at some point.
+ *
+ * - finer-grained purity checks: currently, our fallback for
+ *   guaranteeing random references into mutable, aliasable memory is to
+ *   require *total purity*.  This is rather strong.  We could use local
+ *   type-based alias analysis to distinguish writes that could not
+ *   possibly invalid the references which must be guaranteed.  This
+ *   would only work within the function boundaries; function calls would
+ *   still require total purity.  This seems less likely to be
+ *   implemented in the short term as it would make the code
+ *   significantly more complex; there is currently no code to analyze
+ *   the types and determine the possible impacts of a write.
+ *
+ * # Terminology
+ *
+ * A **loan** is .
+ *
+ * # How the code works
+ *
+ * The borrow check code is divided into several major modules, each of
+ * which is documented in its own file.
+ *
+ * The `gather_loans` and `check_loans` are the two major passes of the
+ * analysis.  The `gather_loans` pass runs over the IR once to determine
+ * what memory must remain valid and for how long.  Its name is a bit of
+ * a misnomer; it does in fact gather up the set of loans which are
+ * granted, but it also determines when @T pointers must be rooted and
+ * for which scopes purity must be required.
+ *
+ * The `check_loans` pass walks the IR and examines the loans and purity
+ * requirements computed in `gather_loans`.  It checks to ensure that (a)
+ * the conditions of all loans are honored; (b) no contradictory loans
+ * were granted (for example, loaning out the same memory as mutable and
+ * immutable simultaneously); and (c) any purity requirements are
+ * honored.
+ *
+ * The remaining modules are helper modules used by `gather_loans` and
+ * `check_loans`:
+ *
+ * - `categorization` has the job of analyzing an expression to determine
+ *   what kind of memory is used in evaluating it (for example, where
+ *   dereferences occur and what kind of pointer is dereferenced; whether
+ *   the memory is mutable; etc)
+ * - `loan` determines when data uniquely tied to the stack frame can be
+ *   loaned out.
+ * - `preserve` determines what actions (if any) must be taken to preserve
+ *   aliasable data.  This is the code which decides when to root
+ *   an @T pointer or to require purity.
+ *
+ * # Maps that are created
+ *
+ * Borrowck results in two maps.
+ *
+ * - `root_map`: identifies those expressions or patterns whose result
+ *   needs to be rooted.  Conceptually the root_map maps from an
+ *   expression or pattern node to a `node_id` identifying the scope for
+ *   which the expression must be rooted (this `node_id` should identify
+ *   a block or call).  The actual key to the map is not an expression id,
+ *   however, but a `root_map_key`, which combines an expression id with a
+ *   deref count and is used to cope with auto-deref.
+ *
+ * - `mutbl_map`: identifies those local variables which are modified or
+ *   moved. This is used by trans to guarantee that such variables are
+ *   given a memory location and not used as immediates.
+ */
 
 import syntax::ast;
 import syntax::ast::{mutability, m_mutbl, m_imm, m_const};
@@ -304,7 +302,7 @@ fn save_and_restore<T:copy,U>(&save_and_restore_t: T, f: fn() -> U) -> U {
     ret u;
 }
 
-#[doc = "Creates and returns a new root_map"]
+/// Creates and returns a new root_map
 fn root_map() -> root_map {
     ret hashmap(root_map_key_hash, root_map_key_eq);
 
diff --git a/src/rustc/middle/borrowck/categorization.rs b/src/rustc/middle/borrowck/categorization.rs
index 7df58bf43d03a..deccf0af2b46d 100644
--- a/src/rustc/middle/borrowck/categorization.rs
+++ b/src/rustc/middle/borrowck/categorization.rs
@@ -1,41 +1,40 @@
-#[doc = "
-
-# Categorization
-
-The job of the categorization module is to analyze an expression to
-determine what kind of memory is used in evaluating it (for example,
-where dereferences occur and what kind of pointer is dereferenced;
-whether the memory is mutable; etc)
-
-Categorization effectively transforms all of our expressions into
-expressions of the following forms (the actual enum has many more
-possibilities, naturally, but they are all variants of these base
-forms):
-
-    E = rvalue    // some computed rvalue
-      | x         // address of a local variable, arg, or upvar
-      | *E        // deref of a ptr
-      | E.comp    // access to an interior component
-
-Imagine a routine ToAddr(Expr) that evaluates an expression and returns an
-address where the result is to be found.  If Expr is an lvalue, then this
-is the address of the lvalue.  If Expr is an rvalue, this is the address of
-some temporary spot in memory where the result is stored.
-
-Now, cat_expr() classies the expression Expr and the address A=ToAddr(Expr)
-as follows:
-
-- cat: what kind of expression was this?  This is a subset of the
-  full expression forms which only includes those that we care about
-  for the purpose of the analysis.
-- mutbl: mutability of the address A
-- ty: the type of data found at the address A
-
-The resulting categorization tree differs somewhat from the expressions
-themselves.  For example, auto-derefs are explicit.  Also, an index a[b] is
-decomposed into two operations: a derefence to reach the array data and
-then an index to jump forward to the relevant item.
-"];
+/*!
+ * # Categorization
+ *
+ * The job of the categorization module is to analyze an expression to
+ * determine what kind of memory is used in evaluating it (for example,
+ * where dereferences occur and what kind of pointer is dereferenced;
+ * whether the memory is mutable; etc)
+ *
+ * Categorization effectively transforms all of our expressions into
+ * expressions of the following forms (the actual enum has many more
+ * possibilities, naturally, but they are all variants of these base
+ * forms):
+ *
+ *     E = rvalue    // some computed rvalue
+ *       | x         // address of a local variable, arg, or upvar
+ *       | *E        // deref of a ptr
+ *       | E.comp    // access to an interior component
+ *
+ * Imagine a routine ToAddr(Expr) that evaluates an expression and returns an
+ * address where the result is to be found.  If Expr is an lvalue, then this
+ * is the address of the lvalue.  If Expr is an rvalue, this is the address of
+ * some temporary spot in memory where the result is stored.
+ *
+ * Now, cat_expr() classies the expression Expr and the address A=ToAddr(Expr)
+ * as follows:
+ *
+ * - cat: what kind of expression was this?  This is a subset of the
+ *   full expression forms which only includes those that we care about
+ *   for the purpose of the analysis.
+ * - mutbl: mutability of the address A
+ * - ty: the type of data found at the address A
+ *
+ * The resulting categorization tree differs somewhat from the expressions
+ * themselves.  For example, auto-derefs are explicit.  Also, an index a[b] is
+ * decomposed into two operations: a derefence to reach the array data and
+ * then an index to jump forward to the relevant item.
+ */
 
 export public_methods;
 export opt_deref_kind;
diff --git a/src/rustc/middle/lint.rs b/src/rustc/middle/lint.rs
index 3c8083e7f76c8..11d26ddbbb180 100644
--- a/src/rustc/middle/lint.rs
+++ b/src/rustc/middle/lint.rs
@@ -17,27 +17,26 @@ export get_warning_level, get_warning_settings_level;
 export check_crate, build_settings_crate, mk_warning_settings;
 export warning_settings;
 
-#[doc="
-
-A 'lint' check is a kind of miscellaneous constraint that a user _might_ want
-to enforce, but might reasonably want to permit as well, on a module-by-module
-basis. They contrast with static constraints enforced by other phases of the
-compiler, which are generally required to hold in order to compile the program
-at all.
-
-We also build up a table containing information about lint settings, in order
-to allow other passes to take advantage of the warning attribute
-infrastructure. To save space, the table is keyed by the id of /items/, not of
-every expression. When an item has the default settings, the entry will be
-omitted. If we start allowing warn attributes on expressions, we will start
-having entries for expressions that do not share their enclosing items
-settings.
-
-This module then, exports two passes: one that populates the warning settings
-table in the session and is run early in the compile process, and one that
-does a variety of lint checks, and is run late in the compile process.
-
-"]
+/**
+ * A 'lint' check is a kind of miscellaneous constraint that a user _might_
+ * want to enforce, but might reasonably want to permit as well, on a
+ * module-by-module basis. They contrast with static constraints enforced by
+ * other phases of the compiler, which are generally required to hold in order
+ * to compile the program at all.
+ *
+ * We also build up a table containing information about lint settings, in
+ * order to allow other passes to take advantage of the warning attribute
+ * infrastructure. To save space, the table is keyed by the id of /items/, not
+ * of every expression. When an item has the default settings, the entry will
+ * be omitted. If we start allowing warn attributes on expressions, we will
+ * start having entries for expressions that do not share their enclosing
+ * items settings.
+ *
+ * This module then, exports two passes: one that populates the warning
+ * settings table in the session and is run early in the compile process, and
+ * one that does a variety of lint checks, and is run late in the compile
+ * process.
+ */
 
 enum lint {
     ctypes,
@@ -203,11 +202,11 @@ impl methods for ctxt {
         self.sess.span_lint_level(level, span, msg);
     }
 
-    #[doc="
-          Merge the warnings specified by any `warn(...)` attributes into the
-          current lint context, call the provided function, then reset the
-          warnings in effect to their previous state.
-    "]
+    /**
+     * Merge the warnings specified by any `warn(...)` attributes into the
+     * current lint context, call the provided function, then reset the
+     * warnings in effect to their previous state.
+     */
     fn with_warn_attrs(attrs: ~[ast::attribute], f: fn(ctxt)) {
 
         let mut new_ctxt = self;
diff --git a/src/rustc/middle/liveness.rs b/src/rustc/middle/liveness.rs
index fd6033c5b9d9f..2f87f6d55de79 100644
--- a/src/rustc/middle/liveness.rs
+++ b/src/rustc/middle/liveness.rs
@@ -1,106 +1,104 @@
-#[doc = "
-
-A classic liveness analysis based on dataflow over the AST.  Computes,
-for each local variable in a function, whether that variable is live
-at a given point.  Program execution points are identified by their
-id.
-
-# Basic idea
-
-The basic model is that each local variable is assigned an index.  We
-represent sets of local variables using a vector indexed by this
-index.  The value in the vector is either 0, indicating the variable
-is dead, or the id of an expression that uses the variable.
-
-We conceptually walk over the AST in reverse execution order.  If we
-find a use of a variable, we add it to the set of live variables.  If
-we find an assignment to a variable, we remove it from the set of live
-variables.  When we have to merge two flows, we take the union of
-those two flows---if the variable is live on both paths, we simply
-pick one id.  In the event of loops, we continue doing this until a
-fixed point is reached.
-
-## Checking initialization
-
-At the function entry point, all variables must be dead.  If this is
-not the case, we can report an error using the id found in the set of
-live variables, which identifies a use of the variable which is not
-dominated by an assignment.
-
-## Checking moves
-
-After each explicit move, the variable must be dead.
-
-## Computing last uses
-
-Any use of the variable where the variable is dead afterwards is a
-last use.
-
-# Extension to handle constructors
-
-Each field is assigned an index just as with local variables.  A use of
-`self` is considered a use of all fields.  A use of `self.f` is just a use
-of `f`.
-
-# Implementation details
-
-The actual implementation contains two (nested) walks over the AST.
-The outer walk has the job of building up the ir_maps instance for the
-enclosing function.  On the way down the tree, it identifies those AST
-nodes and variable IDs that will be needed for the liveness analysis
-and assigns them contiguous IDs.  The liveness id for an AST node is
-called a `live_node` (it's a newtype'd uint) and the id for a variable
-is called a `variable` (another newtype'd uint).
-
-On the way back up the tree, as we are about to exit from a function
-declaration we allocate a `liveness` instance.  Now that we know
-precisely how many nodes and variables we need, we can allocate all
-the various arrays that we will need to precisely the right size.  We then
-perform the actual propagation on the `liveness` instance.
-
-This propagation is encoded in the various `propagate_through_*()`
-methods.  It effectively does a reverse walk of the AST; whenever we
-reach a loop node, we iterate until a fixed point is reached.
-
-## The `users` struct
-
-At each live node `N`, we track three pieces of information for each
-variable `V` (these are encapsulated in the `users` struct):
-
-- `reader`: the `live_node` ID of some node which will read the value
-   that `V` holds on entry to `N`.  Formally: a node `M` such
-   that there exists a path `P` from `N` to `M` where `P` does not
-   write `V`.  If the `reader` is `invalid_node()`, then the current
-   value will never be read (the variable is dead, essentially).
-
-- `writer`: the `live_node` ID of some node which will write the
-   variable `V` and which is reachable from `N`.  Formally: a node `M`
-   such that there exists a path `P` from `N` to `M` and `M` writes
-   `V`.  If the `writer` is `invalid_node()`, then there is no writer
-   of `V` that follows `N`.
-
-- `used`: a boolean value indicating whether `V` is *used*.  We
-  distinguish a *read* from a *use* in that a *use* is some read that
-  is not just used to generate a new value.  For example, `x += 1` is
-  a read but not a use.  This is used to generate better warnings.
-
-## Special Variables
-
-We generate various special variables for various, well, special purposes.
-These are described in the `specials` struct:
-
-- `exit_ln`: a live node that is generated to represent every 'exit' from the
-  function, whether it be by explicit return, fail, or other means.
-
-- `fallthrough_ln`: a live node that represents a fallthrough
-
-- `no_ret_var`: a synthetic variable that is only 'read' from, the
-  fallthrough node.  This allows us to detect functions where we fail
-  to return explicitly.
-
-- `self_var`: a variable representing 'self'
-
-"];
+/*!
+ * A classic liveness analysis based on dataflow over the AST.  Computes,
+ * for each local variable in a function, whether that variable is live
+ * at a given point.  Program execution points are identified by their
+ * id.
+ *
+ * # Basic idea
+ *
+ * The basic model is that each local variable is assigned an index.  We
+ * represent sets of local variables using a vector indexed by this
+ * index.  The value in the vector is either 0, indicating the variable
+ * is dead, or the id of an expression that uses the variable.
+ *
+ * We conceptually walk over the AST in reverse execution order.  If we
+ * find a use of a variable, we add it to the set of live variables.  If
+ * we find an assignment to a variable, we remove it from the set of live
+ * variables.  When we have to merge two flows, we take the union of
+ * those two flows---if the variable is live on both paths, we simply
+ * pick one id.  In the event of loops, we continue doing this until a
+ * fixed point is reached.
+ *
+ * ## Checking initialization
+ *
+ * At the function entry point, all variables must be dead.  If this is
+ * not the case, we can report an error using the id found in the set of
+ * live variables, which identifies a use of the variable which is not
+ * dominated by an assignment.
+ *
+ * ## Checking moves
+ *
+ * After each explicit move, the variable must be dead.
+ *
+ * ## Computing last uses
+ *
+ * Any use of the variable where the variable is dead afterwards is a
+ * last use.
+ *
+ * # Extension to handle constructors
+ *
+ * Each field is assigned an index just as with local variables.  A use of
+ * `self` is considered a use of all fields.  A use of `self.f` is just a use
+ * of `f`.
+ *
+ * # Implementation details
+ *
+ * The actual implementation contains two (nested) walks over the AST.
+ * The outer walk has the job of building up the ir_maps instance for the
+ * enclosing function.  On the way down the tree, it identifies those AST
+ * nodes and variable IDs that will be needed for the liveness analysis
+ * and assigns them contiguous IDs.  The liveness id for an AST node is
+ * called a `live_node` (it's a newtype'd uint) and the id for a variable
+ * is called a `variable` (another newtype'd uint).
+ *
+ * On the way back up the tree, as we are about to exit from a function
+ * declaration we allocate a `liveness` instance.  Now that we know
+ * precisely how many nodes and variables we need, we can allocate all
+ * the various arrays that we will need to precisely the right size.  We then
+ * perform the actual propagation on the `liveness` instance.
+ *
+ * This propagation is encoded in the various `propagate_through_*()`
+ * methods.  It effectively does a reverse walk of the AST; whenever we
+ * reach a loop node, we iterate until a fixed point is reached.
+ *
+ * ## The `users` struct
+ *
+ * At each live node `N`, we track three pieces of information for each
+ * variable `V` (these are encapsulated in the `users` struct):
+ *
+ * - `reader`: the `live_node` ID of some node which will read the value
+ *    that `V` holds on entry to `N`.  Formally: a node `M` such
+ *    that there exists a path `P` from `N` to `M` where `P` does not
+ *    write `V`.  If the `reader` is `invalid_node()`, then the current
+ *    value will never be read (the variable is dead, essentially).
+ *
+ * - `writer`: the `live_node` ID of some node which will write the
+ *    variable `V` and which is reachable from `N`.  Formally: a node `M`
+ *    such that there exists a path `P` from `N` to `M` and `M` writes
+ *    `V`.  If the `writer` is `invalid_node()`, then there is no writer
+ *    of `V` that follows `N`.
+ *
+ * - `used`: a boolean value indicating whether `V` is *used*.  We
+ *   distinguish a *read* from a *use* in that a *use* is some read that
+ *   is not just used to generate a new value.  For example, `x += 1` is
+ *   a read but not a use.  This is used to generate better warnings.
+ *
+ * ## Special Variables
+ *
+ * We generate various special variables for various, well, special purposes.
+ * These are described in the `specials` struct:
+ *
+ * - `exit_ln`: a live node that is generated to represent every 'exit' from
+ *   the function, whether it be by explicit return, fail, or other means.
+ *
+ * - `fallthrough_ln`: a live node that represents a fallthrough
+ *
+ * - `no_ret_var`: a synthetic variable that is only 'read' from, the
+ *   fallthrough node.  This allows us to detect functions where we fail
+ *   to return explicitly.
+ *
+ * - `self_var`: a variable representing 'self'
+ */
 
 import dvec::{dvec, extensions};
 import std::map::{hashmap, int_hash, str_hash, box_str_hash};
diff --git a/src/rustc/middle/resolve3.rs b/src/rustc/middle/resolve3.rs
index 892c97d7869f1..db52ad482ac8f 100644
--- a/src/rustc/middle/resolve3.rs
+++ b/src/rustc/middle/resolve3.rs
@@ -109,13 +109,13 @@ enum ModuleDef {
     ModuleDef(@Module),     // Defines a module.
 }
 
-#[doc="Contains data for specific types of import directives."]
+/// Contains data for specific types of import directives.
 enum ImportDirectiveSubclass {
     SingleImport(Atom /* target */, Atom /* source */),
     GlobImport
 }
 
-#[doc="The context that we thread through while building the reduced graph."]
+/// The context that we thread through while building the reduced graph.
 enum ReducedGraphParent {
     ModuleReducedGraphParent(@Module)
 }
@@ -235,15 +235,15 @@ class AtomTable {
     }
 }
 
-#[doc="Creates a hash table of atoms."]
+/// Creates a hash table of atoms.
 fn atom_hashmap<V:copy>() -> hashmap<Atom,V> {
     ret hashmap::<Atom,V>(|a| a, |a, b| a == b);
 }
 
-#[doc="
-    One local scope. In Rust, local scopes can only contain value bindings.
-    Therefore, we don't have to worry about the other namespaces here.
-"]
+/**
+ * One local scope. In Rust, local scopes can only contain value bindings.
+ * Therefore, we don't have to worry about the other namespaces here.
+ */
 class Rib {
     let bindings: hashmap<Atom,def_like>;
     let kind: RibKind;
@@ -254,7 +254,7 @@ class Rib {
     }
 }
 
-#[doc="One import directive."]
+/// One import directive.
 class ImportDirective {
     let module_path: @dvec<Atom>;
     let subclass: @ImportDirectiveSubclass;
@@ -265,7 +265,7 @@ class ImportDirective {
     }
 }
 
-#[doc="The item that an import resolves to."]
+/// The item that an import resolves to.
 class Target {
     let target_module: @Module;
     let bindings: @NameBindings;
@@ -313,14 +313,14 @@ class ImportResolution {
     }
 }
 
-#[doc="The link from a module up to its nearest parent node."]
+/// The link from a module up to its nearest parent node.
 enum ParentLink {
     NoParentLink,
     ModuleParentLink(@Module, Atom),
     BlockParentLink(@Module, node_id)
 }
 
-#[doc="One node in the tree of modules."]
+/// One node in the tree of modules.
 class Module {
     let parent_link: ParentLink;
     let mut def_id: option<def_id>;
@@ -398,10 +398,10 @@ pure fn is_none<T>(x: option<T>) -> bool {
     }
 }
 
-#[doc="
-    Records the definitions (at most one for each namespace) that a name is
-    bound to.
-"]
+/**
+ * Records the definitions (at most one for each namespace) that a name is
+ * bound to.
+ */
 class NameBindings {
     let mut module_def: ModuleDef;      //< Meaning in the module namespace.
     let mut type_def: option<def>;      //< Meaning in the type namespace.
@@ -415,7 +415,7 @@ class NameBindings {
         self.impl_defs = ~[];
     }
 
-    #[doc="Creates a new module in this set of name bindings."]
+    /// Creates a new module in this set of name bindings.
     fn define_module(parent_link: ParentLink, def_id: option<def_id>) {
         if self.module_def == NoModuleDef {
             let module = @Module(parent_link, def_id);
@@ -423,22 +423,22 @@ class NameBindings {
         }
     }
 
-    #[doc="Records a type definition."]
+    /// Records a type definition.
     fn define_type(def: def) {
         self.type_def = some(def);
     }
 
-    #[doc="Records a value definition."]
+    /// Records a value definition.
     fn define_value(def: def) {
         self.value_def = some(def);
     }
 
-    #[doc="Records an impl definition."]
+    /// Records an impl definition.
     fn define_impl(implementation: @Impl) {
         self.impl_defs += ~[implementation];
     }
 
-    #[doc="Returns the module node if applicable."]
+    /// Returns the module node if applicable.
     fn get_module_if_available() -> option<@Module> {
         alt self.module_def {
             NoModuleDef         { ret none;         }
@@ -446,10 +446,10 @@ class NameBindings {
         }
     }
 
-    #[doc="
-        Returns the module node. Fails if this node does not have a module
-        definition.
-    "]
+    /**
+     * Returns the module node. Fails if this node does not have a module
+     * definition.
+     */
     fn get_module() -> @Module {
         alt self.module_def {
             NoModuleDef {
@@ -508,7 +508,7 @@ class NameBindings {
     }
 }
 
-#[doc="Interns the names of the primitive types."]
+/// Interns the names of the primitive types.
 class PrimitiveTypeTable {
     let primitive_types: hashmap<Atom,prim_ty>;
 
@@ -539,7 +539,7 @@ class PrimitiveTypeTable {
     }
 }
 
-#[doc="The main resolver class."]
+/// The main resolver class.
 class Resolver {
     let session: session;
     let ast_map: ASTMap;
@@ -611,7 +611,7 @@ class Resolver {
         self.export_map = int_hash();
     }
 
-    #[doc="The main name resolution procedure."]
+    /// The main name resolution procedure.
     fn resolve(this: @Resolver) {
         self.build_reduced_graph(this);
         self.resolve_imports();
@@ -627,7 +627,7 @@ class Resolver {
     // any imports resolved.
     //
 
-    #[doc="Constructs the reduced graph for the entire crate."]
+    /// Constructs the reduced graph for the entire crate.
     fn build_reduced_graph(this: @Resolver) {
         let initial_parent =
             ModuleReducedGraphParent((*self.graph_root).get_module());
@@ -654,7 +654,7 @@ class Resolver {
         }));
     }
 
-    #[doc="Returns the current module tracked by the reduced graph parent."]
+    /// Returns the current module tracked by the reduced graph parent.
     fn get_module_from_parent(reduced_graph_parent: ReducedGraphParent)
                            -> @Module {
         alt reduced_graph_parent {
@@ -664,16 +664,16 @@ class Resolver {
         }
     }
 
-    #[doc="
-        Adds a new child item to the module definition of the parent node and
-        returns its corresponding name bindings as well as the current parent.
-        Or, if we're inside a block, creates (or reuses) an anonymous module
-        corresponding to the innermost block ID and returns the name bindings
-        as well as the newly-created parent.
-
-        If this node does not have a module definition and we are not inside
-        a block, fails.
-    "]
+    /**
+     * Adds a new child item to the module definition of the parent node and
+     * returns its corresponding name bindings as well as the current parent.
+     * Or, if we're inside a block, creates (or reuses) an anonymous module
+     * corresponding to the innermost block ID and returns the name bindings
+     * as well as the newly-created parent.
+     *
+     * If this node does not have a module definition and we are not inside
+     * a block, fails.
+     */
     fn add_child(name: Atom,
                  reduced_graph_parent: ReducedGraphParent)
               -> (@NameBindings, ReducedGraphParent) {
@@ -742,7 +742,7 @@ class Resolver {
         }
     }
 
-    #[doc="Constructs the reduced graph for one item."]
+    /// Constructs the reduced graph for one item.
     fn build_reduced_graph_for_item(item: @item,
                                     parent: ReducedGraphParent,
                                     &&visitor: vt<ReducedGraphParent>) {
@@ -874,10 +874,10 @@ class Resolver {
         }
     }
 
-    #[doc="
-        Constructs the reduced graph for one variant. Variants exist in the
-        type namespace.
-    "]
+    /**
+     * Constructs the reduced graph for one variant. Variants exist in the
+     * type namespace.
+     */
     fn build_reduced_graph_for_variant(variant: variant,
                                        item_id: def_id,
                                        parent: ReducedGraphParent,
@@ -890,10 +890,10 @@ class Resolver {
                                           local_def(variant.node.id)));
     }
 
-    #[doc="
-        Constructs the reduced graph for one 'view item'. View items consist
-        of imports and use directives.
-    "]
+    /**
+     * Constructs the reduced graph for one 'view item'. View items consist
+     * of imports and use directives.
+     */
     fn build_reduced_graph_for_view_item(view_item: @view_item,
                                          parent: ReducedGraphParent,
                                          &&_visitor: vt<ReducedGraphParent>) {
@@ -1045,7 +1045,7 @@ class Resolver {
         }
     }
 
-    #[doc="Constructs the reduced graph for one foreign item."]
+    /// Constructs the reduced graph for one foreign item.
     fn build_reduced_graph_for_foreign_item(foreign_item: @foreign_item,
                                             parent: ReducedGraphParent,
                                             &&visitor:
@@ -1095,10 +1095,10 @@ class Resolver {
         visit_block(block, new_parent, visitor);
     }
 
-    #[doc="
-        Builds the reduced graph rooted at the 'use' directive for an external
-        crate.
-    "]
+    /**
+     * Builds the reduced graph rooted at the 'use' directive for an external
+     * crate.
+     */
     fn build_reduced_graph_for_external_crate(root: @Module) {
         // Create all the items reachable by paths.
         for each_path(self.session.cstore, get(root.def_id).crate)
@@ -1285,7 +1285,7 @@ class Resolver {
         }
     }
 
-    #[doc="Creates and adds an import directive to the given module."]
+    /// Creates and adds an import directive to the given module.
     fn build_import_directive(module: @Module,
                               module_path: @dvec<Atom>,
                               subclass: @ImportDirectiveSubclass) {
@@ -1328,10 +1328,10 @@ class Resolver {
     // remain or unsuccessfully when no forward progress in resolving imports
     // is made.
 
-    #[doc="
-        Resolves all imports for the crate. This method performs the fixed-
-        point iteration.
-    "]
+    /**
+     * Resolves all imports for the crate. This method performs the fixed-
+     * point iteration.
+     */
     fn resolve_imports() {
         let mut i = 0u;
         let mut prev_unresolved_imports = 0u;
@@ -1358,10 +1358,10 @@ class Resolver {
         }
     }
 
-    #[doc="
-        Attempts to resolve imports for the given module and all of its
-        submodules.
-    "]
+    /**
+     * Attempts to resolve imports for the given module and all of its
+     * submodules.
+     */
     fn resolve_imports_for_module_subtree(module: @Module) {
         #debug("(resolving imports for module subtree) resolving %s",
                self.module_to_str(module));
@@ -1383,7 +1383,7 @@ class Resolver {
         }
     }
 
-    #[doc="Attempts to resolve imports for the given module only."]
+    /// Attempts to resolve imports for the given module only.
     fn resolve_imports_for_module(module: @Module) {
         if (*module).all_imports_resolved() {
             #debug("(resolving imports for module) all imports resolved for \
@@ -1416,13 +1416,13 @@ class Resolver {
         }
     }
 
-    #[doc="
-        Attempts to resolve the given import. The return value indicates
-        failure if we're certain the name does not exist, indeterminate if we
-        don't know whether the name exists at the moment due to other
-        currently-unresolved imports, or success if we know the name exists.
-        If successful, the resolved bindings are written into the module.
-    "]
+    /**
+     * Attempts to resolve the given import. The return value indicates
+     * failure if we're certain the name does not exist, indeterminate if we
+     * don't know whether the name exists at the moment due to other
+     * currently-unresolved imports, or success if we know the name exists.
+     * If successful, the resolved bindings are written into the module.
+     */
     fn resolve_import_for_module(module: @Module,
                                  import_directive: @ImportDirective)
                               -> ResolveResult<()> {
@@ -1721,11 +1721,11 @@ class Resolver {
         ret Success(());
     }
 
-    #[doc="
-        Resolves a glob import. Note that this function cannot fail; it either
-        succeeds or bails out (as importing * from an empty module or a module
-        that exports nothing is valid).
-    "]
+    /**
+     * Resolves a glob import. Note that this function cannot fail; it either
+     * succeeds or bails out (as importing * from an empty module or a module
+     * that exports nothing is valid).
+     */
     fn resolve_glob_import(module: @Module, containing_module: @Module)
                         -> ResolveResult<()> {
 
@@ -1927,10 +1927,10 @@ class Resolver {
         ret Success(search_module);
     }
 
-    #[doc="
-        Attempts to resolve the module part of an import directive rooted at
-        the given module.
-    "]
+    /**
+     * Attempts to resolve the module part of an import directive rooted at
+     * the given module.
+     */
     fn resolve_module_path_for_import(module: @Module,
                                       module_path: @dvec<Atom>,
                                       xray: XrayFlag)
@@ -2093,11 +2093,11 @@ class Resolver {
                 module.exported_names.contains_key(name);
     }
 
-    #[doc="
-        Attempts to resolve the supplied name in the given module for the
-        given namespace. If successful, returns the target corresponding to
-        the name.
-    "]
+    /**
+     * Attempts to resolve the supplied name in the given module for the
+     * given namespace. If successful, returns the target corresponding to
+     * the name.
+     */
     fn resolve_name_in_module(module: @Module,
                               name: Atom,
                               namespace: Namespace,
@@ -2168,11 +2168,11 @@ class Resolver {
         ret Failed;
     }
 
-    #[doc="
-        Resolves a one-level renaming import of the kind `import foo = bar;`
-        This needs special handling, as, unlike all of the other imports, it
-        needs to look in the scope chain for modules and non-modules alike.
-    "]
+    /**
+     * Resolves a one-level renaming import of the kind `import foo = bar;`
+     * This needs special handling, as, unlike all of the other imports, it
+     * needs to look in the scope chain for modules and non-modules alike.
+     */
     fn resolve_one_level_renaming_import(module: @Module,
                                          import_directive: @ImportDirective)
                                       -> ResolveResult<()> {
@@ -3496,10 +3496,10 @@ class Resolver {
         }
     }
 
-    #[doc="
-        If `check_ribs` is true, checks the local definitions first; i.e.
-        doesn't skip straight to the containing module.
-    "]
+    /**
+     * If `check_ribs` is true, checks the local definitions first; i.e.
+     * doesn't skip straight to the containing module.
+     */
     fn resolve_path(path: @path, namespace: Namespace, check_ribs: bool,
                     visitor: ResolveVisitor)
                  -> option<def> {
@@ -3859,7 +3859,7 @@ class Resolver {
     // hit.
     //
 
-    #[doc="A somewhat inefficient routine to print out the name of a module."]
+    /// A somewhat inefficient routine to print out the name of a module.
     fn module_to_str(module: @Module) -> str {
         let atoms = dvec();
         let mut current_module = module;
@@ -3977,7 +3977,7 @@ class Resolver {
     }
 }
 
-#[doc="Entry point to crate resolution."]
+/// Entry point to crate resolution.
 fn resolve_crate(session: session, ast_map: ASTMap, crate: @crate)
               -> { def_map: DefMap, exp_map: ExportMap, impl_map: ImplMap } {
 
diff --git a/src/rustc/middle/trans/base.rs b/src/rustc/middle/trans/base.rs
index 457ffd8e40122..f0af5f421545a 100644
--- a/src/rustc/middle/trans/base.rs
+++ b/src/rustc/middle/trans/base.rs
@@ -2735,14 +2735,14 @@ fn trans_lval(cx: block, e: @ast::expr) -> lval_result {
     }
 }
 
-#[doc = "
-Get the type of a box in the default address space.
-
-Shared box pointers live in address space 1 so the GC strategy can find them.
-Before taking a pointer to the inside of a box it should be cast into address
-space 0. Otherwise the resulting (non-box) pointer will be in the wrong
-address space and thus be the wrong type.
-"]
+/**
+ * Get the type of a box in the default address space.
+ *
+ * Shared box pointers live in address space 1 so the GC strategy can find
+ * them. Before taking a pointer to the inside of a box it should be cast into
+ * address space 0. Otherwise the resulting (non-box) pointer will be in the
+ * wrong address space and thus be the wrong type.
+ */
 fn non_gc_box_cast(cx: block, val: ValueRef) -> ValueRef {
     #debug("non_gc_box_cast");
     add_comment(cx, "non_gc_box_cast");
diff --git a/src/rustc/middle/ty.rs b/src/rustc/middle/ty.rs
index c5ad6f9a00acc..455408b7e5a23 100644
--- a/src/rustc/middle/ty.rs
+++ b/src/rustc/middle/ty.rs
@@ -2996,9 +2996,7 @@ fn ty_params_to_tys(tcx: ty::ctxt, tps: ~[ast::ty_param]) -> ~[t] {
         })
 }
 
-#[doc = "
-Returns an equivalent type with all the typedefs and self regions removed.
-"]
+/// Returns an equivalent type with all the typedefs and self regions removed.
 fn normalize_ty(cx: ctxt, t: t) -> t {
     alt cx.normalized_cache.find(t) {
       some(t) { ret t; }
diff --git a/src/rustc/middle/typeck/astconv.rs b/src/rustc/middle/typeck/astconv.rs
index a6f1501efe71b..ec963486dfec6 100644
--- a/src/rustc/middle/typeck/astconv.rs
+++ b/src/rustc/middle/typeck/astconv.rs
@@ -1,48 +1,46 @@
-#[doc = "
-
-Conversion from AST representation of types to the ty.rs
-representation.  The main routine here is `ast_ty_to_ty()`: each use
-is parameterized by an instance of `ast_conv` and a `region_scope`.
-
-The parameterization of `ast_ty_to_ty()` is because it behaves
-somewhat differently during the collect and check phases, particularly
-with respect to looking up the types of top-level items.  In the
-collect phase, the crate context is used as the `ast_conv` instance;
-in this phase, the `get_item_ty()` function triggers a recursive call
-to `ty_of_item()` (note that `ast_ty_to_ty()` will detect recursive
-types and report an error).  In the check phase, when the @fn_ctxt is
-used as the `ast_conv`, `get_item_ty()` just looks up the item type in
-`tcx.tcache`.
-
-The `region_scope` interface controls how region references are
-handled.  It has two methods which are used to resolve anonymous
-region references (e.g., `&T`) and named region references (e.g.,
-`&a.T`).  There are numerous region scopes that can be used, but most
-commonly you want either `empty_rscope`, which permits only the static
-region, or `type_rscope`, which permits the self region if the type in
-question is parameterized by a region.
-
-Unlike the `ast_conv` iface, the region scope can change as we descend
-the type.  This is to accommodate the fact that (a) fn types are binding
-scopes and (b) the default region may change.  To understand case (a),
-consider something like:
-
-  type foo = { x: &a.int, y: fn(&a.int) }
-
-The type of `x` is an error because there is no region `a` in scope.
-In the type of `y`, however, region `a` is considered a bound region
-as it does not already appear in scope.
-
-Case (b) says that if you have a type:
-  type foo/& = ...;
-  type bar = fn(&foo, &a.foo)
-The fully expanded version of type bar is:
-  type bar = fn(&foo/&, &a.foo/&a)
-Note that the self region for the `foo` defaulted to `&` in the first
-case but `&a` in the second.  Basically, defaults that appear inside
-an rptr (`&r.T`) use the region `r` that appears in the rptr.
-
-"];
+/*!
+ * Conversion from AST representation of types to the ty.rs
+ * representation.  The main routine here is `ast_ty_to_ty()`: each use
+ * is parameterized by an instance of `ast_conv` and a `region_scope`.
+ *
+ * The parameterization of `ast_ty_to_ty()` is because it behaves
+ * somewhat differently during the collect and check phases, particularly
+ * with respect to looking up the types of top-level items.  In the
+ * collect phase, the crate context is used as the `ast_conv` instance;
+ * in this phase, the `get_item_ty()` function triggers a recursive call
+ * to `ty_of_item()` (note that `ast_ty_to_ty()` will detect recursive
+ * types and report an error).  In the check phase, when the @fn_ctxt is
+ * used as the `ast_conv`, `get_item_ty()` just looks up the item type in
+ * `tcx.tcache`.
+ *
+ * The `region_scope` interface controls how region references are
+ * handled.  It has two methods which are used to resolve anonymous
+ * region references (e.g., `&T`) and named region references (e.g.,
+ * `&a.T`).  There are numerous region scopes that can be used, but most
+ * commonly you want either `empty_rscope`, which permits only the static
+ * region, or `type_rscope`, which permits the self region if the type in
+ * question is parameterized by a region.
+ *
+ * Unlike the `ast_conv` iface, the region scope can change as we descend
+ * the type.  This is to accommodate the fact that (a) fn types are binding
+ * scopes and (b) the default region may change.  To understand case (a),
+ * consider something like:
+ *
+ *   type foo = { x: &a.int, y: fn(&a.int) }
+ *
+ * The type of `x` is an error because there is no region `a` in scope.
+ * In the type of `y`, however, region `a` is considered a bound region
+ * as it does not already appear in scope.
+ *
+ * Case (b) says that if you have a type:
+ *   type foo/& = ...;
+ *   type bar = fn(&foo, &a.foo)
+ * The fully expanded version of type bar is:
+ *   type bar = fn(&foo/&, &a.foo/&a)
+ * Note that the self region for the `foo` defaulted to `&` in the first
+ * case but `&a` in the second.  Basically, defaults that appear inside
+ * an rptr (`&r.T`) use the region `r` that appears in the rptr.
+ */
 
 import check::fn_ctxt;
 import rscope::{anon_rscope, binding_rscope, empty_rscope, in_anon_rscope};
diff --git a/src/rustc/middle/typeck/collect.rs b/src/rustc/middle/typeck/collect.rs
index f64cfed7c81be..181c682fffaba 100644
--- a/src/rustc/middle/typeck/collect.rs
+++ b/src/rustc/middle/typeck/collect.rs
@@ -152,18 +152,18 @@ fn ensure_iface_methods(ccx: @crate_ctxt, id: ast::node_id) {
     }
 }
 
-#[doc = "
-Checks that a method from an impl/class conforms to the signature of
-the same method as declared in the iface.
-
-# Parameters
-
-- impl_m: the method in the impl
-- impl_tps: the type params declared on the impl itself (not the method!)
-- if_m: the method in the iface
-- if_substs: the substitutions used on the type of the iface
-- self_ty: the self type of the impl
-"]
+/**
+ * Checks that a method from an impl/class conforms to the signature of
+ * the same method as declared in the iface.
+ *
+ * # Parameters
+ *
+ * - impl_m: the method in the impl
+ * - impl_tps: the type params declared on the impl itself (not the method!)
+ * - if_m: the method in the iface
+ * - if_substs: the substitutions used on the type of the iface
+ * - self_ty: the self type of the impl
+ */
 fn compare_impl_method(tcx: ty::ctxt, sp: span,
                        impl_m: ty::method, impl_tps: uint,
                        if_m: ty::method, if_substs: ty::substs,
diff --git a/src/rustc/middle/typeck/infer.rs b/src/rustc/middle/typeck/infer.rs
index ba4d9152228ad..83c502d034c2f 100644
--- a/src/rustc/middle/typeck/infer.rs
+++ b/src/rustc/middle/typeck/infer.rs
@@ -546,7 +546,7 @@ fn rollback_to<V:copy vid, T:copy>(
 }
 
 impl transaction_methods for infer_ctxt {
-    #[doc = "Execute `f` and commit the bindings if successful"]
+    /// Execute `f` and commit the bindings if successful
     fn commit<T,E>(f: fn() -> result<T,E>) -> result<T,E> {
 
         assert self.tvb.bindings.len() == 0u;
@@ -562,7 +562,7 @@ impl transaction_methods for infer_ctxt {
         ret r;
     }
 
-    #[doc = "Execute `f`, unroll bindings on failure"]
+    /// Execute `f`, unroll bindings on failure
     fn try<T,E>(f: fn() -> result<T,E>) -> result<T,E> {
 
         let tvbl = self.tvb.bindings.len();
@@ -580,7 +580,7 @@ impl transaction_methods for infer_ctxt {
         ret r;
     }
 
-    #[doc = "Execute `f` then unroll any bindings it creates"]
+    /// Execute `f` then unroll any bindings it creates
     fn probe<T,E>(f: fn() -> result<T,E>) -> result<T,E> {
         assert self.tvb.bindings.len() == 0u;
         assert self.rb.bindings.len() == 0u;
diff --git a/src/rustdoc/attr_parser.rs b/src/rustdoc/attr_parser.rs
index 56c42902ac2e4..32c5f7ccf539a 100644
--- a/src/rustdoc/attr_parser.rs
+++ b/src/rustdoc/attr_parser.rs
@@ -39,9 +39,10 @@ fn doc_meta(
     attrs: ~[ast::attribute]
 ) -> option<@ast::meta_item> {
 
-    #[doc =
-      "Given a vec of attributes, extract the meta_items contained in the \
-       doc attribute"];
+    /*!
+     * Given a vec of attributes, extract the meta_items contained in the \
+     * doc attribute
+     */
 
     let doc_attrs = attr::find_attrs_by_name(attrs, "doc");
     let doc_metas = do doc_attrs.map |attr| {
diff --git a/src/rustdoc/config.rs b/src/rustdoc/config.rs
index c316b175e6618..94d232778679b 100644
--- a/src/rustdoc/config.rs
+++ b/src/rustdoc/config.rs
@@ -8,23 +8,23 @@ export default_config;
 export parse_config;
 export usage;
 
-#[doc = "The type of document to output"]
+/// The type of document to output
 enum output_format {
-    #[doc = "Markdown"]
+    /// Markdown
     markdown,
-    #[doc = "HTML, via markdown and pandoc"]
+    /// HTML, via markdown and pandoc
     pandoc_html
 }
 
-#[doc = "How to organize the output"]
+/// How to organize the output
 enum output_style {
-    #[doc = "All in a single document"]
+    /// All in a single document
     doc_per_crate,
-    #[doc = "Each module in its own document"]
+    /// Each module in its own document
     doc_per_mod
 }
 
-#[doc = "The configuration for a rustdoc session"]
+/// The configuration for a rustdoc session
 type config = {
     input_crate: str,
     output_dir: str,
diff --git a/src/rustdoc/demo.rs b/src/rustdoc/demo.rs
index e05f7080f0865..e84551b6a5390 100644
--- a/src/rustdoc/demo.rs
+++ b/src/rustdoc/demo.rs
@@ -1,30 +1,28 @@
 // no-reformat
 
-#[doc = "
-
-    A demonstration module
-
-    Contains documentation in various forms that rustdoc understands,
-    for testing purposes. It doesn't surve any functional
-    purpose. This here, for instance, is just some filler text.
-
-    FIXME (#1654): It would be nice if we could run some automated
-    tests on this file
-
-"];
-
-#[doc = "The base price of a muffin on a non-holiday"]
+/*!
+ * A demonstration module
+ *
+ * Contains documentation in various forms that rustdoc understands,
+ * for testing purposes. It doesn't surve any functional
+ * purpose. This here, for instance, is just some filler text.
+ *
+ * FIXME (#1654): It would be nice if we could run some automated
+ * tests on this file
+ */
+
+/// The base price of a muffin on a non-holiday
 const price_of_a_muffin: float = 70f;
 
 type waitress = {
     hair_color: str
 };
 
-#[doc = "The type of things that produce omnomnom"]
+/// The type of things that produce omnomnom
 enum omnomnomy {
-    #[doc = "Delicious sugar cookies"]
+    /// Delicious sugar cookies
     cookie,
-    #[doc = "It's pizza"]
+    /// It's pizza
     pizza_pie(~[uint])
 }
 
@@ -33,154 +31,151 @@ fn take_my_order_please(
     _order: ~[omnomnomy]
 ) -> uint {
 
-    #[doc = "
-    OMG would you take my order already?
-
-    # Arguments
-
-    * _waitress - The waitress that you want to bother
-    * _order - The order vector. It should be filled with food
-
-    # Return
-
-    The price of the order, including tax
-
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec
-    molestie nisl. Duis massa risus, pharetra a scelerisque a,
-    molestie eu velit. Donec mattis ligula at ante imperdiet ut
-    dapibus mauris malesuada.
-
-    Sed gravida nisi a metus elementum sit amet hendrerit dolor
-    bibendum. Aenean sit amet neque massa, sed tempus tortor. Sed ut
-    lobortis enim. Proin a mauris quis nunc fermentum ultrices eget a
-    erat. Mauris in lectus vitae metus sodales auctor. Morbi nunc
-    quam, ultricies at venenatis non, pellentesque ac dui.
-
-    # Failure
-
-    This function is full of fail
-    "];
+    /*!
+     * OMG would you take my order already?
+     *
+     * # Arguments
+     *
+     * * _waitress - The waitress that you want to bother
+     * * _order - The order vector. It should be filled with food
+     *
+     * # Return
+     *
+     * The price of the order, including tax
+     *
+     * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec
+     * molestie nisl. Duis massa risus, pharetra a scelerisque a,
+     * molestie eu velit. Donec mattis ligula at ante imperdiet ut
+     * dapibus mauris malesuada.
+     *
+     * Sed gravida nisi a metus elementum sit amet hendrerit dolor
+     * bibendum. Aenean sit amet neque massa, sed tempus tortor. Sed ut
+     * lobortis enim. Proin a mauris quis nunc fermentum ultrices eget a
+     * erat. Mauris in lectus vitae metus sodales auctor. Morbi nunc
+     * quam, ultricies at venenatis non, pellentesque ac dui.
+     *
+     * # Failure
+     *
+     * This function is full of fail
+     */
 
     fail;
 }
 
 mod fortress_of_solitude {
-    #[doc = "
-    Superman's vacation home
-
-    The fortress of solitude is located in the Arctic and it is
-    cold. What you may not know about the fortress of solitude
-    though is that it contains two separate bowling alleys. One of
-    them features bumper-bowling and is kind of lame.
-
-    Really, it's pretty cool.
-
-    "];
+    /*!
+     * Superman's vacation home
+     *
+     * The fortress of solitude is located in the Arctic and it is
+     * cold. What you may not know about the fortress of solitude
+     * though is that it contains two separate bowling alleys. One of
+     * them features bumper-bowling and is kind of lame.
+     *
+     * Really, it's pretty cool.
+     */
 
 }
 
 mod blade_runner {
-    #[doc = "
-    Blade Runner is probably the best movie ever
-
-    I like that in the world of Blade Runner it is always
-    raining, and that it's always night time. And Aliens
-    was also a really good movie.
-
-    Alien 3 was crap though.
-    "];
+    /*!
+     * Blade Runner is probably the best movie ever
+     *
+     * I like that in the world of Blade Runner it is always
+     * raining, and that it's always night time. And Aliens
+     * was also a really good movie.
+     *
+     * Alien 3 was crap though.
+     */
 }
 
-#[doc = "
-Bored
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec
-molestie nisl. Duis massa risus, pharetra a scelerisque a,
-molestie eu velit. Donec mattis ligula at ante imperdiet ut
-dapibus mauris malesuada. Sed gravida nisi a metus elementum sit
-amet hendrerit dolor bibendum. Aenean sit amet neque massa, sed
-tempus tortor. Sed ut lobortis enim. Proin a mauris quis nunc
-fermentum ultrices eget a erat. Mauris in lectus vitae metus
-sodales auctor. Morbi nunc quam, ultricies at venenatis non,
-pellentesque ac dui.
-
-Quisque vitae est id eros placerat laoreet sit amet eu
-nisi. Curabitur suscipit neque porttitor est euismod
-lacinia. Curabitur non quam vitae ipsum adipiscing
-condimentum. Mauris ut ante eget metus sollicitudin
-blandit. Aliquam erat volutpat. Morbi sed nisl mauris. Nulla
-facilisi. Phasellus at mollis ipsum. Maecenas sed convallis
-sapien. Nullam in ligula turpis. Pellentesque a neque augue. Sed
-eget ante feugiat tortor congue auctor ac quis ante. Proin
-condimentum lacinia tincidunt.
-
-"]
+/**
+ * Bored
+ *
+ * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed nec
+ * molestie nisl. Duis massa risus, pharetra a scelerisque a,
+ * molestie eu velit. Donec mattis ligula at ante imperdiet ut
+ * dapibus mauris malesuada. Sed gravida nisi a metus elementum sit
+ * amet hendrerit dolor bibendum. Aenean sit amet neque massa, sed
+ * tempus tortor. Sed ut lobortis enim. Proin a mauris quis nunc
+ * fermentum ultrices eget a erat. Mauris in lectus vitae metus
+ * sodales auctor. Morbi nunc quam, ultricies at venenatis non,
+ * pellentesque ac dui.
+ *
+ * Quisque vitae est id eros placerat laoreet sit amet eu
+ * nisi. Curabitur suscipit neque porttitor est euismod
+ * lacinia. Curabitur non quam vitae ipsum adipiscing
+ * condimentum. Mauris ut ante eget metus sollicitudin
+ * blandit. Aliquam erat volutpat. Morbi sed nisl mauris. Nulla
+ * facilisi. Phasellus at mollis ipsum. Maecenas sed convallis
+ * sapien. Nullam in ligula turpis. Pellentesque a neque augue. Sed
+ * eget ante feugiat tortor congue auctor ac quis ante. Proin
+ * condimentum lacinia tincidunt.
+ */
 class bored {
   let bored: bool;
   new(bored: bool) { self.bored = bored; }
   drop { log(error, self.bored); }
 }
 
-#[doc = "
-The Shunned House
-
-From even the greatest of horrors irony is seldom absent. Sometimes it
-enters directly into the composition of the events, while sometimes it
-relates only to their fortuitous position among persons and
-places. The latter sort is splendidly exemplified by a case in the
-ancient city of Providence, where in the late forties Edgar Allan Poe
-used to sojourn often during his unsuccessful wooing of the gifted
-poetess, Mrs.  Whitman. Poe generally stopped at the Mansion House in
-Benefit Street--the renamed Golden Ball Inn whose roof has sheltered
-Washington, Jefferson, and Lafayette--and his favorite walk led
-northward along the same street to Mrs. Whitman's home and the
-neighboring hillside churchyard of St. John's, whose hidden expanse of
-Eighteenth Century gravestones had for him a peculiar fascination.
-
-"]
+/**
+ * The Shunned House
+ *
+ * From even the greatest of horrors irony is seldom absent. Sometimes it
+ * enters directly into the composition of the events, while sometimes it
+ * relates only to their fortuitous position among persons and
+ * places. The latter sort is splendidly exemplified by a case in the
+ * ancient city of Providence, where in the late forties Edgar Allan Poe
+ * used to sojourn often during his unsuccessful wooing of the gifted
+ * poetess, Mrs.  Whitman. Poe generally stopped at the Mansion House in
+ * Benefit Street--the renamed Golden Ball Inn whose roof has sheltered
+ * Washington, Jefferson, and Lafayette--and his favorite walk led
+ * northward along the same street to Mrs. Whitman's home and the
+ * neighboring hillside churchyard of St. John's, whose hidden expanse of
+ * Eighteenth Century gravestones had for him a peculiar fascination.
+ */
 iface the_shunned_house {
-    #[doc = "
-    Now the irony is this. In this walk, so many times repeated, the
-    world's greatest master of the terrible and the bizarre was
-    obliged to pass a particular house on the eastern side of the
-    street; a dingy, antiquated structure perched on the abruptly
-    rising side hill, with a great unkempt yard dating from a time
-    when the region was partly open country. It does not appear that
-    he ever wrote or spoke of it, nor is there any evidence that he
-    even noticed it. And yet that house, to the two persons in
-    possession of certain information, equals or outranks in horror
-    the wildest fantasy of the genius who so often passed it
-    unknowingly, and stands starkly leering as a symbol of all that is
-    unutterably hideous.
-
-    # Arguments
-
-    * unkempt_yard - A yard dating from a time when the region was partly
-                     open country
-    "]
+    /**
+     * Now the irony is this. In this walk, so many times repeated, the
+     * world's greatest master of the terrible and the bizarre was
+     * obliged to pass a particular house on the eastern side of the
+     * street; a dingy, antiquated structure perched on the abruptly
+     * rising side hill, with a great unkempt yard dating from a time
+     * when the region was partly open country. It does not appear that
+     * he ever wrote or spoke of it, nor is there any evidence that he
+     * even noticed it. And yet that house, to the two persons in
+     * possession of certain information, equals or outranks in horror
+     * the wildest fantasy of the genius who so often passed it
+     * unknowingly, and stands starkly leering as a symbol of all that is
+     * unutterably hideous.
+     *
+     * # Arguments
+     *
+     * * unkempt_yard - A yard dating from a time when the region was partly
+     *                  open country
+     */
     fn dingy_house(unkempt_yard: int);
 
-    #[doc = "
-    The house was--and for that matter still is--of a kind to attract
-    the attention of the curious. Originally a farm or semi-farm
-    building, it followed the average New England colonial lines of
-    the middle Eighteenth Century--the prosperous peaked-roof sort,
-    with two stories and dormerless attic, and with the Georgian
-    doorway and interior panelling dictated by the progress of taste
-    at that time. It faced south, with one gable end buried to the
-    lower windows in the eastward rising hill, and the other exposed
-    to the foundations toward the street. Its construction, over a
-    century and a half ago, had followed the grading and straightening
-    of the road in that especial vicinity; for Benefit Street--at
-    first called Back Street--was laid out as a lane winding amongst
-    the graveyards of the first settlers, and straightened only when
-    the removal of the bodies to the North Burial Ground made it
-    decently possible to cut through the old family plots.
-    "]
+    /**
+     * The house was--and for that matter still is--of a kind to attract
+     * the attention of the curious. Originally a farm or semi-farm
+     * building, it followed the average New England colonial lines of
+     * the middle Eighteenth Century--the prosperous peaked-roof sort,
+     * with two stories and dormerless attic, and with the Georgian
+     * doorway and interior panelling dictated by the progress of taste
+     * at that time. It faced south, with one gable end buried to the
+     * lower windows in the eastward rising hill, and the other exposed
+     * to the foundations toward the street. Its construction, over a
+     * century and a half ago, had followed the grading and straightening
+     * of the road in that especial vicinity; for Benefit Street--at
+     * first called Back Street--was laid out as a lane winding amongst
+     * the graveyards of the first settlers, and straightened only when
+     * the removal of the bodies to the North Burial Ground made it
+     * decently possible to cut through the old family plots.
+     */
     fn construct() -> bool;
 }
 
-#[doc = "Whatever"]
+/// Whatever
 impl of the_shunned_house for omnomnomy {
     fn dingy_house(_unkempt_yard: int) {
     }
diff --git a/src/rustdoc/desc_to_brief_pass.rs b/src/rustdoc/desc_to_brief_pass.rs
index f4b0a52a268e0..15ed16945201e 100644
--- a/src/rustdoc/desc_to_brief_pass.rs
+++ b/src/rustdoc/desc_to_brief_pass.rs
@@ -1,11 +1,9 @@
-#[doc = "
-
-Pulls a brief description out of a long description.
-
-If the first paragraph of a long description is short enough then it
-is interpreted as the brief description.
-
-"];
+/*!
+ * Pulls a brief description out of a long description.
+ *
+ * If the first paragraph of a long description is short enough then it
+ * is interpreted as the brief description.
+ */
 
 export mk_pass;
 
diff --git a/src/rustdoc/doc.rs b/src/rustdoc/doc.rs
index cd83b70bbeaa2..744f62d0eb3d0 100644
--- a/src/rustdoc/doc.rs
+++ b/src/rustdoc/doc.rs
@@ -1,4 +1,4 @@
-#[doc = "The document model"];
+//! The document model
 
 type ast_id = int;
 
@@ -11,10 +11,10 @@ enum page {
     itempage(itemtag)
 }
 
-#[doc = "
-Most rustdocs can be parsed into 'sections' according to their markdown
-headers
-"]
+/**
+ * Most rustdocs can be parsed into 'sections' according to their markdown
+ * headers
+ */
 type section = {
     header: str,
     body: str
@@ -107,18 +107,16 @@ type index = {
     entries: ~[index_entry]
 };
 
-#[doc = "
-
-A single entry in an index
-
-Fields:
-
-* kind - The type of thing being indexed, e.g. 'Module'
-* name - The name of the thing
-* brief - The brief description
-* link - A format-specific string representing the link target
-
-"]
+/**
+ * A single entry in an index
+ *
+ * Fields:
+ *
+ * * kind - The type of thing being indexed, e.g. 'Module'
+ * * name - The name of the thing
+ * * brief - The brief description
+ * * link - A format-specific string representing the link target
+ */
 type index_entry = {
     kind: str,
     name: str,
@@ -141,7 +139,7 @@ impl util for doc {
     }
 }
 
-#[doc = "Some helper methods on moddoc, mostly for testing"]
+/// Some helper methods on moddoc, mostly for testing
 impl util for moddoc {
 
     fn mods() -> ~[moddoc] {
diff --git a/src/rustdoc/escape_pass.rs b/src/rustdoc/escape_pass.rs
index c9dada9026f91..1cefe410e8ec7 100644
--- a/src/rustdoc/escape_pass.rs
+++ b/src/rustdoc/escape_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Escapes text sequences"];
+//! Escapes text sequences
 
 export mk_pass;
 
diff --git a/src/rustdoc/extract.rs b/src/rustdoc/extract.rs
index 0d4182a6ee802..affca61cb961b 100644
--- a/src/rustdoc/extract.rs
+++ b/src/rustdoc/extract.rs
@@ -1,4 +1,4 @@
-#[doc = "Converts the Rust AST to the rustdoc document model"];
+//! Converts the Rust AST to the rustdoc document model
 
 import syntax::ast;
 
@@ -9,7 +9,7 @@ fn from_srv(
     default_name: str
 ) -> doc::doc {
 
-    #[doc = "Use the AST service to create a document tree"];
+    //! Use the AST service to create a document tree
 
     do astsrv::exec(srv) |ctxt| {
         extract(ctxt.ast, default_name)
diff --git a/src/rustdoc/markdown_index_pass.rs b/src/rustdoc/markdown_index_pass.rs
index 83098ecd04527..8a68ff8cadb4d 100644
--- a/src/rustdoc/markdown_index_pass.rs
+++ b/src/rustdoc/markdown_index_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Build indexes as appropriate for the markdown pass"];
+//! Build indexes as appropriate for the markdown pass
 
 export mk_pass;
 
diff --git a/src/rustdoc/markdown_pass.rs b/src/rustdoc/markdown_pass.rs
index 7402bfa0dbbd9..d2ed82b44a560 100644
--- a/src/rustdoc/markdown_pass.rs
+++ b/src/rustdoc/markdown_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Generate markdown from a document tree"];
+//! Generate markdown from a document tree
 
 import markdown_writer::writer;
 import markdown_writer::writer_util;
diff --git a/src/rustdoc/page_pass.rs b/src/rustdoc/page_pass.rs
index a360686e35862..255854df8f03a 100644
--- a/src/rustdoc/page_pass.rs
+++ b/src/rustdoc/page_pass.rs
@@ -1,11 +1,9 @@
-#[doc = "
-
-Divides the document tree into pages.
-
-Each page corresponds is a logical section. There may be pages for individual
-modules, pages for the crate, indexes, etc.
-
-"];
+/*!
+ * Divides the document tree into pages.
+ *
+ * Each page corresponds is a logical section. There may be pages for
+ * individual modules, pages for the crate, indexes, etc.
+ */
 
 import syntax::ast;
 
diff --git a/src/rustdoc/parse.rs b/src/rustdoc/parse.rs
index eca2273c5b241..c327830f517fb 100644
--- a/src/rustdoc/parse.rs
+++ b/src/rustdoc/parse.rs
@@ -1,4 +1,4 @@
-#[doc = "AST-parsing helpers"];
+//! AST-parsing helpers
 
 import rustc::driver::driver;
 import driver::{file_input, str_input};
diff --git a/src/rustdoc/path_pass.rs b/src/rustdoc/path_pass.rs
index 07029029c6ed1..91330cb119289 100644
--- a/src/rustdoc/path_pass.rs
+++ b/src/rustdoc/path_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Records the full path to items"];
+//! Records the full path to items
 
 import syntax::ast;
 
diff --git a/src/rustdoc/prune_hidden_pass.rs b/src/rustdoc/prune_hidden_pass.rs
index 783ca6d3f1465..e121cc88dd7f0 100644
--- a/src/rustdoc/prune_hidden_pass.rs
+++ b/src/rustdoc/prune_hidden_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Prunes things with the #[doc(hidden)] attribute"];
+//! Prunes things with the #[doc(hidden)] attribute
 
 import std::map::hashmap;
 export mk_pass;
diff --git a/src/rustdoc/prune_unexported_pass.rs b/src/rustdoc/prune_unexported_pass.rs
index 753100c1f09f0..4622aeefba864 100644
--- a/src/rustdoc/prune_unexported_pass.rs
+++ b/src/rustdoc/prune_unexported_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Prunes branches of the tree that are not exported"];
+//! Prunes branches of the tree that are not exported
 
 import syntax::ast;
 import syntax::ast_util;
diff --git a/src/rustdoc/reexport_pass.rs b/src/rustdoc/reexport_pass.rs
index 3c28501aa9844..fcebe51dde807 100644
--- a/src/rustdoc/reexport_pass.rs
+++ b/src/rustdoc/reexport_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Finds docs for reexported items and duplicates them"];
+//! Finds docs for reexported items and duplicates them
 
 import std::map;
 import std::map::hashmap;
diff --git a/src/rustdoc/rustdoc.rc b/src/rustdoc/rustdoc.rc
index 8e6dc2e6ccf8a..ab8f770e87f69 100644
--- a/src/rustdoc/rustdoc.rc
+++ b/src/rustdoc/rustdoc.rc
@@ -1,4 +1,4 @@
-#[doc = "Rustdoc - The Rust documentation generator"];
+//! Rustdoc - The Rust documentation generator
 
 #[link(name = "rustdoc",
        vers = "0.2",
diff --git a/src/rustdoc/rustdoc.rs b/src/rustdoc/rustdoc.rs
index 0d7f59e6b6dd9..0f481f7582211 100755
--- a/src/rustdoc/rustdoc.rs
+++ b/src/rustdoc/rustdoc.rs
@@ -2,7 +2,7 @@
 import doc::item;
 import doc::util;
 
-#[doc = "A single operation on the document model"]
+/// A single operation on the document model
 type pass = {
     name: str,
     f: fn~(srv: astsrv::srv, doc: doc::doc) -> doc::doc
@@ -125,7 +125,7 @@ fn time<T>(what: str, f: fn() -> T) -> T {
     ret rv;
 }
 
-#[doc = "Runs rustdoc over the given file"]
+/// Runs rustdoc over the given file
 fn run(config: config::config) {
 
     let source_file = config.input_crate;
diff --git a/src/rustdoc/sectionalize_pass.rs b/src/rustdoc/sectionalize_pass.rs
index 85879c94ba9ab..ced74a9bfd38b 100644
--- a/src/rustdoc/sectionalize_pass.rs
+++ b/src/rustdoc/sectionalize_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Breaks rustdocs into sections according to their headers"];
+//! Breaks rustdocs into sections according to their headers
 
 export mk_pass;
 
@@ -66,23 +66,21 @@ fn fold_impl(fold: fold::fold<()>, doc: doc::impldoc) -> doc::impldoc {
 
 fn sectionalize(desc: option<str>) -> (option<str>, ~[doc::section]) {
 
-    #[doc = "
-
-    Take a description of the form
-
-        General text
-
-        # Section header
-
-        Section text
-
-        # Section header
-
-        Section text
-
-    and remove each header and accompanying text into section records.
-
-    "];
+    /*!
+     * Take a description of the form
+     *
+     *     General text
+     *
+     *     # Section header
+     *
+     *     Section text
+     *
+     *     # Section header
+     *
+     *     Section text
+     *
+     * and remove each header and accompanying text into section records.
+     */
 
     if option::is_none(desc) {
         ret (none, ~[]);
diff --git a/src/rustdoc/sort_item_name_pass.rs b/src/rustdoc/sort_item_name_pass.rs
index c791c099b43b1..47a69fed953b1 100644
--- a/src/rustdoc/sort_item_name_pass.rs
+++ b/src/rustdoc/sort_item_name_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Sorts items by name"];
+//! Sorts items by name
 
 export mk_pass;
 
diff --git a/src/rustdoc/sort_item_type_pass.rs b/src/rustdoc/sort_item_type_pass.rs
index de74f2f535ed2..92a2b381fdb13 100644
--- a/src/rustdoc/sort_item_type_pass.rs
+++ b/src/rustdoc/sort_item_type_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Sorts items by type"];
+//! Sorts items by type
 
 export mk_pass;
 
diff --git a/src/rustdoc/sort_pass.rs b/src/rustdoc/sort_pass.rs
index 7cc537851dcb4..86dc2260e7d70 100644
--- a/src/rustdoc/sort_pass.rs
+++ b/src/rustdoc/sort_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "A general sorting pass"];
+//! A general sorting pass
 
 import std::sort;
 
diff --git a/src/rustdoc/text_pass.rs b/src/rustdoc/text_pass.rs
index 6d3ef691f64f0..126cdc0d9e0dd 100644
--- a/src/rustdoc/text_pass.rs
+++ b/src/rustdoc/text_pass.rs
@@ -1,4 +1,4 @@
-#[doc = "Generic pass for performing an operation on all descriptions"];
+//! Generic pass for performing an operation on all descriptions
 
 export mk_pass;
 
diff --git a/src/rustdoc/trim_pass.rs b/src/rustdoc/trim_pass.rs
index 4f7a90743ac8e..3d135d8073c02 100644
--- a/src/rustdoc/trim_pass.rs
+++ b/src/rustdoc/trim_pass.rs
@@ -1,11 +1,9 @@
-#[doc = "
-
-Pulls a brief description out of a long description.
-
-If the first paragraph of a long description is short enough then it
-is interpreted as the brief description.
-
-"];
+/*!
+ * Pulls a brief description out of a long description.
+ *
+ * If the first paragraph of a long description is short enough then it
+ * is interpreted as the brief description.
+ */
 
 export mk_pass;
 
diff --git a/src/rustdoc/tystr_pass.rs b/src/rustdoc/tystr_pass.rs
index 7de5f48db32b4..a09c3a3b2fa84 100644
--- a/src/rustdoc/tystr_pass.rs
+++ b/src/rustdoc/tystr_pass.rs
@@ -1,5 +1,4 @@
-#[doc =
-  "Pulls type information out of the AST and attaches it to the document"];
+//! Pulls type information out of the AST and attaches it to the document
 
 import syntax::ast;
 import syntax::print::pprust;
diff --git a/src/rustdoc/unindent_pass.rs b/src/rustdoc/unindent_pass.rs
index b5e11b0dfd9b7..1df8d5b8f5029 100644
--- a/src/rustdoc/unindent_pass.rs
+++ b/src/rustdoc/unindent_pass.rs
@@ -1,15 +1,13 @@
-#[doc = "
-
-Removes the common level of indention from description strings. For
-instance, if an entire doc comment is indented 8 spaces we want to
-remove those 8 spaces from every line.
-
-The first line of a string is allowed to be intend less than
-subsequent lines in the same paragraph in order to account for
-instances where the string containing the doc comment is opened in the
-middle of a line, and each of the following lines is indented.
-
-"];
+/*!
+ * Removes the common level of indention from description strings. For
+ * instance, if an entire doc comment is indented 8 spaces we want to
+ * remove those 8 spaces from every line.
+ *
+ * The first line of a string is allowed to be intend less than
+ * subsequent lines in the same paragraph in order to account for
+ * instances where the string containing the doc comment is opened in the
+ * middle of a line, and each of the following lines is indented.
+ */
 
 export mk_pass;
 
diff --git a/src/test/auxiliary/test_comm.rs b/src/test/auxiliary/test_comm.rs
index 62389aece6adc..ea2f71306872c 100644
--- a/src/test/auxiliary/test_comm.rs
+++ b/src/test/auxiliary/test_comm.rs
@@ -11,18 +11,18 @@ export port;
 export recv;
 
 
-#[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>)
 }
 
-#[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)))
 }
@@ -52,14 +52,14 @@ class port_ptr<T:send> {
 }
 
 
-#[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 = "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);
diff --git a/src/test/bench/graph500-bfs.rs b/src/test/bench/graph500-bfs.rs
index 9e24e9defcc49..4a3b41b5ca242 100644
--- a/src/test/bench/graph500-bfs.rs
+++ b/src/test/bench/graph500-bfs.rs
@@ -98,9 +98,11 @@ fn gen_search_keys(graph: graph, n: uint) -> ~[node_id] {
     map::vec_from_set(keys)
 }
 
-#[doc="Returns a vector of all the parents in the BFS tree rooted at key.
-
-Nodes that are unreachable have a parent of -1."]
+/**
+ * Returns a vector of all the parents in the BFS tree rooted at key.
+ *
+ * Nodes that are unreachable have a parent of -1.
+ */
 fn bfs(graph: graph, key: node_id) -> bfs_result {
     let marks : ~[mut node_id] 
         = vec::to_mut(vec::from_elem(vec::len(graph), -1i64));
@@ -125,10 +127,12 @@ fn bfs(graph: graph, key: node_id) -> bfs_result {
     vec::from_mut(marks)
 }
 
-#[doc="Another version of the bfs function.
-
-This one uses the same algorithm as the parallel one, just without
-using the parallel vector operators."]
+/**
+ * Another version of the bfs function.
+ *
+ * This one uses the same algorithm as the parallel one, just without
+ * using the parallel vector operators.
+ */
 fn bfs2(graph: graph, key: node_id) -> bfs_result {
     // This works by doing functional updates of a color vector.
 
@@ -197,7 +201,7 @@ fn bfs2(graph: graph, key: node_id) -> bfs_result {
     }
 }
 
-#[doc="A parallel version of the bfs function."]
+/// A parallel version of the bfs function.
 fn pbfs(&&graph: arc::arc<graph>, key: node_id) -> bfs_result {
     // This works by doing functional updates of a color vector.
 
@@ -277,7 +281,7 @@ fn pbfs(&&graph: arc::arc<graph>, key: node_id) -> bfs_result {
     }
 }
 
-#[doc="Performs at least some of the validation in the Graph500 spec."]
+/// Performs at least some of the validation in the Graph500 spec.
 fn validate(edges: ~[(node_id, node_id)], 
             root: node_id, tree: bfs_result) -> bool {
     // There are 5 things to test. Below is code for each of them.
diff --git a/src/test/pretty/doc-comments.rs b/src/test/pretty/doc-comments.rs
index 175940f008ad9..835c1d9640a0f 100644
--- a/src/test/pretty/doc-comments.rs
+++ b/src/test/pretty/doc-comments.rs
@@ -6,7 +6,7 @@
 fn a() { }
 
 fn b() {
-    //~ some single line inner-docs
+    //! some single line inner-docs
 }
 
 /*
diff --git a/src/test/run-pass/reflect-visit-data.rs b/src/test/run-pass/reflect-visit-data.rs
index 12cda37a1f28c..47a7d00908c12 100644
--- a/src/test/run-pass/reflect-visit-data.rs
+++ b/src/test/run-pass/reflect-visit-data.rs
@@ -4,14 +4,14 @@
 import intrinsic::ty_visitor;
 import libc::c_void;
 
-#[doc = "High-level interfaces to `intrinsic::visit_ty` reflection system."]
+/// High-level interfaces to `intrinsic::visit_ty` reflection system.
 
-#[doc = "Iface for visitor that wishes to reflect on data."]
+/// Iface for visitor that wishes to reflect on data.
 iface movable_ptr {
     fn move_ptr(adjustment: fn(*c_void) -> *c_void);
 }
 
-#[doc = "Helper function for alignment calculation."]
+/// Helper function for alignment calculation.
 #[inline(always)]
 fn align(size: uint, align: uint) -> uint {
     ((size + align) - 1u) & !(align - 1u)