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

8 files changed, 60 insertions, 61 deletions

diff --git a/src/libsyntax/ast_util.rs b/src/libsyntax/ast_util.rs
index c6fb9349ad5..551c6817405 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 e1cfa4830ae..838e275332b 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 7ddc763fac9..04f533be5bf 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 8a32ecdac64..a85e791696f 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 747ca07bee5..c9292308810 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 e2e35447af3..8ea7306e180 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 4c573b45a1f..c4ae9269914 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 cf4d24b8599..bb0f82e89fc 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;
 }