convert comments to rustdocs for box, char, comm and cytpes.rs

4 files changed, 165 insertions, 267 deletions

diff --git a/src/libcore/box.rs b/src/libcore/box.rs
index 23b5889bc6a..fefc129c8b0 100644
--- a/src/libcore/box.rs
+++ b/src/libcore/box.rs
@@ -1,15 +1,8 @@
-/*
-Module: box
-*/
-
-
 export ptr_eq;
 
-/*
-Function: ptr_eq
-
-Determine if two shared boxes point to the same object
-*/
+#[doc(
+  brief = "Determine if two shared boxes point to the same object"
+)]
 pure fn ptr_eq<T>(a: @T, b: @T) -> bool {
     // FIXME: ptr::addr_of
     unsafe {
diff --git a/src/libcore/char.rs b/src/libcore/char.rs
index 5475e695a79..39dad5c8b1c 100644
--- a/src/libcore/char.rs
+++ b/src/libcore/char.rs
@@ -1,8 +1,4 @@
-/*
-Module: char
-
-Utilities for manipulating the char type
-*/
+#[doc = "Utilities for manipulating the char type"];
 
 /*
     Lu  Uppercase_Letter    an uppercase letter
@@ -47,34 +43,28 @@ import is_alphabetic = unicode::derived_property::Alphabetic;
 import is_XID_start = unicode::derived_property::XID_Start;
 import is_XID_continue = unicode::derived_property::XID_Continue;
 
-/*
-Function: is_lowercase
 
-Indicates whether a character is in lower case, defined in terms of the
-Unicode General Category 'Ll'.
-*/
+#[doc(
+  brief = "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);
 }
 
-/*
-Function: is_uppercase
-
-Indicates whether a character is in upper case, defined in terms of the
-Unicode General Category 'Lu'.
-*/
+#[doc(
+  brief = "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);
 }
 
-/*
-Function: is_whitespace
-
-Indicates whether a character is whitespace, defined in terms of
-the Unicode General Categories 'Zs', 'Zl', 'Zp' and the additional
-'Cc'-category control codes in the range [0x09, 0x0d].
-
-*/
+#[doc(
+  brief = "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)
@@ -82,15 +72,11 @@ pure fn is_whitespace(c: char) -> bool {
         || unicode::general_category::Zp(c);
 }
 
-/*
-Function: is_alphanumeric
-
-Indicates whether a character is alphanumeric, defined in terms of
-the Unicode General Categories 'Nd', 'Nl', 'No' and the Derived
-Core Property 'Alphabetic'.
-
-*/
-
+#[doc(
+  brief = "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) ||
@@ -99,21 +85,13 @@ pure fn is_alphanumeric(c: char) -> bool {
 }
 
 
