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(a: @T, b: @T) -> bool { // FIXME: ptr::addr_of unsafe { diff --git a/src/libcore/char.rs b/src/libcore/char.rs index 5475e695a79..2c46c652cd0 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 { 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 { } /* - 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 ab -*/ +#[doc( + brief = "Compare two chars.", + return = "-1 if ab" +)] 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..f9e95edf5e2 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) { -> 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) { \ + 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 { chan_t(task::task, port_id); } @@ -92,27 +81,21 @@ resource port_ptr(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 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 s." +)] tag port { port_t(@port_ptr); } -/* -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(ch: chan, -data: T) { let chan_t(t, p) = ch; let res = rustrt::chan_id_send(sys::get_type_desc::(), t, p, data); @@ -123,26 +106,23 @@ fn send(ch: chan, -data: T) { task::yield(); } -/* -Function: port - -Constructs a port. -*/ +#[doc( + brief = "Constructs a port." +)] fn port() -> port { port_t(@port_ptr(rustrt::new_port(sys::size_of::()))) } -/* -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(p: port) -> T { recv_(***p) } -// Receive on a raw port pointer +#[doc( + brief = "Receive on a raw port pointer" +)] fn recv_(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_(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(p: port) -> chan { chan_t(task::get_task(), rustrt::get_port_id(***p)) } diff --git a/src/libcore/ctypes.rs b/src/libcore/ctypes.rs index 478e8741631..38ca8ac2a0c 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;