Merge pull request #1554 from rtanglao/master

rustdocs for box.rs, comm.rs, ctypes.rs, char.rs

Author: graydon

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 {

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,50 +43,40 @@ 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)
         || unicode::general_category::Zl(c)
         || 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,34 +85,24 @@ 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 }
       option::none. { fail; }
     }
 }
 
-/*
- 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,31 +126,22 @@ 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 }
       _ { c }
     }
 }
 
-/*
- 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<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/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 <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))
 }