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

Author: Dretch

src/libcore/arc.rs

@@ -1,5 +1,7 @@
-#[doc = "An atomically reference counted wrapper that can be used to
-share immutable data between tasks."]
+/**
+ * An atomically reference counted wrapper that can be used to
+ * share immutable data between tasks.
+ */
 
 import comm::{port, chan, methods};
 import sys::methods;
@@ -41,7 +43,7 @@ class arc_destruct<T> {
 
 type arc<T: const> = arc_destruct<T>;
 
-#[doc="Create an atomically reference counted wrapper."]
+/// Create an atomically reference counted wrapper.
 fn arc<T: const>(-data: T) -> arc<T> {
     let data = ~{mut count: 1, data: data};
     unsafe {
@@ -50,8 +52,10 @@ fn arc<T: const>(-data: T) -> arc<T> {
     }
 }
 
-#[doc="Access the underlying data in an atomically reference counted
- wrapper."]
+/**
+ * Access the underlying data in an atomically reference counted
+ * wrapper.
+ */
 fn get<T: const>(rc: &a.arc<T>) -> &a.T {
     unsafe {
         let ptr: ~arc_data<T> = unsafe::reinterpret_cast((*rc).data);
@@ -62,11 +66,13 @@ fn get<T: const>(rc: &a.arc<T>) -> &a.T {
     }
 }
 
-#[doc="Duplicate an atomically reference counted wrapper.
-
-The resulting two `arc` objects will point to the same underlying data
-object. However, one of the `arc` objects can be sent to another task,
-allowing them to share the underlying data."]
+/**
+ * Duplicate an atomically reference counted wrapper.
+ *
+ * The resulting two `arc` objects will point to the same underlying data
+ * object. However, one of the `arc` objects can be sent to another task,
+ * allowing them to share the underlying data.
+ */
 fn clone<T: const>(rc: &arc<T>) -> arc<T> {
     unsafe {
         let ptr: ~arc_data<T> = unsafe::reinterpret_cast((*rc).data);

src/libcore/bool.rs

@@ -1,45 +1,43 @@
 // -*- rust -*-
 
-#[doc = "Boolean logic"];
+//! Boolean logic
 
 export not, and, or, xor, implies;
 export eq, ne, is_true, is_false;
 export from_str, to_str, all_values, to_bit;
 
-#[doc = "Negation / inverse"]
+/// Negation / inverse
 pure fn not(v: bool) -> bool { !v }
 
-#[doc = "Conjunction"]
+/// Conjunction
 pure fn and(a: bool, b: bool) -> bool { a && b }
 
-#[doc = "Disjunction"]
+/// Disjunction
 pure fn or(a: bool, b: bool) -> bool { a || b }
 
-#[doc = "
-Exclusive or
-
-Identical to `or(and(a, not(b)), and(not(a), b))`
-"]
+/**
+ * Exclusive or
+ *
+ * Identical to `or(and(a, not(b)), and(not(a), b))`
+ */
 pure fn xor(a: bool, b: bool) -> bool { (a && !b) || (!a && b) }
 
-#[doc = "Implication in the logic, i.e. from `a` follows `b`"]
+/// Implication in the logic, i.e. from `a` follows `b`
 pure fn implies(a: bool, b: bool) -> bool { !a || b }
 
-#[doc = "
-true if truth values `a` and `b` are indistinguishable in the logic
-"]
+/// true if truth values `a` and `b` are indistinguishable in the logic
 pure fn eq(a: bool, b: bool) -> bool { a == b }
 
-#[doc = "true if truth values `a` and `b` are distinguishable in the logic"]
+/// true if truth values `a` and `b` are distinguishable in the logic
 pure fn ne(a: bool, b: bool) -> bool { a != b }
 
-#[doc = "true if `v` represents truth in the logic"]
+/// true if `v` represents truth in the logic
 pure fn is_true(v: bool) -> bool { v }
 
-#[doc = "true if `v` represents falsehood in the logic"]
+/// true if `v` represents falsehood in the logic
 pure fn is_false(v: bool) -> bool { !v }
 
-#[doc = "Parse logic value from `s`"]
+/// Parse logic value from `s`
 pure fn from_str(s: str) -> option<bool> {
     alt check s {
       "true" { some(true) }
@@ -48,19 +46,19 @@ pure fn from_str(s: str) -> option<bool> {
     }
 }
 
-#[doc = "Convert `v` into a string"]
+/// Convert `v` into a string
 pure fn to_str(v: bool) -> str { if v { "true" } else { "false" } }
 
-#[doc = "
-Iterates over all truth values by passing them to `blk` in an unspecified
-order
-"]
+/**
+ * Iterates over all truth values by passing them to `blk` in an unspecified
+ * order
+ */
 fn all_values(blk: fn(v: bool)) {
     blk(true);
     blk(false);
 }
 
-#[doc = "converts truth value to an 8 bit byte"]
+/// converts truth value to an 8 bit byte
 pure fn to_bit(v: bool) -> u8 { if v { 1u8 } else { 0u8 } }
 
 #[test]

src/libcore/box.rs

@@ -1,9 +1,9 @@
-#[doc = "Operations on shared box types"];
+//! Operations on shared box types
 
 export ptr_eq;
 
 pure fn ptr_eq<T>(a: @T, b: @T) -> bool {
-    #[doc = "Determine if two shared boxes point to the same object"];
+    //! Determine if two shared boxes point to the same object
     unsafe { ptr::addr_of(*a) == ptr::addr_of(*b) }
 }
 

src/libcore/char.rs

@@ -1,4 +1,4 @@
-#[doc = "Utilities for manipulating the char type"];
+//! Utilities for manipulating the char type
 
 /*
     Lu  Uppercase_Letter    an uppercase letter
@@ -46,72 +46,72 @@ import is_XID_start = unicode::derived_property::XID_Start;
 import is_XID_continue = unicode::derived_property::XID_Continue;
 
 
-#[doc = "
-Indicates whether a character is in lower case, defined
-in terms of the Unicode General Category 'Ll'
-"]
+/**
+ * Indicates whether a character is in lower case, defined
+ * in terms of the Unicode General Category 'Ll'
+ */
 pure fn is_lowercase(c: char) -> bool {
     ret unicode::general_category::Ll(c);
 }
 
-#[doc = "
-Indicates whether a character is in upper case, defined
-in terms of the Unicode General Category 'Lu'.
-"]
+/**
+ * Indicates whether a character is in upper case, defined
+ * in terms of the Unicode General Category 'Lu'.
+ */
 pure fn is_uppercase(c: char) -> bool {
     ret unicode::general_category::Lu(c);
 }
 
-#[doc = "
-Indicates whether a character is whitespace, defined in
-terms of the Unicode General Categories 'Zs', 'Zl', 'Zp'
-additional 'Cc'-category control codes in the range [0x09, 0x0d]/~
-"]
+/**
+ * Indicates whether a character is whitespace, defined in
+ * terms of the Unicode General Categories 'Zs', 'Zl', 'Zp'
+ * additional 'Cc'-category control codes in the range [0x09, 0x0d]
+ */
 pure fn is_whitespace(c: char) -> bool {
     ret ('\x09' <= c && c <= '\x0d')
         || unicode::general_category::Zs(c)
         || unicode::general_category::Zl(c)
         || unicode::general_category::Zp(c);
 }
 
-#[doc = "
-Indicates whether a character is alphanumeric, defined
-in terms of the Unicode General Categories 'Nd',
-'Nl', 'No' and the Derived Core Property 'Alphabetic'.
-"]
+/**
+ * Indicates whether a character is alphanumeric, defined
+ * in terms of the Unicode General Categories 'Nd',
+ * 'Nl', 'No' and the Derived Core Property 'Alphabetic'.
+ */
 pure fn is_alphanumeric(c: char) -> bool {
     ret unicode::derived_property::Alphabetic(c) ||
         unicode::general_category::Nd(c) ||
         unicode::general_category::Nl(c) ||
         unicode::general_category::No(c);
 }
 
-#[doc = "Indicates whether the character is an ASCII character"]
+/// Indicates whether the character is an ASCII character
 pure fn is_ascii(c: char) -> bool {
    c - ('\x7F' & c) == '\x00'
 }
 
-#[doc = "Indicates whether the character is numeric (Nd, Nl, or No)"]
+/// Indicates whether the character is numeric (Nd, Nl, or No)
 pure fn is_digit(c: char) -> bool {
     ret unicode::general_category::Nd(c) ||
         unicode::general_category::Nl(c) ||
         unicode::general_category::No(c);
 }
 
-#[doc = "
-Convert a char to the corresponding digit.
-
-# Safety note
-
-This function fails if `c` is not a valid char
-
-# Return value
-
-If `c` is between '0' and '9', the corresponding value
-between 0 and 9. If `c` is 'a' or 'A', 10. If `c` is
-'b' or 'B', 11, etc. Returns none if the char does not
-refer to a digit in the given radix.
-"]
+/**
+ * Convert a char to the corresponding digit.
+ *
+ * # Safety note
+ *
+ * This function fails if `c` is not a valid char
+ *
+ * # Return value
+ *
+ * If `c` is between '0' and '9', the corresponding value
+ * between 0 and 9. If `c` is 'a' or 'A', 10. If `c` is
+ * 'b' or 'B', 11, etc. Returns none if the char does not
+ * refer to a digit in the given radix.
+ */
 pure fn to_digit(c: char, radix: uint) -> option<uint> {
     let val = alt c {
       '0' to '9' { c as uint - ('0' as uint) }
@@ -123,15 +123,15 @@ pure fn to_digit(c: char, radix: uint) -> option<uint> {
     else { none }
 }
 
-#[doc = "
-Return the hexadecimal unicode escape of a char.
-
-The rules are as follows:
-
-  - chars in [0,0xff]/~ get 2-digit escapes: `\\xNN`
-  - chars in [0x100,0xffff]/~ get 4-digit escapes: `\\uNNNN`
-  - chars above 0x10000 get 8-digit escapes: `\\UNNNNNNNN`
-"]
+/**
+ * Return the hexadecimal unicode escape of a char.
+ *
+ * The rules are as follows:
+ *
+ *   - chars in [0,0xff] get 2-digit escapes: `\\xNN`
+ *   - chars in [0x100,0xffff] get 4-digit escapes: `\\uNNNN`
+ *   - chars above 0x10000 get 8-digit escapes: `\\UNNNNNNNN`
+ */
 fn escape_unicode(c: char) -> str {
     let s = u32::to_str(c as u32, 16u);
     let (c, pad) = (if c <= '\xff' { ('x', 2u) }
@@ -145,18 +145,18 @@ fn escape_unicode(c: char) -> str {
     ret out;
 }
 
-#[doc = "
-Return a 'default' ASCII and C++11-like char-literal escape of a char.
-
-The default is chosen with a bias toward producing literals that are
-legal in a variety of languages, including C++11 and similar C-family
-languages. The exact rules are:
-
-  - Tab, CR and LF are escaped as '\t', '\r' and '\n' respectively.
-  - Single-quote, double-quote and backslash chars are backslash-escaped.
-  - Any other chars in the range [0x20,0x7e]/~ are not escaped.
-  - Any other chars are given hex unicode escapes; see `escape_unicode`.
-"]
+/**
+ * Return a 'default' ASCII and C++11-like char-literal escape of a char.
+ *
+ * The default is chosen with a bias toward producing literals that are
+ * legal in a variety of languages, including C++11 and similar C-family
+ * languages. The exact rules are:
+ *
+ *   - Tab, CR and LF are escaped as '\t', '\r' and '\n' respectively.
+ *   - Single-quote, double-quote and backslash chars are backslash-escaped.
+ *   - Any other chars in the range [0x20,0x7e] are not escaped.
+ *   - Any other chars are given hex unicode escapes; see `escape_unicode`.
+ */
 fn escape_default(c: char) -> str {
     alt c {
       '\t' { "\\t" }
@@ -170,13 +170,13 @@ fn escape_default(c: char) -> str {
     }
 }
 
-#[doc = "
-Compare two chars
-
-# Return value
-
--1 if a < b, 0 if a == b, +1 if a > b
-"]
+/**
+ * Compare two chars
+ *
+ * # Return value
+ *
+ * -1 if a < b, 0 if a == b, +1 if a > b
+ */
 pure fn cmp(a: char, b: char) -> int {
     ret  if b > a { -1 }
     else if b < a { 1 }

src/libcore/cmp.rs

@@ -1,4 +1,4 @@
-#[doc="Interfaces used for comparison."]
+/// Interfaces used for comparison.
 
 iface ord {
     fn lt(&&other: self) -> bool;