Merge pull request #1554 from rtanglao/master

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

src/libcore/box.rs

@@ -1,15 +1,8 @@
-/*
-Module: box
-*/
-
-
 export ptr_eq;
 
-/*
+#[doc(
-Function: ptr_eq
+  brief = "Determine if two shared boxes point to the same object"
-
+)]
-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 @@
-/*
+#[doc = "Utilities for manipulating the char type"];
-Module: char
-
-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
+#[doc(
-Unicode General Category 'Ll'.
+  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);
 }
 
-/*
+#[doc(
-Function: is_uppercase
+  brief = "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(
-Function: is_whitespace
+  brief = "Indicates whether a character is whitespace, defined in \
-
+           terms of the Unicode General Categories 'Zs', 'Zl', 'Zp' \
-Indicates whether a character is whitespace, defined in terms of
+           additional 'Cc'-category control codes in the range [0x09, 0x0d]"
-the Unicode General Categories 'Zs', 'Zl', 'Zp' and the 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);
 }
 
-/*
+#[doc(
-Function: is_alphanumeric
+  brief = "Indicates whether a character is alphanumeric, defined \
-
+            in terms of the Unicode General Categories 'Nd', \
-Indicates whether a character is alphanumeric, defined in terms of
+            'Nl', 'No' and the Derived Core Property 'Alphabetic'."
-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 {
 }
 
 
-/*
+#[doc(
- Function: to_digit
+  brief = "Convert a char to the corresponding digit. \
-
+           Safety note: This function fails if `c` is not a valid char",
- Convert a char to the corresponding digit.
+  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 \
- Parameters:
+            'b' or 'B', 11, etc."
-   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
-*/
 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 {
     }
 }
 
-/*
+#[doc(
- Function: maybe_digit
+  brief = "Convert a char to the corresponding digit. Returns none when \
-
+           character is not a valid hexadecimal digit."
- Convert a char to the corresponding digit. Returns none when the
+)]
- 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 {
     }
 }
 
-/*
+#[doc(
- Function: cmp
+  brief =  "Compare two chars.",
-
+  return = "-1 if a<b, 0 if a==b, +1 if a>b"
- Compare two chars.
+)]
-
- Parameters:
-  a - a char
-  b - a char
-
- Returns:
-  -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 @@
-/*
+#[doc(
-Module: comm
+  brief = "Communication between tasks",
-
+  desc  = "Communication between tasks is facilitated by ports (in the \
-Communication between tasks
+           receiving task), and channels (in the sending task). Any \
-
+           number of channels may feed into a single port. \
-Communication between tasks is facilitated by ports (in the receiving task),
+           Ports and channels may only transmit values of unique \
-and channels (in the sending task). Any number of channels may feed into a
+           types; that is, values that are statically guaranteed to \
-single port.
+           be accessed by a single 'owner' at a time.  Unique types \
-
+           include scalars, vectors, strings, and records, tags, \
-Ports and channels may only transmit values of unique types; that is,
+           tuples and unique boxes (~T) thereof. Most notably, \
-values that are statically guaranteed to be accessed by a single
+           shared boxes (@T) may not be transmitted across channels. \
-'owner' at a time.  Unique types include scalars, vectors, strings,
+           Example: \
-and records, tags, tuples and unique boxes (~T) thereof. Most notably,
+               let p = comm::port(); \
-shared boxes (@T) may not be transmitted across channels.
+               task::spawn(comm::chan(p), fn (c: chan<str>) { \
-
+                   comm::send(c, \"Hello, World\"); \
-Example:
+               }); \
-
+               io::println(comm::recv(p));"
-> 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.
-/*
+#[doc(
-Type: chan
+  brief = "A communication endpoint that can send messages. \
-
+           Channels send messages to ports.",
-A communication endpoint that can send messages. Channels send
+  desc = "Each channel is bound to a port when the channel is \
-messages to ports.
+          constructed, so the destination port for a channel \
-
+          must exist before the channel itself. \
-Each channel is bound to a port when the channel is constructed, so
+          Channels are weak: a channel does not keep the port it \
-the destination port for a channel must exist before the channel
+          is bound to alive. If a channel attempts to send data \
-itself.
+          to a dead port that data will be silently dropped. \
-
+          Channels may be duplicated and themselves transmitted \
-Channels are weak: a channel does not keep the port it is bound to alive.
+          over other channels."
-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);
 }
 
-/*
+#[doc(
-Type: port
+  brief = "A communication endpoint that can receive messages. \
-
+           Ports receive messages from channels.",
-A communication endpoint that can receive messages. Ports receive
+  desc = "Each port has a unique per-task identity and may not \
-messages from channels.
+          be replicated or transmitted. If a port value is \
-
+          copied, both copies refer to the same port. \
-Each port has a unique per-task identity and may not be replicated or
+          Ports may be associated with multiple <chan>s."
-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>); }
 
-/*
+#[doc(
-Function: send
+  brief = "Sends data over a channel. The sent data is moved \
-
+           into the channel, whereupon the caller loses \
-Sends data over a channel.
+           access to it."
-
+)]
-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();
 }
 
-/*
+#[doc(
-Function: port
+  brief = "Constructs a port."
-
+)]
-Constructs a port.
-*/
 fn port<T: send>() -> port<T> {
     port_t(@port_ptr(rustrt::new_port(sys::size_of::<T>())))
 }
 