-/*
- Function: to_digit
-
- Convert a char to the corresponding digit.
-
- Parameters:
-   c - a char, either '0' to '9', 'a' to 'z' or 'A' to 'Z'
-
- Returns:
-   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.
-
- Safety note:
-   This function fails if `c` is not a valid char
-*/
+#[doc(
+  brief = "Convert a char to the corresponding digit.\
+           Safety note: This function fails if `c` is not a valid char",
+  return = "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."
+)]
 pure fn to_digit(c: char) -> u8 unsafe {
     alt maybe_digit(c) {
       option::some(x) { x }
@@ -121,12 +99,10 @@ pure fn to_digit(c: char) -> u8 unsafe {
     }
 }
 
-/*
- Function: maybe_digit
-
- Convert a char to the corresponding digit. Returns none when the
- character is not a valid hexadecimal digit.
-*/
+#[doc(
+  brief = "Convert a char to the corresponding digit. Returns none when\
+           character is not a valid hexadecimal digit."
+)]
 pure fn maybe_digit(c: char) -> option::t<u8> {
     alt c {
       '0' to '9' { option::some(c as u8 - ('0' as u8)) }
@@ -137,12 +113,11 @@ pure fn maybe_digit(c: char) -> option::t<u8> {
 }
 
 /*
- Function: to_lower
-
- Convert a char to the corresponding lower case.
-
  FIXME: works only on ASCII
 */
+#[doc(
+  brief = "Convert a char to the corresponding lower case."
+)]
 pure fn to_lower(c: char) -> char {
     alt c {
       'A' to 'Z' { ((c as u8) + 32u8) as char }
@@ -151,12 +126,11 @@ pure fn to_lower(c: char) -> char {
 }
 
 /*
- Function: to_upper
-
- Convert a char to the corresponding upper case.
-
  FIXME: works only on ASCII
 */
+#[doc(
+  brief = "Convert a char to the corresponding upper case."
+)]
 pure fn to_upper(c: char) -> char {
     alt c {
       'a' to 'z' { ((c as u8) - 32u8) as char }
@@ -164,18 +138,10 @@ pure fn to_upper(c: char) -> char {
     }
 }
 
-/*
- Function: cmp
-
- Compare two chars.
-
- Parameters:
-  a - a char
-  b - a char
-
- Returns:
-  -1 if a<b, 0 if a==b, +1 if a>b
-*/
+#[doc(
+  brief =  "Compare two chars.",
+  return = "-1 if a&lt;b, 0 if a==b, +1 if a>b"
+)]
 pure fn cmp(a: char, b: char) -> int {
     ret  if b > a { -1 }
     else if b < a { 1 }
diff --git a/src/libcore/comm.rs b/src/libcore/comm.rs
index be65197b48f..274b28b9680 100644
--- a/src/libcore/comm.rs
+++ b/src/libcore/comm.rs
@@ -1,28 +1,21 @@
-/*
-Module: comm
-
-Communication between tasks
-
-Communication between tasks is facilitated by ports (in the receiving task),
-and channels (in the sending task). Any number of channels may feed into a
-single port.
-
-Ports and channels may only transmit values of unique types; that is,
-values that are statically guaranteed to be accessed by a single
-'owner' at a time.  Unique types include scalars, vectors, strings,
-and records, tags, tuples and unique boxes (~T) thereof. Most notably,
-shared boxes (@T) may not be transmitted across channels.
-
-Example:
-
-> let p = comm::port();
-> task::spawn(comm::chan(p), fn (c: chan<str>) {
->   comm::send(c, "Hello, World");
-> });
->
-> io::println(comm::recv(p));
-
-*/
+#[doc(
+  brief = "Communication between tasks",
+  desc  = "Communication between tasks is facilitated by ports (in the\
+           receiving task), and channels (in the sending task). Any\
+           number of channels may feed into a single port.\
+           Ports and channels may only transmit values of unique\
+           types; that is, values that are statically guaranteed to\
+           be accessed by a single 'owner' at a time.  Unique types\
+           include scalars, vectors, strings, and records, tags,\
+           tuples and unique boxes (~T) thereof. Most notably,\
+           shared boxes (@T) may not be transmitted across channels.\
+           Example:\
+               let p = comm::port();\
+               task::spawn(comm::chan(p), fn (c: chan<str>) {\
+                   comm::send(c, \"Hello, World\");\
+               });\
+               io::println(comm::recv(p));"
+)];
 
 import sys;
 import task;
@@ -59,22 +52,18 @@ type port_id = int;
 
 // It's critical that this only have one variant, so it has a record
 // layout, and will work in the rust_task structure in task.rs.
-/*
-Type: chan
-
-A communication endpoint that can send messages. Channels send
-messages to ports.
-
-Each channel is bound to a port when the channel is constructed, so
-the destination port for a channel must exist before the channel
-itself.
-
-Channels are weak: a channel does not keep the port it is bound to alive.
-If a channel attempts to send data to a dead port that data will be silently
-dropped.
-
-Channels may be duplicated and themselves transmitted over other channels.
-*/
+#[doc(
+  brief = "A communication endpoint that can send messages.\
+           Channels send messages to ports.",
+  desc = "Each channel is bound to a port when the channel is\
+          constructed, so the destination port for a channel\
+          must exist before the channel itself.\
+          Channels are weak: a channel does not keep the port it\
+          is bound to alive. If a channel attempts to send data\
+          to a dead port that data will be silently dropped.\
+          Channels may be duplicated and themselves transmitted\
+          over other channels."
+)]
 tag chan<T: send> {
     chan_t(task::task, port_id);
 }
