doc: Cleanup.

Remove ~~~ for code block specification. Use /// Over /** */ for doc
blocks.

9 files changed, 186 insertions, 213 deletions

diff --git a/src/libcore/fmt/num.rs b/src/libcore/fmt/num.rs
index 568745d70b3..eb8d684fe50 100644
--- a/src/libcore/fmt/num.rs
+++ b/src/libcore/fmt/num.rs
@@ -138,10 +138,10 @@ pub struct RadixFmt<T, R>(T, R);
 ///
 /// # Example
 ///
-/// ~~~
+/// ```
 /// use std::fmt::radix;
 /// assert_eq!(format!("{}", radix(55i, 36)), "1j".to_string());
-/// ~~~
+/// ```
 pub fn radix<T>(x: T, base: u8) -> RadixFmt<T, Radix> {
     RadixFmt(x, Radix::new(base))
 }
diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs
index f6c5ffd5402..99d9d1df522 100644
--- a/src/libcore/num/mod.rs
+++ b/src/libcore/num/mod.rs
@@ -61,10 +61,10 @@ pub trait Zero: Add<Self, Self> {
     ///
     /// # Laws
     ///
-    /// ~~~text
+    /// ```{.text}
     /// a + 0 = a       ∀ a ∈ Self
     /// 0 + a = a       ∀ a ∈ Self
-    /// ~~~
+    /// ```
     ///
     /// # Purity
     ///
@@ -114,10 +114,10 @@ pub trait One: Mul<Self, Self> {
     ///
     /// # Laws
     ///
-    /// ~~~text
+    /// ```{.text}
     /// a * 1 = a       ∀ a ∈ Self
     /// 1 * a = a       ∀ a ∈ Self
-    /// ~~~
+    /// ```
     ///
     /// # Purity
     ///
diff --git a/src/libcore/result.rs b/src/libcore/result.rs
index 426ae8f0929..9b533a72ad7 100644
--- a/src/libcore/result.rs
+++ b/src/libcore/result.rs
@@ -15,12 +15,12 @@
 //! success and containing a value, and `Err(E)`, representing error
 //! and containing an error value.
 //!
-//! ~~~
+//! ```
 //! enum Result<T, E> {
 //!    Ok(T),
 //!    Err(E)
 //! }
-//! ~~~
+//! ```
 //!
 //! Functions return `Result` whenever errors are expected and
 //! recoverable. In the `std` crate `Result` is most prominently used
@@ -29,7 +29,7 @@
 //! A simple function returning `Result` might be
 //! defined and used like so:
 //!
-//! ~~~
+//! ```
 //! #[deriving(Show)]
 //! enum Version { Version1, Version2 }
 //!
@@ -53,13 +53,13 @@
 //!         println!("error parsing header: {}", e);
 //!     }
 //! }
-//! ~~~
+//! ```
 //!
 //! Pattern matching on `Result`s is clear and straightforward for
 //! simple cases, but `Result` comes with some convenience methods
 //! that make working it more succinct.
 //!
-//! ~~~
+//! ```
 //! let good_result: Result<int, int> = Ok(10);
 //! let bad_result: Result<int, int> = Err(10);
 //!
@@ -79,7 +79,7 @@
 //!
 //! // Consume the result and return the contents with `unwrap`.
 //! let final_awesome_result = good_result.ok().unwrap();
-//! ~~~
+//! ```
 //!
 //! # Results must be used
 //!
@@ -94,13 +94,13 @@
 //! Consider the `write_line` method defined for I/O types
 //! by the [`Writer`](../io/trait.Writer.html) trait:
 //!
-//! ~~~
+//! ```
 //! use std::io::IoError;
 //!
 //! trait Writer {
 //!     fn write_line(&mut self, s: &str) -> Result<(), IoError>;
 //! }
-//! ~~~
+//! ```
 //!
 //! *Note: The actual definition of `Writer` uses `IoResult`, which
 //! is just a synonym for `Result<T, IoError>`.*
@@ -109,7 +109,7 @@
 //! fail. It's crucial to handle the error case, and *not* write
 //! something like this:
 //!
-//! ~~~ignore
+//! ```{.ignore}
 //! use std::io::{File, Open, Write};
 //!
 //! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
@@ -117,7 +117,7 @@
 //! // value is ignored.
 //! file.write_line("important message");
 //! drop(file);
-//! ~~~
+//! ```
 //!
 //! If you *do* write that in Rust, the compiler will by give you a
 //! warning (by default, controlled by the `unused_must_use` lint).
@@ -127,27 +127,27 @@
 //! success with `expect`. This will fail if the write fails, proving
 //! a marginally useful message indicating why:
 //!
-//! ~~~no_run
+//! ```{.no_run}
 //! use std::io::{File, Open, Write};
 //!
 //! let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
 //! file.write_line("important message").ok().expect("failed to write message");
 //! drop(file);
-//! ~~~
+//! ```
 //!
 //! You might also simply assert success:
 //!
-//! ~~~no_run
+//! ```{.no_run}
 //! # use std::io::{File, Open, Write};
 //!
 //! # let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
 //! assert!(file.write_line("important message").is_ok());
 //! # drop(file);
-//! ~~~
+//! ```
 //!
 //! Or propagate the error up the call stack with `try!`:
 //!
-//! ~~~
+//! ```
 //! # use std::io::{File, Open, Write, IoError};
 //! fn write_message() -> Result<(), IoError> {
 //!     let mut file = File::open_mode(&Path::new("valuable_data.txt"), Open, Write);
@@ -155,7 +155,7 @@
 //!     drop(file);
 //!     return Ok(());
 //! }
-//! ~~~
+//! ```
 //!
 //! # The `try!` macro
 //!
@@ -166,7 +166,7 @@
 //!
 //! It replaces this:
 //!
-//! ~~~
+//! ```
 //! use std::io::{File, Open, Write, IoError};
 //!
 //! struct Info {
@@ -188,11 +188,11 @@
 //!     }
 //!     return file.write_line(format!("rating: {}", info.rating).as_slice());
 //! }
-//! ~~~
+//! ```
 //!
 //! With this:
 //!
-//! ~~~
+//! ```
 //! use std::io::{File, Open, Write, IoError};
 //!
 //! struct Info {
@@ -209,7 +209,7 @@
 //!     try!(file.write_line(format!("rating: {}", info.rating).as_slice()));
 //!     return Ok(());
 //! }
-//! ~~~
+//! ```
 //!
 //! *It's much nicer!*
 //!
@@ -218,13 +218,13 @@
 //! `Err` is returned early from the enclosing function. Its simple definition
 //! makes it clear:
 //!
-//! ~~~
+//! ```
 //! # #![feature(macro_rules)]
 //! macro_rules! try(
 //!     ($e:expr) => (match $e { Ok(e) => e, Err(e) => return Err(e) })
 //! )
 //! # fn main() { }
-//! ~~~
+//! ```
 //!
 //! `try!` is imported by the prelude, and is available everywhere.
 //!
@@ -245,10 +245,10 @@
 //!
 //! Converting to an `Option` with `ok()` to handle an error:
 //!
-//! ~~~
+//! ```
 //! use std::io::Timer;
 //! let mut t = Timer::new().ok().expect("failed to create timer!");
-//! ~~~
+//! ```
 //!
 //! # `Result` vs. `fail!`
 //!
@@ -440,12 +440,12 @@ impl<T, E> Result<T, E> {
     ///
     /// This function can be used to compose the results of two functions.
     ///
-    /// # Examples
+    /// # Example
     ///
     /// Sum the lines of a buffer by mapping strings to numbers,
     /// ignoring I/O and parse errors:
     ///
-    /// ~~~
+    /// ```
     /// use std::io::{BufReader, IoResult};
     ///
     /// let buffer = "1\n2\n3\n4\n";
@@ -464,7 +464,7 @@ impl<T, E> Result<T, E> {
     /// }
     ///
     /// assert!(sum == 10);
-    /// ~~~
+    /// ```
     #[inline]
     #[unstable = "waiting for unboxed closures"]
     pub fn map<U>(self, op: |T| -> U) -> Result<U,E> {
diff --git a/src/libgetopts/lib.rs b/src/libgetopts/lib.rs
index 3ffd39a0065..f95ecb412d1 100644
--- a/src/libgetopts/lib.rs
+++ b/src/libgetopts/lib.rs
@@ -31,7 +31,7 @@
 //! 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.
 //!
-//! ~~~{.rust}
+//! ```{.rust}
 //! extern crate getopts;
 //! use getopts::{optopt,optflag,getopts,OptGroup};
 //! use std::os;
@@ -76,7 +76,7 @@
 //!     };
 //!     do_work(input.as_slice(), output);
 //! }
-//! ~~~
+//! ```
 
 #![crate_name = "getopts"]
 #![experimental]
diff --git a/src/libnum/integer.rs b/src/libnum/integer.rs
index b06e2b448d4..f5ac5831ea5 100644
--- a/src/libnum/integer.rs
+++ b/src/libnum/integer.rs
@@ -17,7 +17,7 @@ pub trait Integer: Num + PartialOrd
     ///
     /// # Examples
     ///
-    /// ~~~
+    /// ```
     /// # use num::Integer;
     /// assert!(( 8i).div_floor(& 3) ==  2);
     /// assert!(( 8i).div_floor(&-3) == -3);
@@ -28,20 +28,20 @@ pub trait Integer: Num + PartialOrd
     /// assert!(( 1i).div_floor(&-2) == -1);
     /// assert!((-1i).div_floor(& 2) == -1);
     /// assert!((-1i).div_floor(&-2) ==  0);
-    /// ~~~
+    /// ```
     fn div_floor(&self, other: &Self) -> Self;
 
     /// Floored integer modulo, satisfying:
     ///
-    /// ~~~
+    /// ```
     /// # use num::Integer;
     /// # let n = 1i; let d = 1i;
     /// assert!(n.div_floor(&d) * d + n.mod_floor(&d) == n)
-    /// ~~~
+    /// ```
     ///
     /// # Examples
     ///
-    /// ~~~
+    /// ```
     /// # use num::Integer;
     /// assert!(( 8i).mod_floor(& 3) ==  2);
     /// assert!(( 8i).mod_floor(&-3) == -1);
@@ -52,29 +52,29 @@ pub trait Integer: Num + PartialOrd
     /// assert!(( 1i).mod_floor(&-2) == -1);
     /// assert!((-1i).mod_floor(& 2) ==  1);
     /// assert!((-1i).mod_floor(&-2) == -1);
-    /// ~~~
+    /// ```
     fn mod_floor(&self, other: &Self) -> Self;
 
     /// Greatest Common Divisor (GCD).
     ///
     /// # Examples
     ///
-    /// ~~~
+    /// ```
     /// # use num::Integer;
     /// assert_eq!(6i.gcd(&8), 2);
     /// assert_eq!(7i.gcd(&3), 1);
-    /// ~~~
+    /// ```
     fn gcd(&self, other: &Self) -> Self;
 
     /// Lowest Common Multiple (LCM).
     ///
     /// # Examples
     ///
-    /// ~~~
+    /// ```
     /// # use num::Integer;
     /// assert_eq!(7i.lcm(&3), 21);
     /// assert_eq!(2i.lcm(&4), 4);
-    /// ~~~
+    /// ```
     fn lcm(&self, other: &Self) -> Self;
 
     /// Deprecated, use `is_multiple_of` instead.
@@ -85,33 +85,33 @@ pub trait Integer: Num + PartialOrd
     ///
     /// # Examples
     ///
-    /// ~~~
+    /// ```
     /// # use num::Integer;
     /// assert_eq!(9i.is_multiple_of(&3), true);
     /// assert_eq!(3i.is_multiple_of(&9), false);
-    /// ~~~
+    /// ```
     fn is_multiple_of(&self, other: &Self) -> bool;
 
     /// Returns `true` if the number is even.
     ///
     /// # Examples
     ///
-    /// ~~~
+    /// ```
     /// # use num::Integer;
     /// assert_eq!(3i.is_even(), false);
     /// assert_eq!(4i.is_even(), true);
-    /// ~~~
+    /// ```
     fn is_even(&self) -> bool;
 
     /// Returns `true` if the number is odd.
     ///
     /// # Examples
     ///
-    /// ~~~
+    /// ```
     /// # use num::Integer;
     /// assert_eq!(3i.is_odd(), true);
     /// assert_eq!(4i.is_odd(), false);
-    /// ~~~
+    /// ```
     fn is_odd(&self) -> bool;
 
     /// Simultaneous truncated integer division and modulus.
@@ -119,7 +119,7 @@ pub trait Integer: Num + PartialOrd
     ///
     /// # Examples
     ///
-    /// ~~~
+    /// ```
     /// # use num::Integer;
     /// assert_eq!(( 8i).div_rem( &3), ( 2,  2));
     /// assert_eq!(( 8i).div_rem(&-3), (-2,  2));
@@ -130,7 +130,7 @@ pub trait Integer: Num + PartialOrd
     /// assert_eq!(( 1i).div_rem(&-2), ( 0,  1));
     /// assert_eq!((-1i).div_rem( &2), ( 0, -1));
     /// assert_eq!((-1i).div_rem(&-2), ( 0, -1));
-    /// ~~~
+    /// ```
     #[inline]
     fn div_rem(&self, other: &Self) -> (Self, Self) {
         (*self / *other, *self % *other)
@@ -141,7 +141,7 @@ pub trait Integer: Num + PartialOrd
     ///
     /// # Examples
     ///
-    /// ~~~
+    /// ```
     /// # use num::Integer;
     /// assert_eq!(( 8i).div_mod_floor( &3), ( 2,  2));
     /// assert_eq!(( 8i).div_mod_floor(&-3), (-3, -1));
@@ -152,7 +152,7 @@ pub trait Integer: Num + PartialOrd
     /// assert_eq!(( 1i).div_mod_floor(&-2), (-1, -1));
     /// assert_eq!((-1i).div_mod_floor( &2), (-1,  1));
     /// assert_eq!((-1i).div_mod_floor(&-2), ( 0, -1));
-    /// ~~~
+    /// ```
     fn div_mod_floor(&self, other: &Self) -> (Self, Self) {
         (self.div_floor(other), self.mod_floor(other))
     }
diff --git a/src/libstd/bitflags.rs b/src/libstd/bitflags.rs
index 3d1bc20cca4..7a7c340c8c5 100644
--- a/src/libstd/bitflags.rs
+++ b/src/libstd/bitflags.rs
@@ -21,7 +21,7 @@
 ///
 /// # Example
 ///
-/// ~~~rust
+/// ```{.rust}
 /// bitflags! {
 ///     flags Flags: u32 {
 ///         static FlagA       = 0x00000001,
@@ -41,11 +41,11 @@
 ///     assert!((e1 - e2) == FlagA);     // set difference
 ///     assert!(!e2 == FlagA);           // set complement
 /// }
-/// ~~~
+/// ```
 ///
 /// The generated `struct`s can also be extended with type and trait implementations:
 ///
-/// ~~~rust
+/// ```{.rust}
 /// use std::fmt;
 ///
 /// bitflags! {
@@ -74,7 +74,7 @@
 ///     assert!(flags.is_empty());
 ///     assert_eq!(format!("{}", flags).as_slice(), "hi!");
 /// }
-/// ~~~
+/// ```
 ///
 /// # Attributes
 ///
diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs
index 0ebca006c4c..c11350ea3ac 100644
--- a/src/libstd/macros.rs
+++ b/src/libstd/macros.rs
@@ -192,7 +192,7 @@ macro_rules! debug_assert_eq(
 ///
 /// # Example
 ///
-/// ~~~rust
+/// ```{.rust}
 /// struct Item { weight: uint }
 ///
 /// fn choose_weighted_item(v: &[Item]) -> Item {
@@ -208,7 +208,7 @@ macro_rules! debug_assert_eq(
 ///     // type checker that it isn't possible to get down here
 ///     unreachable!();
 /// }
-/// ~~~
+/// ```
 #[macro_export]
 macro_rules! unreachable(
     () => (fail!("internal error: entered unreachable code"))
diff --git a/src/libsyntax/ext/deriving/generic/mod.rs b/src/libsyntax/ext/deriving/generic/mod.rs
index ff249495bd7..31b242da27b 100644
--- a/src/libsyntax/ext/deriving/generic/mod.rs
+++ b/src/libsyntax/ext/deriving/generic/mod.rs
@@ -101,32 +101,32 @@
 //!
 //! When generating the `expr` for the `A` impl, the `SubstructureFields` is
 //!
-//! ~~~text
+//! ```{.text}
 //! Struct(~[FieldInfo {
 //!            span: <span of x>
 //!            name: Some(<ident of x>),
 //!            self_: <expr for &self.x>,
 //!            other: ~[<expr for &other.x]
 //!          }])
-//! ~~~
+//! ```
 //!
 //! For the `B` impl, called with `B(a)` and `B(b)`,
 //!
-//! ~~~text
+//! ```{.text}
 //! Struct(~[FieldInfo {
 //!           span: <span of `int`>,
 //!           name: None,
 //!           <expr for &a>
 //!           ~[<expr for &b>]
 //!          }])
-//! ~~~
+//! ```
 //!
 //! ## Enums
 //!
 //! When generating the `expr` for a call with `self == C0(a)` and `other
 //! == C0(b)`, the SubstructureFields is
 //!
-//! ~~~text
+//! ```{.text}
 //! EnumMatching(0, <ast::Variant for C0>,
 //!              ~[FieldInfo {
 //!                 span: <span of int>
@@ -134,11 +134,11 @@
 //!                 self_: <expr for &a>,
 //!                 other: ~[<expr for &b>]
 //!               }])
-//! ~~~
+//! ```
 //!
 //! For `C1 {x}` and `C1 {x}`,
 //!
-//! ~~~text
+//! ```{.text}
 //! EnumMatching(1, <ast::Variant for C1>,
 //!              ~[FieldInfo {
 //!                 span: <span of x>
@@ -146,16 +146,16 @@
 //!                 self_: <expr for &self.x>,
 //!                 other: ~[<expr for &other.x>]
 //!                }])
-//! ~~~
+//! ```
 //!
 //! For `C0(a)` and `C1 {x}` ,
 //!
-//! ~~~text
+//! ```{.text}
 //! EnumNonMatchingCollapsed(
 //!     ~[<ident of self>, <ident of __arg_1>],
 //!     &[<ast::Variant for C0>, <ast::Variant for C1>],
 //!     &[<ident for self index value>, <ident of __arg_1 index value>])
-//! ~~~
+//! ```
 //!
 //! It is the same for when the arguments are flipped to `C1 {x}` and
 //! `C0(a)`; the only difference is what the values of the identifiers
@@ -170,7 +170,7 @@
 //!
 //! A static method on the above would result in,
 //!
-//! ~~~text
+//! ```{.text}
 //! StaticStruct(<ast::StructDef of A>, Named(~[(<ident of x>, <span of x>)]))
 //!
 //! StaticStruct(<ast::StructDef of B>, Unnamed(~[<span of x>]))
@@ -178,7 +178,7 @@
 //! StaticEnum(<ast::EnumDef of C>, ~[(<ident of C0>, <span of C0>, Unnamed(~[<span of int>])),
 //!                                   (<ident of C1>, <span of C1>,
 //!                                    Named(~[(<ident of x>, <span of x>)]))])
-//! ~~~
+//! ```
 
 use std::cell::RefCell;
 use std::gc::GC;
@@ -286,21 +286,17 @@ pub enum StaticFields {
 /// and examples
 pub enum SubstructureFields<'a> {
     Struct(Vec<FieldInfo>),
-    /**
-    Matching variants of the enum: variant index, ast::Variant,
-    fields: the field name is only non-`None` in the case of a struct
-    variant.
-    */
+    /// Matching variants of the enum: variant index, ast::Variant,
+    /// fields: the field name is only non-`None` in the case of a struct
+    /// variant.
     EnumMatching(uint, &'a ast::Variant, Vec<FieldInfo>),
 
-    /**
-    non-matching variants of the enum, but with all state hidden from
-    the consequent code.  The first component holds Idents for all of
-    the Self arguments; the second component is a slice of all of the
-    variants for the enum itself, and the third component is a list of
-    Idents bound to the variant index values for each of the actual
-    input Self arguments.
-    */
+    /// non-matching variants of the enum, but with all state hidden from
+    /// the consequent code.  The first component holds Idents for all of
+    /// the Self arguments; the second component is a slice of all of the
+    /// variants for the enum itself, and the third component is a list of
+    /// Idents bound to the variant index values for each of the actual
+    /// input Self arguments.
     EnumNonMatchingCollapsed(Vec<Ident>, &'a [P<ast::Variant>], &'a [Ident]),
 
     /// A static method where Self is a struct.
@@ -311,20 +307,16 @@ pub enum SubstructureFields<'a> {
 
 
 
-/**
-Combine the values of all the fields together. The last argument is
-all the fields of all the structures, see above for details.
-*/
+/// Combine the values of all the fields together. The last argument is
+/// all the fields of all the structures, see above for details.
 pub type CombineSubstructureFunc<'a> =
     |&mut ExtCtxt, Span, &Substructure|: 'a -> P<Expr>;
 
-/**
-Deal with non-matching enum variants.  The tuple is a list of
-identifiers (one for each Self argument, which could be any of the
-variants since they have been collapsed together) and the identifiers
-holding the variant index value for each of the Self arguments.  The
-last argument is all the non-Self args of the method being derived.
-*/
+/// Deal with non-matching enum variants.  The tuple is a list of
+/// identifiers (one for each Self argument, which could be any of the
+/// variants since they have been collapsed together) and the identifiers
+/// holding the variant index value for each of the Self arguments.  The
+/// last argument is all the non-Self args of the method being derived.
 pub type EnumNonMatchCollapsedFunc<'a> =
     |&mut ExtCtxt,
      Span,
@@ -374,18 +366,14 @@ impl<'a> TraitDef<'a> {
         }))
     }
 
-    /**
-     *
-     * Given that we are deriving a trait `Tr` for a type `T<'a, ...,
-     * 'z, A, ..., Z>`, creates an impl like:
-     *
-     * ```ignore
-     *      impl<'a, ..., 'z, A:Tr B1 B2, ..., Z: Tr B1 B2> Tr for T<A, ..., Z> { ... }
-     * ```
-     *
-     * where B1, B2, ... are the bounds given by `bounds_paths`.'
-     *
-     */
+    /// Given that we are deriving a trait `Tr` for a type `T<'a, ...,
+    /// 'z, A, ..., Z>`, creates an impl like:
+    ///
+    /// ```ignore
+    ///      impl<'a, ..., 'z, A:Tr B1 B2, ..., Z: Tr B1 B2> Tr for T<A, ..., Z> { ... }
+    /// ```
+    ///
+    /// where B1, B2, ... are the bounds given by `bounds_paths`.'
     fn create_derived_impl(&self,
                            cx: &mut ExtCtxt,
                            type_ident: Ident,
@@ -694,27 +682,25 @@ impl<'a> MethodDef<'a> {
         })
     }
 
-    /**
-   ~~~
-    #[deriving(PartialEq)]
-    struct A { x: int, y: int }
-
-    // equivalent to:
-    impl PartialEq for A {
-        fn eq(&self, __arg_1: &A) -> bool {
-            match *self {
-                A {x: ref __self_0_0, y: ref __self_0_1} => {
-                    match *__arg_1 {
-                        A {x: ref __self_1_0, y: ref __self_1_1} => {
-                            __self_0_0.eq(__self_1_0) && __self_0_1.eq(__self_1_1)
-                        }
-                    }
-                }
-            }
-        }
-    }
-   ~~~
-    */
+    /// ```
+    /// #[deriving(PartialEq)]
+    /// struct A { x: int, y: int }
+    ///
+    /// // equivalent to:
+    /// impl PartialEq for A {
+    ///     fn eq(&self, __arg_1: &A) -> bool {
+    ///         match *self {
+    ///             A {x: ref __self_0_0, y: ref __self_0_1} => {
+    ///                 match *__arg_1 {
+    ///                     A {x: ref __self_1_0, y: ref __self_1_1} => {
+    ///                         __self_0_0.eq(__self_1_0) && __self_0_1.eq(__self_1_1)
+    ///                     }
+    ///                 }
+    ///             }
+    ///         }
+    ///     }
+    /// }
+    /// ```
     fn expand_struct_method_body(&self,
                                  cx: &mut ExtCtxt,
                                  trait_: &TraitDef,
@@ -799,37 +785,35 @@ impl<'a> MethodDef<'a> {
                                       &StaticStruct(struct_def, summary))
     }
 
-    /**
-   ~~~
-    #[deriving(PartialEq)]
-    enum A {
-        A1,
-        A2(int)
-    }
-
-    // is equivalent to
-
-    impl PartialEq for A {
-        fn eq(&self, __arg_1: &A) -> ::bool {
-            match (&*self, &*__arg_1) {
-                (&A1, &A1) => true,
-                (&A2(ref __self_0),
-                 &A2(ref __arg_1_0)) => (*__self_0).eq(&(*__arg_1_0)),
-                _ => {
-                    let __self_vi = match *self { A1(..) => 0u, A2(..) => 1u };
-                    let __arg_1_vi = match *__arg_1 { A1(..) => 0u, A2(..) => 1u };
-                    false
-                }
-            }
-        }
-    }
-   ~~~
-
-    (Of course `__self_vi` and `__arg_1_vi` are unused for
-     `PartialEq`, and those subcomputations will hopefully be removed
-     as their results are unused.  The point of `__self_vi` and
-     `__arg_1_vi` is for `PartialOrd`; see #15503.)
-    */
+    /// ```
+    /// #[deriving(PartialEq)]
+    /// enum A {
+    ///     A1,
+    ///     A2(int)
+    /// }
+    ///
+    /// // is equivalent to
+    ///
+    /// impl PartialEq for A {
+    ///     fn eq(&self, __arg_1: &A) -> ::bool {
+    ///         match (&*self, &*__arg_1) {
+    ///             (&A1, &A1) => true,
+    ///             (&A2(ref __self_0),
+    ///              &A2(ref __arg_1_0)) => (*__self_0).eq(&(*__arg_1_0)),
+    ///             _ => {
+    ///                 let __self_vi = match *self { A1(..) => 0u, A2(..) => 1u };
+    ///                 let __arg_1_vi = match *__arg_1 { A1(..) => 0u, A2(..) => 1u };
+    ///                 false
+    ///             }
+    ///         }
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// (Of course `__self_vi` and `__arg_1_vi` are unused for
+    /// `PartialEq`, and those subcomputations will hopefully be removed
+    /// as their results are unused.  The point of `__self_vi` and
+    /// `__arg_1_vi` is for `PartialOrd`; see #15503.)
     fn expand_enum_method_body(&self,
                                cx: &mut ExtCtxt,
                                trait_: &TraitDef,
@@ -843,33 +827,31 @@ impl<'a> MethodDef<'a> {
     }
 
 
-    /**
-    Creates a match for a tuple of all `self_args`, where either all
-    variants match, or it falls into a catch-all for when one variant
-    does not match.
-
-    There are N + 1 cases because is a case for each of the N
-    variants where all of the variants match, and one catch-all for
-    when one does not match.
-
-    The catch-all handler is provided access the variant index values
-    for each of the self-args, carried in precomputed variables. (Nota
-    bene: the variant index values are not necessarily the
-    discriminant values.  See issue #15523.)
-
-    ~~~text
-    match (this, that, ...) {
-      (Variant1, Variant1, Variant1) => ... // delegate Matching on Variant1
-      (Variant2, Variant2, Variant2) => ... // delegate Matching on Variant2
-      ...
-      _ => {
-        let __this_vi = match this { Variant1 => 0u, Variant2 => 1u, ... };
-        let __that_vi = match that { Variant1 => 0u, Variant2 => 1u, ... };
-        ... // catch-all remainder can inspect above variant index values.
-      }
-    }
-    ~~~
-    */
+    /// Creates a match for a tuple of all `self_args`, where either all
+    /// variants match, or it falls into a catch-all for when one variant
+    /// does not match.
+
+    /// There are N + 1 cases because is a case for each of the N
+    /// variants where all of the variants match, and one catch-all for
+    /// when one does not match.
+
+    /// The catch-all handler is provided access the variant index values
+    /// for each of the self-args, carried in precomputed variables. (Nota
+    /// bene: the variant index values are not necessarily the
+    /// discriminant values.  See issue #15523.)
+
+    /// ```{.text}
+    /// match (this, that, ...) {
+    ///   (Variant1, Variant1, Variant1) => ... // delegate Matching on Variant1
+    ///   (Variant2, Variant2, Variant2) => ... // delegate Matching on Variant2
+    ///   ...
+    ///   _ => {
+    ///     let __this_vi = match this { Variant1 => 0u, Variant2 => 1u, ... };
+    ///     let __that_vi = match that { Variant1 => 0u, Variant2 => 1u, ... };
+    ///     ... // catch-all remainder can inspect above variant index values.
+    ///   }
+    /// }
+    /// ```
     fn build_enum_match_tuple(
         &self,
         cx: &mut ExtCtxt,
@@ -1320,10 +1302,8 @@ impl<'a> TraitDef<'a> {
 
 /* helpful premade recipes */
 
-/**
-Fold the fields. `use_foldl` controls whether this is done
-left-to-right (`true`) or right-to-left (`false`).
-*/
+/// Fold the fields. `use_foldl` controls whether this is done
+/// left-to-right (`true`) or right-to-left (`false`).
 pub fn cs_fold(use_foldl: bool,
                f: |&mut ExtCtxt, Span, P<Expr>, P<Expr>, &[P<Expr>]| -> P<Expr>,
                base: P<Expr>,
@@ -1362,15 +1342,13 @@ pub fn cs_fold(use_foldl: bool,
 }
 
 
-/**
-Call the method that is being derived on all the fields, and then
-process the collected results. i.e.
-
-~~~
-f(cx, span, ~[self_1.method(__arg_1_1, __arg_2_1),
-              self_2.method(__arg_1_2, __arg_2_2)])
-~~~
-*/
+/// Call the method that is being derived on all the fields, and then
+/// process the collected results. i.e.
+///
+/// ```
+/// f(cx, span, ~[self_1.method(__arg_1_1, __arg_2_1),
+///              self_2.method(__arg_1_2, __arg_2_2)])
+/// ```
 #[inline]
 pub fn cs_same_method(f: |&mut ExtCtxt, Span, Vec<P<Expr>>| -> P<Expr>,
                       enum_nonmatch_f: EnumNonMatchCollapsedFunc,
@@ -1401,11 +1379,9 @@ pub fn cs_same_method(f: |&mut ExtCtxt, Span, Vec<P<Expr>>| -> P<Expr>,
     }
 }
 
-/**
-Fold together the results of calling the derived method on all the
-fields. `use_foldl` controls whether this is done left-to-right
-(`true`) or right-to-left (`false`).
-*/
+/// Fold together the results of calling the derived method on all the
+/// fields. `use_foldl` controls whether this is done left-to-right
+/// (`true`) or right-to-left (`false`).
 #[inline]
 pub fn cs_same_method_fold(use_foldl: bool,
                            f: |&mut ExtCtxt, Span, P<Expr>, P<Expr>| -> P<Expr>,
@@ -1431,10 +1407,8 @@ pub fn cs_same_method_fold(use_foldl: bool,
         cx, trait_span, substructure)
 }
 
-/**
-Use a given binop to combine the result of calling the derived method
-on all the fields.
-*/
+/// Use a given binop to combine the result of calling the derived method
+/// on all the fields.
 #[inline]
 pub fn cs_binop(binop: ast::BinOp, base: P<Expr>,
                 enum_nonmatch_f: EnumNonMatchCollapsedFunc,
diff --git a/src/libtest/stats.rs b/src/libtest/stats.rs
index 7087d4c4238..93c5e00b6ea 100644
--- a/src/libtest/stats.rs
+++ b/src/libtest/stats.rs
@@ -352,10 +352,9 @@ pub fn write_5_number_summary<T: Float + Show>(w: &mut io::Writer,
 /// As an example, the summary with 5-number-summary `(min=15, q1=17, med=20, q3=24, max=31)` might
 /// display as:
 ///
-/// ~~~~ignore
+/// ```{.ignore}
 ///   10 |        [--****#******----------]          | 40
-/// ~~~~
-
+/// ```
 pub fn write_boxplot<T: Float + Show + FromPrimitive>(
                      w: &mut io::Writer,
                      s: &Summary<T>,