syntax: doc comments all the things

9 files changed, 288 insertions, 284 deletions

diff --git a/src/libsyntax/parse/attr.rs b/src/libsyntax/parse/attr.rs
index 53489e32837..b2297ec770c 100644
--- a/src/libsyntax/parse/attr.rs
+++ b/src/libsyntax/parse/attr.rs
@@ -18,7 +18,7 @@ use parse::token::INTERPOLATED;
 
 use std::gc::{Gc, GC};
 
-// a parser that can parse attributes.
+/// A parser that can parse attributes.
 pub trait ParserAttr {
     fn parse_outer_attributes(&mut self) -> Vec<ast::Attribute>;
     fn parse_attribute(&mut self, permit_inner: bool) -> ast::Attribute;
@@ -30,7 +30,7 @@ pub trait ParserAttr {
 }
 
 impl<'a> ParserAttr for Parser<'a> {
-    // Parse attributes that appear before an item
+    /// Parse attributes that appear before an item
     fn parse_outer_attributes(&mut self) -> Vec<ast::Attribute> {
         let mut attrs: Vec<ast::Attribute> = Vec::new();
         loop {
@@ -59,10 +59,10 @@ impl<'a> ParserAttr for Parser<'a> {
         return attrs;
     }
 
-    // matches attribute = # ! [ meta_item ]
-    //
-    // if permit_inner is true, then a leading `!` indicates an inner
-    // attribute
+    /// Matches `attribute = # ! [ meta_item ]`
+    ///
+    /// If permit_inner is true, then a leading `!` indicates an inner
+    /// attribute
     fn parse_attribute(&mut self, permit_inner: bool) -> ast::Attribute {
         debug!("parse_attributes: permit_inner={:?} self.token={:?}",
                permit_inner, self.token);
@@ -114,17 +114,17 @@ impl<'a> ParserAttr for Parser<'a> {
         };
     }
 
-    // Parse attributes that appear after the opening of an item. These should
-    // be preceded by an exclamation mark, but we accept and warn about one
-    // terminated by a semicolon. In addition to a vector of inner attributes,
-    // this function also returns a vector that may contain the first outer
-    // attribute of the next item (since we can't know whether the attribute
-    // is an inner attribute of the containing item or an outer attribute of
-    // the first contained item until we see the semi).
-
-    // matches inner_attrs* outer_attr?
-    // you can make the 'next' field an Option, but the result is going to be
-    // more useful as a vector.
+    /// Parse attributes that appear after the opening of an item. These should
+    /// be preceded by an exclamation mark, but we accept and warn about one
+    /// terminated by a semicolon. In addition to a vector of inner attributes,
+    /// this function also returns a vector that may contain the first outer
+    /// attribute of the next item (since we can't know whether the attribute
+    /// is an inner attribute of the containing item or an outer attribute of
+    /// the first contained item until we see the semi).
+
+    /// matches inner_attrs* outer_attr?
+    /// you can make the 'next' field an Option, but the result is going to be
+    /// more useful as a vector.
     fn parse_inner_attrs_and_next(&mut self)
                                   -> (Vec<ast::Attribute> , Vec<ast::Attribute> ) {
         let mut inner_attrs: Vec<ast::Attribute> = Vec::new();
@@ -157,9 +157,9 @@ impl<'a> ParserAttr for Parser<'a> {
         (inner_attrs, next_outer_attrs)
     }
 
-    // matches meta_item = IDENT
-    // | IDENT = lit
-    // | IDENT meta_seq
+    /// matches meta_item = IDENT
+    /// | IDENT = lit
+    /// | IDENT meta_seq
     fn parse_meta_item(&mut self) -> Gc<ast::MetaItem> {
         match self.token {
             token::INTERPOLATED(token::NtMeta(e)) => {
@@ -201,7 +201,7 @@ impl<'a> ParserAttr for Parser<'a> {
         }
     }
 
-    // matches meta_seq = ( COMMASEP(meta_item) )
+    /// matches meta_seq = ( COMMASEP(meta_item) )
     fn parse_meta_seq(&mut self) -> Vec<Gc<ast::MetaItem>> {
         self.parse_seq(&token::LPAREN,
                        &token::RPAREN,
diff --git a/src/libsyntax/parse/classify.rs b/src/libsyntax/parse/classify.rs
index 8d9cc305c26..516f22cdf4d 100644
--- a/src/libsyntax/parse/classify.rs
+++ b/src/libsyntax/parse/classify.rs
@@ -15,13 +15,13 @@
 use ast;
 use std::gc::Gc;
 
-// does this expression require a semicolon to be treated
-// as a statement? The negation of this: 'can this expression
-// be used as a statement without a semicolon' -- is used
-// as an early-bail-out in the parser so that, for instance,
-// 'if true {...} else {...}
-//  |x| 5 '
-// isn't parsed as (if true {...} else {...} | x) | 5
+/// Does this expression require a semicolon to be treated
+/// as a statement? The negation of this: 'can this expression
+/// be used as a statement without a semicolon' -- is used
+/// as an early-bail-out in the parser so that, for instance,
+///     if true {...} else {...}
+///      |x| 5
+/// isn't parsed as (if true {...} else {...} | x) | 5
 pub fn expr_requires_semi_to_be_stmt(e: Gc<ast::Expr>) -> bool {
     match e.node {
         ast::ExprIf(..)
@@ -41,9 +41,9 @@ pub fn expr_is_simple_block(e: Gc<ast::Expr>) -> bool {
     }
 }
 
-// this statement requires a semicolon after it.
-// note that in one case (stmt_semi), we've already
-// seen the semicolon, and thus don't need another.
+/// this statement requires a semicolon after it.
+/// note that in one case (stmt_semi), we've already
+/// seen the semicolon, and thus don't need another.
 pub fn stmt_ends_with_semi(stmt: &ast::Stmt) -> bool {
     return match stmt.node {
         ast::StmtDecl(d, _) => {
diff --git a/src/libsyntax/parse/common.rs b/src/libsyntax/parse/common.rs
index 3c3f0c7a820..3842170d677 100644
--- a/src/libsyntax/parse/common.rs
+++ b/src/libsyntax/parse/common.rs
@@ -12,8 +12,8 @@
 
 use parse::token;
 
-// SeqSep : a sequence separator (token)
-// and whether a trailing separator is allowed.
+/// SeqSep : a sequence separator (token)
+/// and whether a trailing separator is allowed.
 pub struct SeqSep {
     pub sep: Option<token::Token>,
     pub trailing_sep_allowed: bool
diff --git a/src/libsyntax/parse/lexer/comments.rs b/src/libsyntax/parse/lexer/comments.rs
index 73e5bb97f51..c5dd10382a9 100644
--- a/src/libsyntax/parse/lexer/comments.rs
+++ b/src/libsyntax/parse/lexer/comments.rs
@@ -24,10 +24,14 @@ use std::uint;
 
 #[deriving(Clone, PartialEq)]
 pub enum CommentStyle {
-    Isolated, // No code on either side of each line of the comment
-    Trailing, // Code exists to the left of the comment
-    Mixed, // Code before /* foo */ and after the comment
-    BlankLine, // Just a manual blank line "\n\n", for layout
+    /// No code on either side of each line of the comment
+    Isolated,
+    /// Code exists to the left of the comment
+    Trailing,
+    /// Code before /* foo */ and after the comment
+    Mixed,
+    /// Just a manual blank line "\n\n", for layout
+    BlankLine,
 }
 
 #[deriving(Clone)]
@@ -198,9 +202,9 @@ fn read_line_comments(rdr: &mut StringReader, code_to_the_left: bool,
     }
 }
 
-// Returns None if the first col chars of s contain a non-whitespace char.
-// Otherwise returns Some(k) where k is first char offset after that leading
-// whitespace.  Note k may be outside bounds of s.
+/// Returns None if the first col chars of s contain a non-whitespace char.
+/// Otherwise returns Some(k) where k is first char offset after that leading
+/// whitespace.  Note k may be outside bounds of s.
 fn all_whitespace(s: &str, col: CharPos) -> Option<uint> {
     let len = s.len();
     let mut col = col.to_uint();
diff --git a/src/libsyntax/parse/lexer/mod.rs b/src/libsyntax/parse/lexer/mod.rs
index 1e72b2de20f..43bbba85271 100644
--- a/src/libsyntax/parse/lexer/mod.rs
+++ b/src/libsyntax/parse/lexer/mod.rs
@@ -44,13 +44,13 @@ pub struct TokenAndSpan {
 
 pub struct StringReader<'a> {
     pub span_diagnostic: &'a SpanHandler,
-    // The absolute offset within the codemap of the next character to read
+    /// The absolute offset within the codemap of the next character to read
     pub pos: BytePos,
-    // The absolute offset within the codemap of the last character read(curr)
+    /// The absolute offset within the codemap of the last character read(curr)
     pub last_pos: BytePos,
-    // The column of the next character to read
+    /// The column of the next character to read
     pub col: CharPos,
-    // The last character to be read
+    /// The last character to be read
     pub curr: Option<char>,
     pub filemap: Rc<codemap::FileMap>,
     /* cached: */
@@ -60,7 +60,7 @@ pub struct StringReader<'a> {
 
 impl<'a> Reader for StringReader<'a> {
     fn is_eof(&self) -> bool { self.curr.is_none() }
-    // return the next token. EFFECT: advances the string_reader.
+    /// Return the next token. EFFECT: advances the string_reader.
     fn next_token(&mut self) -> TokenAndSpan {
         let ret_val = TokenAndSpan {
             tok: replace(&mut self.peek_tok, token::UNDERSCORE),
@@ -417,7 +417,7 @@ impl<'a> StringReader<'a> {
         return self.consume_any_line_comment();
     }
 
-    // might return a sugared-doc-attr
+    /// Might return a sugared-doc-attr
     fn consume_block_comment(&mut self) -> Option<TokenAndSpan> {
         // block comments starting with "/**" or "/*!" are doc-comments
         let is_doc_comment = self.curr_is('*') || self.curr_is('!');
diff --git a/src/libsyntax/parse/mod.rs b/src/libsyntax/parse/mod.rs
index fb4a23cf326..bea8b6a94d4 100644
--- a/src/libsyntax/parse/mod.rs
+++ b/src/libsyntax/parse/mod.rs
@@ -10,7 +10,6 @@
 
 //! The main parser interface
 
-
 use ast;
 use codemap::{Span, CodeMap, FileMap};
 use diagnostic::{SpanHandler, mk_span_handler, default_handler, Auto};
@@ -32,7 +31,7 @@ pub mod common;
 pub mod classify;
 pub mod obsolete;
 
-// info about a parsing session.
+/// Info about a parsing session.
 pub struct ParseSess {
     pub span_diagnostic: SpanHandler, // better be the same as the one in the reader!
     /// Used to determine and report recursive mod inclusions
@@ -241,14 +240,14 @@ pub fn file_to_filemap(sess: &ParseSess, path: &Path, spanopt: Option<Span>)
     unreachable!()
 }
 
-// given a session and a string, add the string to
-// the session's codemap and return the new filemap
+/// Given a session and a string, add the string to
+/// the session's codemap and return the new filemap
 pub fn string_to_filemap(sess: &ParseSess, source: String, path: String)
                          -> Rc<FileMap> {
     sess.span_diagnostic.cm.new_filemap(path, source)
 }
 
-// given a filemap, produce a sequence of token-trees
+/// Given a filemap, produce a sequence of token-trees
 pub fn filemap_to_tts(sess: &ParseSess, filemap: Rc<FileMap>)
     -> Vec<ast::TokenTree> {
     // it appears to me that the cfg doesn't matter here... indeed,
@@ -259,7 +258,7 @@ pub fn filemap_to_tts(sess: &ParseSess, filemap: Rc<FileMap>)
     p1.parse_all_token_trees()
 }
 
-// given tts and cfg, produce a parser
+/// Given tts and cfg, produce a parser
 pub fn tts_to_parser<'a>(sess: &'a ParseSess,
                          tts: Vec<ast::TokenTree>,
                          cfg: ast::CrateConfig) -> Parser<'a> {
@@ -267,7 +266,7 @@ pub fn tts_to_parser<'a>(sess: &'a ParseSess,
     Parser::new(sess, cfg, box trdr)
 }
 
-// abort if necessary
+/// Abort if necessary
 pub fn maybe_aborted<T>(result: T, mut p: Parser) -> T {
     p.abort_if_errors();
     result
diff --git a/src/libsyntax/parse/obsolete.rs b/src/libsyntax/parse/obsolete.rs
index 025684ae71e..cadae7ef12f 100644
--- a/src/libsyntax/parse/obsolete.rs
+++ b/src/libsyntax/parse/obsolete.rs
@@ -38,8 +38,8 @@ pub enum ObsoleteSyntax {
 pub trait ParserObsoleteMethods {
     /// Reports an obsolete syntax non-fatal error.
     fn obsolete(&mut self, sp: Span, kind: ObsoleteSyntax);
-    // Reports an obsolete syntax non-fatal error, and returns
-    // a placeholder expression
+    /// Reports an obsolete syntax non-fatal error, and returns
+    /// a placeholder expression
     fn obsolete_expr(&mut self, sp: Span, kind: ObsoleteSyntax) -> Gc<Expr>;
     fn report(&mut self,
               sp: Span,
@@ -83,8 +83,8 @@ impl<'a> ParserObsoleteMethods for parser::Parser<'a> {
         self.report(sp, kind, kind_str, desc);
     }
 
-    // Reports an obsolete syntax non-fatal error, and returns
-    // a placeholder expression
+    /// Reports an obsolete syntax non-fatal error, and returns
+    /// a placeholder expression
     fn obsolete_expr(&mut self, sp: Span, kind: ObsoleteSyntax) -> Gc<Expr> {
         self.obsolete(sp, kind);
         self.mk_expr(sp.lo, sp.hi, ExprLit(box(GC) respan(sp, LitNil)))
diff --git a/src/libsyntax/parse/parser.rs b/src/libsyntax/parse/parser.rs
index ac4cbf3aa8e..3bf88424891 100644
--- a/src/libsyntax/parse/parser.rs
+++ b/src/libsyntax/parse/parser.rs
@@ -117,8 +117,8 @@ pub struct PathAndBounds {
 }
 
 enum ItemOrViewItem {
-    // Indicates a failure to parse any kind of item. The attributes are
-    // returned.
+    /// Indicates a failure to parse any kind of item. The attributes are
+    /// returned.
     IoviNone(Vec<Attribute>),
     IoviItem(Gc<Item>),
     IoviForeignItem(Gc<ForeignItem>),
@@ -126,12 +126,12 @@ enum ItemOrViewItem {
 }
 
 
-// Possibly accept an `INTERPOLATED` expression (a pre-parsed expression
-// dropped into the token stream, which happens while parsing the
-// result of macro expansion)
-/* Placement of these is not as complex as I feared it would be.
-The important thing is to make sure that lookahead doesn't balk
-at INTERPOLATED tokens */
+/// Possibly accept an `INTERPOLATED` expression (a pre-parsed expression
+/// dropped into the token stream, which happens while parsing the
+/// result of macro expansion)
+/// Placement of these is not as complex as I feared it would be.
+/// The important thing is to make sure that lookahead doesn't balk
+/// at INTERPOLATED tokens
 macro_rules! maybe_whole_expr (
     ($p:expr) => (
         {
@@ -166,7 +166,7 @@ macro_rules! maybe_whole_expr (
     )
 )
 
-// As above, but for things other than expressions
+/// As maybe_whole_expr, but for things other than expressions
 macro_rules! maybe_whole (
     ($p:expr, $constructor:ident) => (
         {
@@ -287,14 +287,14 @@ struct ParsedItemsAndViewItems {
 
 pub struct Parser<'a> {
     pub sess: &'a ParseSess,
-    // the current token:
+    /// the current token:
     pub token: token::Token,
-    // the span of the current token:
+    /// the span of the current token:
     pub span: Span,
-    // the span of the prior token:
+    /// the span of the prior token:
     pub last_span: Span,
     pub cfg: CrateConfig,
-    // the previous token or None (only stashed sometimes).
+    /// the previous token or None (only stashed sometimes).
     pub last_token: Option<Box<token::Token>>,
     pub buffer: [TokenAndSpan, ..4],
     pub buffer_start: int,
@@ -361,12 +361,13 @@ impl<'a> Parser<'a> {
             root_module_name: None,
         }
     }
-    // convert a token to a string using self's reader
+
+    /// Convert a token to a string using self's reader
     pub fn token_to_string(token: &token::Token) -> String {
         token::to_string(token)
     }
 
-    // convert the current token to a string using self's reader
+    /// Convert the current token to a string using self's reader
     pub fn this_token_to_string(&mut self) -> String {
         Parser::token_to_string(&self.token)
     }
@@ -383,8 +384,8 @@ impl<'a> Parser<'a> {
         self.fatal(format!("unexpected token: `{}`", this_token).as_slice());
     }
 
-    // expect and consume the token t. Signal an error if
-    // the next token is not t.
+    /// Expect and consume the token t. Signal an error if
+    /// the next token is not t.
     pub fn expect(&mut self, t: &token::Token) {
         if self.token == *t {
             self.bump();
@@ -397,9 +398,9 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // Expect next token to be edible or inedible token.  If edible,
-    // then consume it; if inedible, then return without consuming
-    // anything.  Signal a fatal error if next token is unexpected.
+    /// Expect next token to be edible or inedible token.  If edible,
+    /// then consume it; if inedible, then return without consuming
+    /// anything.  Signal a fatal error if next token is unexpected.
     pub fn expect_one_of(&mut self,
                          edible: &[token::Token],
                          inedible: &[token::Token]) {
@@ -437,9 +438,9 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // Check for erroneous `ident { }`; if matches, signal error and
-    // recover (without consuming any expected input token).  Returns
-    // true if and only if input was consumed for recovery.
+    /// Check for erroneous `ident { }`; if matches, signal error and
+    /// recover (without consuming any expected input token).  Returns
+    /// true if and only if input was consumed for recovery.
     pub fn check_for_erroneous_unit_struct_expecting(&mut self, expected: &[token::Token]) -> bool {
         if self.token == token::LBRACE
             && expected.iter().all(|t| *t != token::LBRACE)
@@ -456,9 +457,9 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // Commit to parsing a complete expression `e` expected to be
-    // followed by some token from the set edible + inedible.  Recover
-    // from anticipated input errors, discarding erroneous characters.
+    /// Commit to parsing a complete expression `e` expected to be
+    /// followed by some token from the set edible + inedible.  Recover
+    /// from anticipated input errors, discarding erroneous characters.
     pub fn commit_expr(&mut self, e: Gc<Expr>, edible: &[token::Token],
                        inedible: &[token::Token]) {
         debug!("commit_expr {:?}", e);
@@ -479,9 +480,9 @@ impl<'a> Parser<'a> {
         self.commit_expr(e, &[edible], &[])
     }
 
-    // Commit to parsing a complete statement `s`, which expects to be
-    // followed by some token from the set edible + inedible.  Check
-    // for recoverable input errors, discarding erroneous characters.
+    /// Commit to parsing a complete statement `s`, which expects to be
+    /// followed by some token from the set edible + inedible.  Check
+    /// for recoverable input errors, discarding erroneous characters.
     pub fn commit_stmt(&mut self, s: Gc<Stmt>, edible: &[token::Token],
                        inedible: &[token::Token]) {
         debug!("commit_stmt {:?}", s);
@@ -526,8 +527,8 @@ impl<'a> Parser<'a> {
                                               id: ast::DUMMY_NODE_ID })
     }
 
-    // consume token 'tok' if it exists. Returns true if the given
-    // token was present, false otherwise.
+    /// Consume token 'tok' if it exists. Returns true if the given
+    /// token was present, false otherwise.
     pub fn eat(&mut self, tok: &token::Token) -> bool {
         let is_present = self.token == *tok;
         if is_present { self.bump() }
@@ -538,8 +539,8 @@ impl<'a> Parser<'a> {
         token::is_keyword(kw, &self.token)
     }
 
-    // if the next token is the given keyword, eat it and return
-    // true. Otherwise, return false.
+    /// If the next token is the given keyword, eat it and return
+    /// true. Otherwise, return false.
     pub fn eat_keyword(&mut self, kw: keywords::Keyword) -> bool {
         match self.token {
             token::IDENT(sid, false) if kw.to_name() == sid.name => {
@@ -550,9 +551,9 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // if the given word is not a keyword, signal an error.
-    // if the next token is not the given word, signal an error.
-    // otherwise, eat it.
+    /// If the given word is not a keyword, signal an error.
+    /// If the next token is not the given word, signal an error.
+    /// Otherwise, eat it.
     pub fn expect_keyword(&mut self, kw: keywords::Keyword) {
         if !self.eat_keyword(kw) {
             let id_interned_str = token::get_name(kw.to_name());
@@ -562,7 +563,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // signal an error if the given string is a strict keyword
+    /// Signal an error if the given string is a strict keyword
     pub fn check_strict_keywords(&mut self) {
         if token::is_strict_keyword(&self.token) {
             let token_str = self.this_token_to_string();
@@ -573,7 +574,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // signal an error if the current token is a reserved keyword
+    /// Signal an error if the current token is a reserved keyword
     pub fn check_reserved_keywords(&mut self) {
         if token::is_reserved_keyword(&self.token) {
             let token_str = self.this_token_to_string();
@@ -582,8 +583,8 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // Expect and consume an `&`. If `&&` is seen, replace it with a single
-    // `&` and continue. If an `&` is not seen, signal an error.
+    /// Expect and consume an `&`. If `&&` is seen, replace it with a single
+    /// `&` and continue. If an `&` is not seen, signal an error.
     fn expect_and(&mut self) {
         match self.token {
             token::BINOP(token::AND) => self.bump(),
@@ -603,8 +604,8 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // Expect and consume a `|`. If `||` is seen, replace it with a single
-    // `|` and continue. If a `|` is not seen, signal an error.
+    /// Expect and consume a `|`. If `||` is seen, replace it with a single
+    /// `|` and continue. If a `|` is not seen, signal an error.
     fn expect_or(&mut self) {
         match self.token {
             token::BINOP(token::OR) => self.bump(),
@@ -624,26 +625,26 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // Attempt to consume a `<`. If `<<` is seen, replace it with a single
-    // `<` and continue. If a `<` is not seen, return false.
-    //
-    // This is meant to be used when parsing generics on a path to get the
-    // starting token. The `force` parameter is used to forcefully break up a
-    // `<<` token. If `force` is false, then `<<` is only broken when a lifetime
-    // shows up next. For example, consider the expression:
-    //
-    //      foo as bar << test
-    //
-    // The parser needs to know if `bar <<` is the start of a generic path or if
-    // it's a left-shift token. If `test` were a lifetime, then it's impossible
-    // for the token to be a left-shift, but if it's not a lifetime, then it's
-    // considered a left-shift.
-    //
-    // The reason for this is that the only current ambiguity with `<<` is when
-    // parsing closure types:
-    //
-    //      foo::<<'a> ||>();
-    //      impl Foo<<'a> ||>() { ... }
+    /// Attempt to consume a `<`. If `<<` is seen, replace it with a single
+    /// `<` and continue. If a `<` is not seen, return false.
+    ///
+    /// This is meant to be used when parsing generics on a path to get the
+    /// starting token. The `force` parameter is used to forcefully break up a
+    /// `<<` token. If `force` is false, then `<<` is only broken when a lifetime
+    /// shows up next. For example, consider the expression:
+    ///
+    ///      foo as bar << test
+    ///
+    /// The parser needs to know if `bar <<` is the start of a generic path or if
+    /// it's a left-shift token. If `test` were a lifetime, then it's impossible
+    /// for the token to be a left-shift, but if it's not a lifetime, then it's
+    /// considered a left-shift.
+    ///
+    /// The reason for this is that the only current ambiguity with `<<` is when
+    /// parsing closure types:
+    ///
+    ///      foo::<<'a> ||>();
+    ///      impl Foo<<'a> ||>() { ... }
     fn eat_lt(&mut self, force: bool) -> bool {
         match self.token {
             token::LT => { self.bump(); true }
@@ -675,7 +676,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // Parse a sequence bracketed by `|` and `|`, stopping before the `|`.
+    /// Parse a sequence bracketed by `|` and `|`, stopping before the `|`.
     fn parse_seq_to_before_or<T>(
                               &mut self,
                               sep: &token::Token,
@@ -696,9 +697,9 @@ impl<'a> Parser<'a> {
         vector
     }
 
-    // expect and consume a GT. if a >> is seen, replace it
-    // with a single > and continue. If a GT is not seen,
-    // signal an error.
+    /// Expect and consume a GT. if a >> is seen, replace it
+    /// with a single > and continue. If a GT is not seen,
+    /// signal an error.
     pub fn expect_gt(&mut self) {
         match self.token {
             token::GT => self.bump(),
@@ -727,8 +728,8 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse a sequence bracketed by '<' and '>', stopping
-    // before the '>'.
+    /// Parse a sequence bracketed by '<' and '>', stopping
+    /// before the '>'.
     pub fn parse_seq_to_before_gt<T>(
                                   &mut self,
                                   sep: Option<token::Token>,
@@ -762,9 +763,9 @@ impl<'a> Parser<'a> {
         return v;
     }
 
-    // parse a sequence, including the closing delimiter. The function
-    // f must consume tokens until reaching the next separator or
-    // closing bracket.
+    /// Parse a sequence, including the closing delimiter. The function
+    /// f must consume tokens until reaching the next separator or
+    /// closing bracket.
     pub fn parse_seq_to_end<T>(
                             &mut self,
                             ket: &token::Token,
@@ -776,9 +777,9 @@ impl<'a> Parser<'a> {
         val
     }
 
-    // parse a sequence, not including the closing delimiter. The function
-    // f must consume tokens until reaching the next separator or
-    // closing bracket.
+    /// Parse a sequence, not including the closing delimiter. The function
+    /// f must consume tokens until reaching the next separator or
+    /// closing bracket.
     pub fn parse_seq_to_before_end<T>(
                                    &mut self,
                                    ket: &token::Token,
@@ -801,9 +802,9 @@ impl<'a> Parser<'a> {
         return v;
     }
 
-    // parse a sequence, including the closing delimiter. The function
-    // f must consume tokens until reaching the next separator or
-    // closing bracket.
+    /// Parse a sequence, including the closing delimiter. The function
+    /// f must consume tokens until reaching the next separator or
+    /// closing bracket.
     pub fn parse_unspanned_seq<T>(
                                &mut self,
                                bra: &token::Token,
@@ -817,8 +818,8 @@ impl<'a> Parser<'a> {
         result
     }
 
-    // parse a sequence parameter of enum variant. For consistency purposes,
-    // these should not be empty.
+    /// Parse a sequence parameter of enum variant. For consistency purposes,
+    /// these should not be empty.
     pub fn parse_enum_variant_seq<T>(
                                &mut self,
                                bra: &token::Token,
@@ -852,7 +853,7 @@ impl<'a> Parser<'a> {
         spanned(lo, hi, result)
     }
 
-    // advance the parser by one token
+    /// Advance the parser by one token
     pub fn bump(&mut self) {
         self.last_span = self.span;
         // Stash token for error recovery (sometimes; clone is not necessarily cheap).
@@ -880,14 +881,14 @@ impl<'a> Parser<'a> {
         self.tokens_consumed += 1u;
     }
 
-    // Advance the parser by one token and return the bumped token.
+    /// Advance the parser by one token and return the bumped token.
     pub fn bump_and_get(&mut self) -> token::Token {
         let old_token = replace(&mut self.token, token::UNDERSCORE);
         self.bump();
         old_token
     }
 
-    // EFFECT: replace the current token and span with the given one
+    /// EFFECT: replace the current token and span with the given one
     pub fn replace_token(&mut self,
                          next: token::Token,
                          lo: BytePos,
@@ -940,8 +941,8 @@ impl<'a> Parser<'a> {
         token::get_ident(id)
     }
 
-    // Is the current token one of the keywords that signals a bare function
-    // type?
+    /// Is the current token one of the keywords that signals a bare function
+    /// type?
     pub fn token_is_bare_fn_keyword(&mut self) -> bool {
         if token::is_keyword(keywords::Fn, &self.token) {
             return true
@@ -955,14 +956,14 @@ impl<'a> Parser<'a> {
         false
     }
 
-    // Is the current token one of the keywords that signals a closure type?
+    /// Is the current token one of the keywords that signals a closure type?
     pub fn token_is_closure_keyword(&mut self) -> bool {
         token::is_keyword(keywords::Unsafe, &self.token) ||
             token::is_keyword(keywords::Once, &self.token)
     }
 
-    // Is the current token one of the keywords that signals an old-style
-    // closure type (with explicit sigil)?
+    /// Is the current token one of the keywords that signals an old-style
+    /// closure type (with explicit sigil)?
     pub fn token_is_old_style_closure_keyword(&mut self) -> bool {
         token::is_keyword(keywords::Unsafe, &self.token) ||
             token::is_keyword(keywords::Once, &self.token) ||
@@ -983,7 +984,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse a TyBareFn type:
+    /// parse a TyBareFn type:
     pub fn parse_ty_bare_fn(&mut self) -> Ty_ {
         /*
 
@@ -1014,8 +1015,8 @@ impl<'a> Parser<'a> {
         });
     }
 
-    // Parses a procedure type (`proc`). The initial `proc` keyword must
-    // already have been parsed.
+    /// Parses a procedure type (`proc`). The initial `proc` keyword must
+    /// already have been parsed.
     pub fn parse_proc_type(&mut self) -> Ty_ {
         /*
 
@@ -1063,7 +1064,7 @@ impl<'a> Parser<'a> {
         })
     }
 
-    // parse a TyClosure type
+    /// Parse a TyClosure type
     pub fn parse_ty_closure(&mut self) -> Ty_ {
         /*
 
@@ -1154,7 +1155,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse a function type (following the 'fn')
+    /// Parse a function type (following the 'fn')
     pub fn parse_ty_fn_decl(&mut self, allow_variadic: bool)
                             -> (P<FnDecl>, Vec<ast::Lifetime>) {
         /*
@@ -1186,7 +1187,7 @@ impl<'a> Parser<'a> {
         (decl, lifetimes)
     }
 
-    // parse the methods in a trait declaration
+    /// Parse the methods in a trait declaration
     pub fn parse_trait_methods(&mut self) -> Vec<TraitMethod> {
         self.parse_unspanned_seq(
             &token::LBRACE,
@@ -1255,15 +1256,15 @@ impl<'a> Parser<'a> {
         })
     }
 
-    // parse a possibly mutable type
+    /// Parse a possibly mutable type
     pub fn parse_mt(&mut self) -> MutTy {
         let mutbl = self.parse_mutability();
         let t = self.parse_ty(true);
         MutTy { ty: t, mutbl: mutbl }
     }
 
-    // parse [mut/const/imm] ID : TY
-    // now used only by obsolete record syntax parser...
+    /// Parse [mut/const/imm] ID : TY
+    /// now used only by obsolete record syntax parser...
     pub fn parse_ty_field(&mut self) -> TypeField {
         let lo = self.span.lo;
         let mutbl = self.parse_mutability();
@@ -1278,7 +1279,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse optional return type [ -> TY ] in function decl
+    /// Parse optional return type [ -> TY ] in function decl
     pub fn parse_ret_ty(&mut self) -> (RetStyle, P<Ty>) {
         return if self.eat(&token::RARROW) {
             let lo = self.span.lo;
@@ -1478,8 +1479,8 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // This version of parse arg doesn't necessarily require
-    // identifier names.
+    /// This version of parse arg doesn't necessarily require
+    /// identifier names.
     pub fn parse_arg_general(&mut self, require_name: bool) -> Arg {
         let pat = if require_name || self.is_named_argument() {
             debug!("parse_arg_general parse_pat (require_name:{:?})",
@@ -1504,12 +1505,12 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse a single function argument
+    /// Parse a single function argument
     pub fn parse_arg(&mut self) -> Arg {
         self.parse_arg_general(true)
     }
 
-    // parse an argument in a lambda header e.g. |arg, arg|
+    /// Parse an argument in a lambda header e.g. |arg, arg|
     pub fn parse_fn_block_arg(&mut self) -> Arg {
         let pat = self.parse_pat();
         let t = if self.eat(&token::COLON) {
@@ -1539,7 +1540,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // matches token_lit = LIT_INT | ...
+    /// Matches token_lit = LIT_INT | ...
     pub fn lit_from_token(&mut self, tok: &token::Token) -> Lit_ {
         match *tok {
             token::LIT_BYTE(i) => LitByte(i),
@@ -1566,7 +1567,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // matches lit = true | false | token_lit
+    /// Matches lit = true | false | token_lit
     pub fn parse_lit(&mut self) -> Lit {
         let lo = self.span.lo;
         let lit = if self.eat_keyword(keywords::True) {
@@ -1581,7 +1582,7 @@ impl<'a> Parser<'a> {
         codemap::Spanned { node: lit, span: mk_sp(lo, self.last_span.hi) }
     }
 
-    // matches '-' lit | lit
+    /// matches '-' lit | lit
     pub fn parse_literal_maybe_minus(&mut self) -> Gc<Expr> {
         let minus_lo = self.span.lo;
         let minus_present = self.eat(&token::BINOP(token::MINUS));
@@ -1719,7 +1720,7 @@ impl<'a> Parser<'a> {
     }
 
     /// Parses a single lifetime
-    // matches lifetime = LIFETIME
+    /// Matches lifetime = LIFETIME
     pub fn parse_lifetime(&mut self) -> ast::Lifetime {
         match self.token {
             token::LIFETIME(i) => {
@@ -1779,7 +1780,7 @@ impl<'a> Parser<'a> {
         token::is_keyword(keywords::Const, tok)
     }
 
-    // parse mutability declaration (mut/const/imm)
+    /// Parse mutability declaration (mut/const/imm)
     pub fn parse_mutability(&mut self) -> Mutability {
         if self.eat_keyword(keywords::Mut) {
             MutMutable
@@ -1788,7 +1789,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse ident COLON expr
+    /// Parse ident COLON expr
     pub fn parse_field(&mut self) -> Field {
         let lo = self.span.lo;
         let i = self.parse_ident();
@@ -1867,9 +1868,9 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // at the bottom (top?) of the precedence hierarchy,
-    // parse things like parenthesized exprs,
-    // macros, return, etc.
+    /// At the bottom (top?) of the precedence hierarchy,
+    /// parse things like parenthesized exprs,
+    /// macros, return, etc.
     pub fn parse_bottom_expr(&mut self) -> Gc<Expr> {
         maybe_whole_expr!(self);
 
@@ -2107,7 +2108,7 @@ impl<'a> Parser<'a> {
         return self.mk_expr(lo, hi, ex);
     }
 
-    // parse a block or unsafe block
+    /// Parse a block or unsafe block
     pub fn parse_block_expr(&mut self, lo: BytePos, blk_mode: BlockCheckMode)
                             -> Gc<Expr> {
         self.expect(&token::LBRACE);
@@ -2115,7 +2116,7 @@ impl<'a> Parser<'a> {
         return self.mk_expr(blk.span.lo, blk.span.hi, ExprBlock(blk));
     }
 
-    // parse a.b or a(13) or a[4] or just a
+    /// parse a.b or a(13) or a[4] or just a
     pub fn parse_dot_or_call_expr(&mut self) -> Gc<Expr> {
         let b = self.parse_bottom_expr();
         self.parse_dot_or_call_expr_with(b)
@@ -2199,8 +2200,8 @@ impl<'a> Parser<'a> {
         return e;
     }
 
-    // parse an optional separator followed by a kleene-style
-    // repetition token (+ or *).
+    /// Parse an optional separator followed by a kleene-style
+    /// repetition token (+ or *).
     pub fn parse_sep_and_zerok(&mut self) -> (Option<token::Token>, bool) {
         fn parse_zerok(parser: &mut Parser) -> Option<bool> {
             match parser.token {
@@ -2225,7 +2226,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse a single token tree from the input.
+    /// parse a single token tree from the input.
     pub fn parse_token_tree(&mut self) -> TokenTree {
         // FIXME #6994: currently, this is too eager. It
         // parses token trees but also identifies TTSeq's
@@ -2341,9 +2342,9 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // This goofy function is necessary to correctly match parens in Matcher's.
-    // Otherwise, `$( ( )` would be a valid Matcher, and `$( () )` would be
-    // invalid. It's similar to common::parse_seq.
+    /// This goofy function is necessary to correctly match parens in Matcher's.
+    /// Otherwise, `$( ( )` would be a valid Matcher, and `$( () )` would be
+    /// invalid. It's similar to common::parse_seq.
     pub fn parse_matcher_subseq_upto(&mut self,
                                      name_idx: &mut uint,
                                      ket: &token::Token)
@@ -2392,7 +2393,7 @@ impl<'a> Parser<'a> {
         return spanned(lo, self.span.hi, m);
     }
 
-    // parse a prefix-operator expr
+    /// Parse a prefix-operator expr
     pub fn parse_prefix_expr(&mut self) -> Gc<Expr> {
         let lo = self.span.lo;
         let hi;
@@ -2500,13 +2501,13 @@ impl<'a> Parser<'a> {
         return self.mk_expr(lo, hi, ex);
     }
 
-    // parse an expression of binops
+    /// Parse an expression of binops
     pub fn parse_binops(&mut self) -> Gc<Expr> {
         let prefix_expr = self.parse_prefix_expr();
         self.parse_more_binops(prefix_expr, 0)
     }
 
-    // parse an expression of binops of at least min_prec precedence
+    /// Parse an expression of binops of at least min_prec precedence
     pub fn parse_more_binops(&mut self, lhs: Gc<Expr>,
                              min_prec: uint) -> Gc<Expr> {
         if self.expr_is_complete(lhs) { return lhs; }
@@ -2554,9 +2555,9 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse an assignment expression....
-    // actually, this seems to be the main entry point for
-    // parsing an arbitrary expression.
+    /// Parse an assignment expression....
+    /// actually, this seems to be the main entry point for
+    /// parsing an arbitrary expression.
     pub fn parse_assign_expr(&mut self) -> Gc<Expr> {
         let lo = self.span.lo;
         let lhs = self.parse_binops();
@@ -2590,7 +2591,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse an 'if' expression ('if' token already eaten)
+    /// Parse an 'if' expression ('if' token already eaten)
     pub fn parse_if_expr(&mut self) -> Gc<Expr> {
         let lo = self.last_span.lo;
         let cond = self.parse_expr_res(RESTRICT_NO_STRUCT_LITERAL);
@@ -2605,7 +2606,7 @@ impl<'a> Parser<'a> {
         self.mk_expr(lo, hi, ExprIf(cond, thn, els))
     }
 
-    // `|args| { ... }` or `{ ...}` like in `do` expressions
+    /// `|args| { ... }` or `{ ...}` like in `do` expressions
     pub fn parse_lambda_block_expr(&mut self) -> Gc<Expr> {
         self.parse_lambda_expr_(
             |p| {
@@ -2634,15 +2635,15 @@ impl<'a> Parser<'a> {
             })
     }
 
-    // `|args| expr`
+    /// `|args| expr`
     pub fn parse_lambda_expr(&mut self) -> Gc<Expr> {
         self.parse_lambda_expr_(|p| p.parse_fn_block_decl(),
                                 |p| p.parse_expr())
     }
 
-    // parse something of the form |args| expr
-    // this is used both in parsing a lambda expr
-    // and in parsing a block expr as e.g. in for...
+    /// parse something of the form |args| expr
+    /// this is used both in parsing a lambda expr
+    /// and in parsing a block expr as e.g. in for...
     pub fn parse_lambda_expr_(&mut self,
                               parse_decl: |&mut Parser| -> P<FnDecl>,
                               parse_body: |&mut Parser| -> Gc<Expr>)
@@ -2671,7 +2672,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse a 'for' .. 'in' expression ('for' token already eaten)
+    /// Parse a 'for' .. 'in' expression ('for' token already eaten)
     pub fn parse_for_expr(&mut self, opt_ident: Option<ast::Ident>) -> Gc<Expr> {
         // Parse: `for <src_pat> in <src_expr> <src_loop_block>`
 
@@ -2737,12 +2738,12 @@ impl<'a> Parser<'a> {
         return self.mk_expr(lo, hi, ExprMatch(discriminant, arms));
     }
 
-    // parse an expression
+    /// Parse an expression
     pub fn parse_expr(&mut self) -> Gc<Expr> {
         return self.parse_expr_res(UNRESTRICTED);
     }
 
-    // parse an expression, subject to the given restriction
+    /// Parse an expression, subject to the given restriction
     pub fn parse_expr_res(&mut self, r: restriction) -> Gc<Expr> {
         let old = self.restriction;
         self.restriction = r;
@@ -2751,7 +2752,7 @@ impl<'a> Parser<'a> {
         return e;
     }
 
-    // parse the RHS of a local variable declaration (e.g. '= 14;')
+    /// Parse the RHS of a local variable declaration (e.g. '= 14;')
     fn parse_initializer(&mut self) -> Option<Gc<Expr>> {
         if self.token == token::EQ {
             self.bump();
@@ -2761,7 +2762,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse patterns, separated by '|' s
+    /// Parse patterns, separated by '|' s
     fn parse_pats(&mut self) -> Vec<Gc<Pat>> {
         let mut pats = Vec::new();
         loop {
@@ -2824,7 +2825,7 @@ impl<'a> Parser<'a> {
         (before, slice, after)
     }
 
-    // parse the fields of a struct-like pattern
+    /// Parse the fields of a struct-like pattern
     fn parse_pat_fields(&mut self) -> (Vec<ast::FieldPat> , bool) {
         let mut fields = Vec::new();
         let mut etc = false;
@@ -2884,7 +2885,7 @@ impl<'a> Parser<'a> {
         return (fields, etc);
     }
 
-    // parse a pattern.
+    /// Parse a pattern.
     pub fn parse_pat(&mut self) -> Gc<Pat> {
         maybe_whole!(self, NtPat);
 
@@ -3126,9 +3127,9 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse ident or ident @ pat
-    // used by the copy foo and ref foo patterns to give a good
-    // error message when parsing mistakes like ref foo(a,b)
+    /// Parse ident or ident @ pat
+    /// used by the copy foo and ref foo patterns to give a good
+    /// error message when parsing mistakes like ref foo(a,b)
     fn parse_pat_ident(&mut self,
                        binding_mode: ast::BindingMode)
                        -> ast::Pat_ {
@@ -3162,7 +3163,7 @@ impl<'a> Parser<'a> {
         PatIdent(binding_mode, name, sub)
     }
 
-    // parse a local variable declaration
+    /// Parse a local variable declaration
     fn parse_local(&mut self) -> Gc<Local> {
         let lo = self.span.lo;
         let pat = self.parse_pat();
@@ -3186,14 +3187,14 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse a "let" stmt
+    /// Parse a "let" stmt
     fn parse_let(&mut self) -> Gc<Decl> {
         let lo = self.span.lo;
         let local = self.parse_local();
         box(GC) spanned(lo, self.last_span.hi, DeclLocal(local))
     }
 
-    // parse a structure field
+    /// Parse a structure field
     fn parse_name_and_ty(&mut self, pr: Visibility,
                          attrs: Vec<Attribute> ) -> StructField {
         let lo = self.span.lo;
@@ -3211,8 +3212,8 @@ impl<'a> Parser<'a> {
         })
     }
 
-    // parse a statement. may include decl.
-    // precondition: any attributes are parsed already
+    /// Parse a statement. may include decl.
+    /// Precondition: any attributes are parsed already
     pub fn parse_stmt(&mut self, item_attrs: Vec<Attribute>) -> Gc<Stmt> {
         maybe_whole!(self, NtStmt);
 
@@ -3315,13 +3316,13 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // is this expression a successfully-parsed statement?
+    /// Is this expression a successfully-parsed statement?
     fn expr_is_complete(&mut self, e: Gc<Expr>) -> bool {
         return self.restriction == RESTRICT_STMT_EXPR &&
             !classify::expr_requires_semi_to_be_stmt(e);
     }
 
-    // parse a block. No inner attrs are allowed.
+    /// Parse a block. No inner attrs are allowed.
     pub fn parse_block(&mut self) -> P<Block> {
         maybe_whole!(no_clone self, NtBlock);
 
@@ -3331,7 +3332,7 @@ impl<'a> Parser<'a> {
         return self.parse_block_tail_(lo, DefaultBlock, Vec::new());
     }
 
-    // parse a block. Inner attrs are allowed.
+    /// Parse a block. Inner attrs are allowed.
     fn parse_inner_attrs_and_block(&mut self)
         -> (Vec<Attribute> , P<Block>) {
 
@@ -3344,15 +3345,15 @@ impl<'a> Parser<'a> {
         (inner, self.parse_block_tail_(lo, DefaultBlock, next))
     }
 
-    // Precondition: already parsed the '{' or '#{'
-    // I guess that also means "already parsed the 'impure'" if
-    // necessary, and this should take a qualifier.
-    // some blocks start with "#{"...
+    /// Precondition: already parsed the '{' or '#{'
+    /// I guess that also means "already parsed the 'impure'" if
+    /// necessary, and this should take a qualifier.
+    /// Some blocks start with "#{"...
     fn parse_block_tail(&mut self, lo: BytePos, s: BlockCheckMode) -> P<Block> {
         self.parse_block_tail_(lo, s, Vec::new())
     }
 
-    // parse the rest of a block expression or function body
+    /// Parse the rest of a block expression or function body
     fn parse_block_tail_(&mut self, lo: BytePos, s: BlockCheckMode,
                          first_item_attrs: Vec<Attribute> ) -> P<Block> {
         let mut stmts = Vec::new();
@@ -3510,18 +3511,18 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // matches bounds    = ( boundseq )?
-    // where   boundseq  = ( bound + boundseq ) | bound
-    // and     bound     = 'static | ty
-    // Returns "None" if there's no colon (e.g. "T");
-    // Returns "Some(Empty)" if there's a colon but nothing after (e.g. "T:")
-    // Returns "Some(stuff)" otherwise (e.g. "T:stuff").
-    // NB: The None/Some distinction is important for issue #7264.
-    //
-    // Note that the `allow_any_lifetime` argument is a hack for now while the
-    // AST doesn't support arbitrary lifetimes in bounds on type parameters. In
-    // the future, this flag should be removed, and the return value of this
-    // function should be Option<~[TyParamBound]>
+    /// matches optbounds = ( ( : ( boundseq )? )? )
+    /// where   boundseq  = ( bound + boundseq ) | bound
+    /// and     bound     = 'static | ty
+    /// Returns "None" if there's no colon (e.g. "T");
+    /// Returns "Some(Empty)" if there's a colon but nothing after (e.g. "T:")
+    /// Returns "Some(stuff)" otherwise (e.g. "T:stuff").
+    /// NB: The None/Some distinction is important for issue #7264.
+    ///
+    /// Note that the `allow_any_lifetime` argument is a hack for now while the
+    /// AST doesn't support arbitrary lifetimes in bounds on type parameters. In
+    /// the future, this flag should be removed, and the return value of this
+    /// function should be Option<~[TyParamBound]>
     fn parse_ty_param_bounds(&mut self, allow_any_lifetime: bool)
                              -> (Option<ast::Lifetime>,
                                  OwnedSlice<TyParamBound>) {
@@ -3588,7 +3589,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // matches typaram = (unbound`?`)? IDENT optbounds ( EQ ty )?
+    /// Matches typaram = (unbound`?`)? IDENT optbounds ( EQ ty )?
     fn parse_ty_param(&mut self) -> TyParam {
         // This is a bit hacky. Currently we are only interested in a single
         // unbound, and it may only be `Sized`. To avoid backtracking and other
@@ -3632,10 +3633,10 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse a set of optional generic type parameter declarations
-    // matches generics = ( ) | ( < > ) | ( < typaramseq ( , )? > ) | ( < lifetimes ( , )? > )
-    //                  | ( < lifetimes , typaramseq ( , )? > )
-    // where   typaramseq = ( typaram ) | ( typaram , typaramseq )
+    /// Parse a set of optional generic type parameter declarations
+    /// matches generics = ( ) | ( < > ) | ( < typaramseq ( , )? > ) | ( < lifetimes ( , )? > )
+    ///                  | ( < lifetimes , typaramseq ( , )? > )
+    /// where   typaramseq = ( typaram ) | ( typaram , typaramseq )
     pub fn parse_generics(&mut self) -> ast::Generics {
         if self.eat(&token::LT) {
             let lifetimes = self.parse_lifetimes();
@@ -3727,7 +3728,7 @@ impl<'a> Parser<'a> {
         (args, variadic)
     }
 
-    // parse the argument list and result type of a function declaration
+    /// Parse the argument list and result type of a function declaration
     pub fn parse_fn_decl(&mut self, allow_variadic: bool) -> P<FnDecl> {
 
         let (args, variadic) = self.parse_fn_args(true, allow_variadic);
@@ -3762,8 +3763,8 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse the argument list and result type of a function
-    // that may have a self type.
+    /// Parse the argument list and result type of a function
+    /// that may have a self type.
     fn parse_fn_decl_with_self(&mut self, parse_arg_fn: |&mut Parser| -> Arg)
                                -> (ExplicitSelf, P<FnDecl>) {
         fn maybe_parse_borrowed_explicit_self(this: &mut Parser)
@@ -3921,7 +3922,7 @@ impl<'a> Parser<'a> {
         (spanned(lo, hi, explicit_self), fn_decl)
     }
 
-    // parse the |arg, arg| header on a lambda
+    /// Parse the |arg, arg| header on a lambda
     fn parse_fn_block_decl(&mut self) -> P<FnDecl> {
         let inputs_captures = {
             if self.eat(&token::OROR) {
@@ -3953,7 +3954,7 @@ impl<'a> Parser<'a> {
         })
     }
 
-    // Parses the `(arg, arg) -> return_type` header on a procedure.
+    /// Parses the `(arg, arg) -> return_type` header on a procedure.
     fn parse_proc_decl(&mut self) -> P<FnDecl> {
         let inputs =
             self.parse_unspanned_seq(&token::LPAREN,
@@ -3979,7 +3980,7 @@ impl<'a> Parser<'a> {
         })
     }
 
-    // parse the name and optional generic types of a function header.
+    /// Parse the name and optional generic types of a function header.
     fn parse_fn_header(&mut self) -> (Ident, ast::Generics) {
         let id = self.parse_ident();
         let generics = self.parse_generics();
@@ -3999,7 +4000,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse an item-position function declaration.
+    /// Parse an item-position function declaration.
     fn parse_item_fn(&mut self, fn_style: FnStyle, abi: abi::Abi) -> ItemInfo {
         let (ident, generics) = self.parse_fn_header();
         let decl = self.parse_fn_decl(false);
@@ -4007,7 +4008,7 @@ impl<'a> Parser<'a> {
         (ident, ItemFn(decl, fn_style, abi, generics, body), Some(inner_attrs))
     }
 
-    // parse a method in a trait impl, starting with `attrs` attributes.
+    /// Parse a method in a trait impl, starting with `attrs` attributes.
     fn parse_method(&mut self,
                     already_parsed_attrs: Option<Vec<Attribute>>) -> Gc<Method> {
         let next_attrs = self.parse_outer_attributes();
@@ -4043,7 +4044,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse trait Foo { ... }
+    /// Parse trait Foo { ... }
     fn parse_item_trait(&mut self) -> ItemInfo {
         let ident = self.parse_ident();
         let tps = self.parse_generics();
@@ -4062,9 +4063,9 @@ impl<'a> Parser<'a> {
         (ident, ItemTrait(tps, sized, traits, meths), None)
     }
 
-    // Parses two variants (with the region/type params always optional):
-    //    impl<T> Foo { ... }
-    //    impl<T> ToString for ~[T] { ... }
+    /// Parses two variants (with the region/type params always optional):
+    ///    impl<T> Foo { ... }
+    ///    impl<T> ToString for ~[T] { ... }
     fn parse_item_impl(&mut self) -> ItemInfo {
         // First, parse type parameters if necessary.
         let generics = self.parse_generics();
@@ -4117,7 +4118,7 @@ impl<'a> Parser<'a> {
         (ident, ItemImpl(generics, opt_trait, ty, meths), Some(inner_attrs))
     }
 
-    // parse a::B<String,int>
+    /// Parse a::B<String,int>
     fn parse_trait_ref(&mut self) -> TraitRef {
         ast::TraitRef {
             path: self.parse_path(LifetimeAndTypesWithoutColons).path,
@@ -4125,7 +4126,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse B + C<String,int> + D
+    /// Parse B + C<String,int> + D
     fn parse_trait_ref_list(&mut self, ket: &token::Token) -> Vec<TraitRef> {
         self.parse_seq_to_before_end(
             ket,
@@ -4134,7 +4135,7 @@ impl<'a> Parser<'a> {
         )
     }
 
-    // parse struct Foo { ... }
+    /// Parse struct Foo { ... }
     fn parse_item_struct(&mut self, is_virtual: bool) -> ItemInfo {
         let class_name = self.parse_ident();
         let generics = self.parse_generics();
@@ -4217,7 +4218,7 @@ impl<'a> Parser<'a> {
          None)
     }
 
-    // parse a structure field declaration
+    /// Parse a structure field declaration
     pub fn parse_single_struct_field(&mut self,
                                      vis: Visibility,
                                      attrs: Vec<Attribute> )
@@ -4239,7 +4240,7 @@ impl<'a> Parser<'a> {
         a_var
     }
 
-    // parse an element of a struct definition
+    /// Parse an element of a struct definition
     fn parse_struct_decl_field(&mut self) -> StructField {
 
         let attrs = self.parse_outer_attributes();
@@ -4251,7 +4252,7 @@ impl<'a> Parser<'a> {
         return self.parse_single_struct_field(Inherited, attrs);
     }
 
-    // parse visiility: PUB, PRIV, or nothing
+    /// Parse visiility: PUB, PRIV, or nothing
     fn parse_visibility(&mut self) -> Visibility {
         if self.eat_keyword(keywords::Pub) { Public }
         else { Inherited }
@@ -4273,8 +4274,8 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // given a termination token and a vector of already-parsed
-    // attributes (of length 0 or 1), parse all of the items in a module
+    /// Given a termination token and a vector of already-parsed
+    /// attributes (of length 0 or 1), parse all of the items in a module
     fn parse_mod_items(&mut self,
                        term: token::Token,
                        first_item_attrs: Vec<Attribute>,
@@ -4342,7 +4343,7 @@ impl<'a> Parser<'a> {
         (id, ItemStatic(ty, m, e), None)
     }
 
-    // parse a `mod <foo> { ... }` or `mod <foo>;` item
+    /// Parse a `mod <foo> { ... }` or `mod <foo>;` item
     fn parse_item_mod(&mut self, outer_attrs: &[Attribute]) -> ItemInfo {
         let id_span = self.span;
         let id = self.parse_ident();
@@ -4380,7 +4381,7 @@ impl<'a> Parser<'a> {
         self.mod_path_stack.pop().unwrap();
     }
 
-    // read a module from a source file.
+    /// Read a module from a source file.
     fn eval_src_mod(&mut self,
                     id: ast::Ident,
                     outer_attrs: &[ast::Attribute],
@@ -4488,7 +4489,7 @@ impl<'a> Parser<'a> {
         return (ast::ItemMod(m0), mod_attrs);
     }
 
-    // parse a function declaration from a foreign module
+    /// Parse a function declaration from a foreign module
     fn parse_item_foreign_fn(&mut self, vis: ast::Visibility,
                              attrs: Vec<Attribute>) -> Gc<ForeignItem> {
         let lo = self.span.lo;
@@ -4506,7 +4507,7 @@ impl<'a> Parser<'a> {
                                    vis: vis }
     }
 
-    // parse a static item from a foreign module
+    /// Parse a static item from a foreign module
     fn parse_item_foreign_static(&mut self, vis: ast::Visibility,
                                  attrs: Vec<Attribute> ) -> Gc<ForeignItem> {
         let lo = self.span.lo;
@@ -4529,7 +4530,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse safe/unsafe and fn
+    /// Parse safe/unsafe and fn
     fn parse_fn_style(&mut self) -> FnStyle {
         if self.eat_keyword(keywords::Fn) { NormalFn }
         else if self.eat_keyword(keywords::Unsafe) {
@@ -4540,8 +4541,8 @@ impl<'a> Parser<'a> {
     }
 
 
-    // at this point, this is essentially a wrapper for
-    // parse_foreign_items.
+    /// At this point, this is essentially a wrapper for
+    /// parse_foreign_items.
     fn parse_foreign_mod_items(&mut self,
                                abi: abi::Abi,
                                first_item_attrs: Vec<Attribute> )
@@ -4642,7 +4643,7 @@ impl<'a> Parser<'a> {
         return IoviItem(item);
     }
 
-    // parse type Foo = Bar;
+    /// Parse type Foo = Bar;
     fn parse_item_type(&mut self) -> ItemInfo {
         let ident = self.parse_ident();
         let tps = self.parse_generics();
@@ -4652,8 +4653,8 @@ impl<'a> Parser<'a> {
         (ident, ItemTy(ty, tps), None)
     }
 
-    // parse a structure-like enum variant definition
-    // this should probably be renamed or refactored...
+    /// Parse a structure-like enum variant definition
+    /// this should probably be renamed or refactored...
     fn parse_struct_def(&mut self) -> Gc<StructDef> {
         let mut fields: Vec<StructField> = Vec::new();
         while self.token != token::RBRACE {
@@ -4669,7 +4670,7 @@ impl<'a> Parser<'a> {
         };
     }
 
-    // parse the part of an "enum" decl following the '{'
+    /// Parse the part of an "enum" decl following the '{'
     fn parse_enum_def(&mut self, _generics: &ast::Generics) -> EnumDef {
         let mut variants = Vec::new();
         let mut all_nullary = true;
@@ -4733,7 +4734,7 @@ impl<'a> Parser<'a> {
         ast::EnumDef { variants: variants }
     }
 
-    // parse an "enum" declaration
+    /// Parse an "enum" declaration
     fn parse_item_enum(&mut self) -> ItemInfo {
         let id = self.parse_ident();
         let generics = self.parse_generics();
@@ -4750,8 +4751,8 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // Parses a string as an ABI spec on an extern type or module. Consumes
-    // the `extern` keyword, if one is found.
+    /// Parses a string as an ABI spec on an extern type or module. Consumes
+    /// the `extern` keyword, if one is found.
     fn parse_opt_abi(&mut self) -> Option<abi::Abi> {
         match self.token {
             token::LIT_STR(s) | token::LIT_STR_RAW(s, _) => {
@@ -4777,10 +4778,10 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse one of the items or view items allowed by the
-    // flags; on failure, return IoviNone.
-    // NB: this function no longer parses the items inside an
-    // extern crate.
+    /// Parse one of the items or view items allowed by the
+    /// flags; on failure, return IoviNone.
+    /// NB: this function no longer parses the items inside an
+    /// extern crate.
     fn parse_item_or_view_item(&mut self,
                                attrs: Vec<Attribute> ,
                                macros_allowed: bool)
@@ -4988,7 +4989,7 @@ impl<'a> Parser<'a> {
         self.parse_macro_use_or_failure(attrs,macros_allowed,lo,visibility)
     }
 
-    // parse a foreign item; on failure, return IoviNone.
+    /// Parse a foreign item; on failure, return IoviNone.
     fn parse_foreign_item(&mut self,
                           attrs: Vec<Attribute> ,
                           macros_allowed: bool)
@@ -5011,7 +5012,7 @@ impl<'a> Parser<'a> {
         self.parse_macro_use_or_failure(attrs,macros_allowed,lo,visibility)
     }
 
-    // this is the fall-through for parsing items.
+    /// This is the fall-through for parsing items.
     fn parse_macro_use_or_failure(
         &mut self,
         attrs: Vec<Attribute> ,
@@ -5095,17 +5096,17 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // parse, e.g., "use a::b::{z,y}"
+    /// Parse, e.g., "use a::b::{z,y}"
     fn parse_use(&mut self) -> ViewItem_ {
         return ViewItemUse(self.parse_view_path());
     }
 
 
-    // matches view_path : MOD? IDENT EQ non_global_path
-    // | MOD? non_global_path MOD_SEP LBRACE RBRACE
-    // | MOD? non_global_path MOD_SEP LBRACE ident_seq RBRACE
-    // | MOD? non_global_path MOD_SEP STAR
-    // | MOD? non_global_path
+    /// Matches view_path : MOD? IDENT EQ non_global_path
+    /// | MOD? non_global_path MOD_SEP LBRACE RBRACE
+    /// | MOD? non_global_path MOD_SEP LBRACE ident_seq RBRACE
+    /// | MOD? non_global_path MOD_SEP STAR
+    /// | MOD? non_global_path
     fn parse_view_path(&mut self) -> Gc<ViewPath> {
         let lo = self.span.lo;
 
@@ -5228,10 +5229,10 @@ impl<'a> Parser<'a> {
                         ViewPathSimple(last, path, ast::DUMMY_NODE_ID));
     }
 
-    // Parses a sequence of items. Stops when it finds program
-    // text that can't be parsed as an item
-    // - mod_items uses extern_mod_allowed = true
-    // - block_tail_ uses extern_mod_allowed = false
+    /// Parses a sequence of items. Stops when it finds program
+    /// text that can't be parsed as an item
+    /// - mod_items uses extern_mod_allowed = true
+    /// - block_tail_ uses extern_mod_allowed = false
     fn parse_items_and_view_items(&mut self,
                                   first_item_attrs: Vec<Attribute> ,
                                   mut extern_mod_allowed: bool,
@@ -5313,8 +5314,8 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // Parses a sequence of foreign items. Stops when it finds program
-    // text that can't be parsed as an item
+    /// Parses a sequence of foreign items. Stops when it finds program
+    /// text that can't be parsed as an item
     fn parse_foreign_items(&mut self, first_item_attrs: Vec<Attribute> ,
                            macros_allowed: bool)
         -> ParsedItemsAndViewItems {
@@ -5353,8 +5354,8 @@ impl<'a> Parser<'a> {
         }
     }
 
-    // Parses a source module as a crate. This is the main
-    // entry point for the parser.
+    /// Parses a source module as a crate. This is the main
+    /// entry point for the parser.
     pub fn parse_crate_mod(&mut self) -> Crate {
         let lo = self.span.lo;
         // parse the crate's inner attrs, maybe (oops) one
diff --git a/src/libsyntax/parse/token.rs b/src/libsyntax/parse/token.rs
index 55db3482a61..8bd74b9ca77 100644
--- a/src/libsyntax/parse/token.rs
+++ b/src/libsyntax/parse/token.rs
@@ -92,9 +92,9 @@ pub enum Token {
     LIT_BINARY_RAW(Rc<Vec<u8>>, uint), /* raw binary str delimited by n hash symbols */
 
     /* Name components */
-    // an identifier contains an "is_mod_name" boolean,
-    // indicating whether :: follows this token with no
-    // whitespace in between.
+    /// An identifier contains an "is_mod_name" boolean,
+    /// indicating whether :: follows this token with no
+    /// whitespace in between.
     IDENT(ast::Ident, bool),
     UNDERSCORE,
     LIFETIME(ast::Ident),