rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Roland Tanglao
2012-01-16 18:34:03 -08:00
parent 293678847b
commit ca55a4b421
4 changed files with 165 additions and 267 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
src/libcore/box.rs
View File

@@ -1,15 +1,8 @@
/*
Module: box
*/
export ptr_eq; 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 { pure fn ptr_eq<T>(a: @T, b: @T) -> bool {
// FIXME: ptr::addr_of // FIXME: ptr::addr_of
unsafe { unsafe {

114
src/libcore/char.rs
View File

@@ -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 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_start = unicode::derived_property::XID_Start;
import is_XID_continue = unicode::derived_property::XID_Continue; 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 { pure fn is_lowercase(c: char) -> bool {
ret unicode::general_category::Ll(c); 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 { pure fn is_uppercase(c: char) -> bool {
ret unicode::general_category::Lu(c); 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 { pure fn is_whitespace(c: char) -> bool {
ret ('\x09' <= c && c <= '\x0d') ret ('\x09' <= c && c <= '\x0d')
|| unicode::general_category::Zs(c) || unicode::general_category::Zs(c)
@@ -82,15 +72,11 @@ pure fn is_whitespace(c: char) -> bool {
|| unicode::general_category::Zp(c); || 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 { pure fn is_alphanumeric(c: char) -> bool {
ret unicode::derived_property::Alphabetic(c) || ret unicode::derived_property::Alphabetic(c) ||
unicode::general_category::Nd(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 { pure fn to_digit(c: char) -> u8 unsafe {
alt maybe_digit(c) { alt maybe_digit(c) {
option::some(x) { x } 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> { pure fn maybe_digit(c: char) -> option::t<u8> {
alt c { alt c {
'0' to '9' { option::some(c as u8 - ('0' as u8)) } '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 FIXME: works only on ASCII
*/ */
#[doc(
brief = "Convert a char to the corresponding lower case."
)]
pure fn to_lower(c: char) -> char { pure fn to_lower(c: char) -> char {
alt c { alt c {
'A' to 'Z' { ((c as u8) + 32u8) as char } '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 FIXME: works only on ASCII
*/ */
#[doc(
brief = "Convert a char to the corresponding upper case."
)]
pure fn to_upper(c: char) -> char { pure fn to_upper(c: char) -> char {
alt c { alt c {
'a' to 'z' { ((c as u8) - 32u8) as char } '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&lt;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 { pure fn cmp(a: char, b: char) -> int {
ret if b > a { -1 } ret if b > a { -1 }
else if b < a { 1 } else if b < a { 1 }

139
src/libcore/comm.rs
View File

@@ -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 sys;
import task; import task;
@@ -59,22 +52,18 @@ type port_id = int;
// It's critical that this only have one variant, so it has a record // 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. // 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> { tag chan<T: send> {
chan_t(task::task, port_id); chan_t(task::task, port_id);
} }
@@ -92,27 +81,21 @@ resource port_ptr<T: send>(po: *rustrt::rust_port) {
rustrt::del_port(po); 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 &lt;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>); } 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) { fn send<T: send>(ch: chan<T>, -data: T) {
let chan_t(t, p) = ch; let chan_t(t, p) = ch;
let res = rustrt::chan_id_send(sys::get_type_desc::<T>(), t, p, data); 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(); task::yield();
} }
/* #[doc(
Function: port brief = "Constructs a port."
)]
Constructs a port.
*/
fn port<T: send>() -> port<T> { fn port<T: send>() -> port<T> {
port_t(@port_ptr(rustrt::new_port(sys::size_of::<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) } 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 { fn recv_<T: send>(p: *rustrt::rust_port) -> T {
// FIXME: Due to issue 1185 we can't use a return pointer when // 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 // 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; 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> { fn chan<T: send>(p: port<T>) -> chan<T> {
chan_t(task::get_task(), rustrt::get_port_id(***p)) chan_t(task::get_task(), rustrt::get_port_id(***p))
} }

166
src/libcore/ctypes.rs
View File

@@ -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, FIXME: Add a test that uses some native code to verify these sizes,
@@ -20,81 +16,62 @@ export enum;
// PORT adapt to architecture // 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; 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; 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; 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; 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; 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; 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; 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 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 uintptr_t = uint;
type uint32_t = u32; 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 { tag void {
// Making the only variant reference itself makes it impossible to // Making the only variant reference itself makes it impossible to
// construct. Not exporting it makes it impossible to destructure. // construct. Not exporting it makes it impossible to destructure.
@@ -103,60 +80,45 @@ tag void {
void_private2(@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; 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; 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; 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; 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; 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. 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; 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; type enum = u32;