@@ -92,27 +81,21 @@ resource port_ptr<T: send>(po: *rustrt::rust_port) {
     rustrt::del_port(po);
 }
 
-/*
-Type: port
-
-A communication endpoint that can receive messages. Ports receive
-messages from channels.
-
-Each port has a unique per-task identity and may not be replicated or
-transmitted. If a port value is copied, both copies refer to the same port.
-
-Ports may be associated with multiple <chan>s.
-*/
+#[doc(
+  brief = "A communication endpoint that can receive messages.\
+           Ports receive messages from channels.",
+  desc = "Each port has a unique per-task identity and may not\
+          be replicated or transmitted. If a port value is\
+          copied, both copies refer to the same port.\
+          Ports may be associated with multiple &lt;chan>s."
+)]
 tag port<T: send> { port_t(@port_ptr<T>); }
 
-/*
-Function: send
-
-Sends data over a channel.
-
-The sent data is moved into the channel, whereupon the caller loses access
-to it.
-*/
+#[doc(
+  brief = "Sends data over a channel. The sent data is moved\
+           into the channel, whereupon the caller loses\
+           access to it."
+)]
 fn send<T: send>(ch: chan<T>, -data: T) {
     let chan_t(t, p) = ch;
     let res = rustrt::chan_id_send(sys::get_type_desc::<T>(), t, p, data);
@@ -123,26 +106,23 @@ fn send<T: send>(ch: chan<T>, -data: T) {
     task::yield();
 }
 
-/*
-Function: port
-
-Constructs a port.
-*/
+#[doc(
+  brief = "Constructs a port."
+)]
 fn port<T: send>() -> port<T> {
     port_t(@port_ptr(rustrt::new_port(sys::size_of::<T>())))
 }
 
-/*
-Function: recv
-
-Receive from a port.
-
-If no data is available on the port then the task will block until data
-becomes available.
-*/
+#[doc(
+  brief = "Receive from a port.\
+           If no data is available on the port then the task will\
+           block until data becomes available."
+)]
 fn recv<T: send>(p: port<T>) -> T { recv_(***p) }
 
-// Receive on a raw port pointer
+#[doc(
+  brief = "Receive on a raw port pointer"
+)]
 fn recv_<T: send>(p: *rustrt::rust_port) -> T {
     // FIXME: Due to issue 1185 we can't use a return pointer when
     // calling C code, and since we can't create our own return
@@ -169,13 +149,10 @@ fn recv_<T: send>(p: *rustrt::rust_port) -> T {
     ret res;
 }
 
-/*
-Function: chan
-
-Constructs a channel.
-
-The channel is bound to the port used to construct it.
-*/
+#[doc(
+  brief = "Constructs a channel. The channel is bound to the\
+           port used to construct it."
+)]
 fn chan<T: send>(p: port<T>) -> chan<T> {
     chan_t(task::get_task(), rustrt::get_port_id(***p))
 }
diff --git a/src/libcore/ctypes.rs b/src/libcore/ctypes.rs
index 478e8741631..ab8e250ac56 100644
--- a/src/libcore/ctypes.rs
+++ b/src/libcore/ctypes.rs
@@ -1,8 +1,4 @@
-/*
-Module: ctypes
-
-Definitions useful for C interop
-*/
+#[doc = "Definitions useful for C interop"];
 
 /*
 FIXME: Add a test that uses some native code to verify these sizes,
@@ -20,81 +16,62 @@ export enum;
 
 // PORT adapt to architecture
 
-/*
-Type: c_int
-
-A signed integer with the same size as a C `int`
-*/
+#[doc(
+  brief = "A signed integer with the same size as a C `int`."
+)]
 type c_int = i32;
 
-/*
-Type: c_uint
-
-An unsigned integer with the same size as a C `unsigned int`
-*/
+#[doc(
+  brief = "An unsigned integer with the same size as a C `unsigned int`."
+)]
 type c_uint = u32;
 
-/*
-Type: long
-
-A signed integer with the same size as a C `long`
-*/
+#[doc(
+  brief = "A signed integer with the same size as a C `long`."
+)]
 type long = int;
 