-/*
+#[doc(
-Function: recv
+  brief = "Receive from a port. \
-
+           If no data is available on the port then the task will \
-Receive from a port.
+           block until data becomes available."
-
+)]
-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;
 }
 
-/*
+#[doc(
-Function: chan
+  brief = "Constructs a channel. The channel is bound to the \
-
+           port used to construct it."
-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))
 }

src/libcore/ctypes.rs

@@ -1,8 +1,4 @@
-/*
+#[doc = "Definitions useful for C interop"];
-Module: ctypes
-
-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
 
-/*
+#[doc(
-Type: c_int
+  brief = "A signed integer with the same size as a C `int`."
-
+)]
-A signed integer with the same size as a C `int`
-*/
 type c_int = i32;
 
-/*
+#[doc(
-Type: c_uint
+  brief = "An unsigned integer with the same size as a C `unsigned int`."
-
+)]
-An unsigned integer with the same size as a C `unsigned int`
-*/
 type c_uint = u32;
 
-/*
+#[doc(
-Type: long
+  brief = "A signed integer with the same size as a C `long`."
-
+)]
-A signed integer with the same size as a C `long`
-*/
 type long = int;
 
-/*
+#[doc(
-Type: longlong
+  brief = "A signed integer with the same size as a C `long long`."
-
+)]
-A signed integer with the same size as a C `long long`
-*/
 type longlong = i64;
 
-/*
+#[doc(
-Type: unsigned
+  brief = "A signed integer with the same size as a C `unsigned int`."
-
+)]
-An unsigned integer with the same size as a C `unsigned int`
-*/
 type unsigned = u32;
 
-/*
+#[doc(
-Type: ulong
+  brief = "A signed integer with the same size as a C `unsigned long`."
-
+)]
-An unsigned integer with the same size as a C `unsigned long`
-*/
 type ulong = uint;
 
-/*
+#[doc(
-Type: ulonglong
+  brief = "A signed integer with the same size as a C `unsigned long long`."
-
+)]
-An unsigned integer with the same size as a C `unsigned long long`
-*/
 type ulonglong = u64;
 
-/*
+#[doc(
-Type: intptr_t
+  brief = "A signed integer with the same size as a pointer. \
-
+           This is guaranteed to always be the same type as a \
-A signed integer with the same size as a pointer. This is
+            Rust `int`."
-guaranteed to always be the same type as a Rust `int`
+)]
-*/
 type intptr_t = uint; // FIXME: int
 
-/*
+#[doc(
-Type: uintptr_t
+  brief = "An unsigned integer with the same size as a pointer. \
-
+           This is guaranteed to always be the same type as a Rust \
-An unsigned integer with the same size as a pointer. This is
+           `uint`."
-guaranteed to always be the same type as a Rust `uint`.
+)]
-*/
 type uintptr_t = uint;
 type uint32_t = u32;
 
-/*
+#[doc(
-Type: void
+  brief = "A type, a pointer to which can be used as C `void *`.",
-
+  desc = "The void type cannot be constructed or destructured, \
-A type, a pointer to which can be used as C `void *`.
+         but using pointers to this type when interoperating \
-
+         with C void pointers can help in documentation."
-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);
 }
 
-/*
+#[doc(
-Type: c_float
+  brief = "A float value with the same size as a C `float`."
-
+)]
-A float value with the same size as a C `float`
-*/
 type c_float = f32;
 
-/*
+#[doc(
-Type: c_float
+  brief = "A float value with the same size as a C `double`."
-
+)]
-A float value with the same size as a C `double`
-*/
 type c_double = f64;
 
-/*
+#[doc(
-Type: size_t
+  brief = "An unsigned integer corresponding to the C `size_t`."
-
+)]
-An unsigned integer corresponding to the C `size_t`
-*/
 type size_t = uint;
 
-/*
+#[doc(
-Type: ssize_t
+  brief = "A signed integer corresponding to the C `ssize_t`."
-
+)]
-A signed integer correpsonding to the C `ssize_t`
-*/
 type ssize_t = int;
 
-/*
+#[doc(
-Type: off_t
+  brief = "An unsigned integer corresponding to the C `off_t`."
-
+)]
-An unsigned integer corresponding to the C `off_t`
-*/
 type off_t = uint;
 
-/*
+#[doc(
-Type: fd_t
+  brief = "A type that can be used for C file descriptors."
-
+)]
-A type that can be used for C file descriptors
-*/
 type fd_t = i32;      // not actually a C type, but should be.
 
-/*
+#[doc(
-Type: pid_t
+  brief = "A type for representing process ID's, corresponding to C `pid_t`."
-
+)]
-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
+#[doc(
-/*
+  brief = "An unsigned integer with the same size as a C enum. \
-Type: enum
+           enum is implementation-defined, but is 32-bits in \
-
+           practice"
-An unsigned integer with the same size as a C enum
+)]
-*/
 type enum = u32;