-/*
-Type: longlong
-
-A signed integer with the same size as a C `long long`
-*/
+#[doc(
+  brief = "A signed integer with the same size as a C `long long`."
+)]
 type longlong = i64;
 
-/*
-Type: unsigned
-
-An unsigned integer with the same size as a C `unsigned int`
-*/
+#[doc(
+  brief = "A signed integer with the same size as a C `unsigned int`."
+)]
 type unsigned = u32;
 
-/*
-Type: ulong
-
-An unsigned integer with the same size as a C `unsigned long`
-*/
+#[doc(
+  brief = "A signed integer with the same size as a C `unsigned long`."
+)]
 type ulong = uint;
 
-/*
-Type: ulonglong
-
-An unsigned integer with the same size as a C `unsigned long long`
-*/
+#[doc(
+  brief = "A signed integer with the same size as a C `unsigned long long`."
+)]
 type ulonglong = u64;
 
-/*
-Type: intptr_t
-
-A signed integer with the same size as a pointer. This is
-guaranteed to always be the same type as a Rust `int`
-*/
+#[doc(
+  brief = "A signed integer with the same size as a pointer.\
+           This is guaranteed to always be the same type as a\
+            Rust `int`."
+)]
 type intptr_t = uint; // FIXME: int
 
-/*
-Type: uintptr_t
-
-An unsigned integer with the same size as a pointer. This is
-guaranteed to always be the same type as a Rust `uint`.
-*/
+#[doc(
+  brief = "An unsigned integer with the same size as a pointer.\
+           This is guaranteed to always be the same type as a Rust\
+           `uint`."
+)]
 type uintptr_t = uint;
 type uint32_t = u32;
 
-/*
-Type: void
-
-A type, a pointer to which can be used as C `void *`.
-
-The void type cannot be constructed or destructured, but using
-pointers to this type when interoperating with C void pointers can
-help in documentation.
-*/
+#[doc(
+  brief = "A type, a pointer to which can be used as C `void *`.",
+  desc = "The void type cannot be constructed or destructured,\
+         but using pointers to this type when interoperating\
+         with C void pointers can help in documentation."
+)]
 tag void {
     // Making the only variant reference itself makes it impossible to
     // construct. Not exporting it makes it impossible to destructure.
@@ -103,60 +80,45 @@ tag void {
     void_private2(@void);
 }
 
-/*
-Type: c_float
-
-A float value with the same size as a C `float`
-*/
+#[doc(
+  brief = "A float value with the same size as a C `float`."
+)]
 type c_float = f32;
 
-/*
-Type: c_float
-
-A float value with the same size as a C `double`
-*/
+#[doc(
+  brief = "A float value with the same size as a C `double`."
+)]
 type c_double = f64;
 
-/*
-Type: size_t
-
-An unsigned integer corresponding to the C `size_t`
-*/
+#[doc(
+  brief = "An unsigned integer corresponding to the C `size_t`."
+)]
 type size_t = uint;
 
-/*
-Type: ssize_t
-
-A signed integer correpsonding to the C `ssize_t`
-*/
+#[doc(
+  brief = "A signed integer corresponding to the C `ssize_t`."
+)]
 type ssize_t = int;
 
-/*
-Type: off_t
-
-An unsigned integer corresponding to the C `off_t`
-*/
+#[doc(
+  brief = "An unsigned integer corresponding to the C `off_t`."
+)]
 type off_t = uint;
 
-/*
-Type: fd_t
-
-A type that can be used for C file descriptors
-*/
+#[doc(
+  brief = "A type that can be used for C file descriptors."
+)]
 type fd_t = i32;      // not actually a C type, but should be.
 
-/*
-Type: pid_t
-
-A type for representing process ID's, corresponding to C `pid_t`
-*/
+#[doc(
+  brief = "A type for representing process ID's, corresponding to C `pid_t`."
+)]
 type pid_t = i32;
 
-// enum is implementation-defined, but is 32-bits in practice
-/*
-Type: enum
-
-An unsigned integer with the same size as a C enum
-*/
+#[doc(
+  brief = "An unsigned integer with the same size as a C enum.\
+           enum is implementation-defined, but is 32-bits in\
+           practice"
+)]
 type enum = u32;