From 95521c408438efc5794e83953086c812b795c756 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Wed, 7 Mar 2012 18:17:30 -0800 Subject: [PATCH] std: Convert to rustdoc --- src/libstd/bitv.rs | 174 +++------ src/libstd/c_vec.rs | 79 ++-- src/libstd/dbg.rs | 10 +- src/libstd/deque.rs | 26 +- src/libstd/four.rs | 176 +++------ src/libstd/fun_treemap.rs | 41 +-- src/libstd/getopts.rs | 181 ++++------ src/libstd/json.rs | 45 +-- src/libstd/list.rs | 95 ++--- src/libstd/map.rs | 126 ++----- src/libstd/net.rs | 34 +- src/libstd/rand.rs | 46 +-- src/libstd/rope.rs | 696 ++++++++++++++++-------------------- src/libstd/run_program.rs | 130 +++---- src/libstd/serialization.rs | 6 +- src/libstd/sha1.rs | 62 +--- src/libstd/smallintmap.rs | 53 +-- src/libstd/sort.rs | 29 +- src/libstd/std.rc | 2 + src/libstd/tempfile.rs | 9 +- src/libstd/term.rs | 48 +-- src/libstd/test.rs | 2 + src/libstd/time.rs | 28 +- src/libstd/treemap.rs | 41 +-- src/libstd/tri.rs | 123 ++----- src/libstd/util.rs | 19 +- 26 files changed, 712 insertions(+), 1569 deletions(-) diff --git a/src/libstd/bitv.rs b/src/libstd/bitv.rs index eb9d21ac31e..01bbc1588bb 100644 --- a/src/libstd/bitv.rs +++ b/src/libstd/bitv.rs @@ -1,9 +1,3 @@ -/* -Module: bitv - -Bitvectors. -*/ - export t; export create; export union; @@ -28,25 +22,19 @@ export eq_vec; // an optimizing version of this module that produces a different obj // for the case where nbits <= 32. -/* -Type: t - -The bitvector type. -*/ +#[doc = "The bitvector type"] type t = @{storage: [mutable uint], nbits: uint}; - const uint_bits: uint = 32u + (1u << 32u >> 27u); -/* -Function: create +#[doc = " +Constructs a bitvector -Constructs a bitvector. +# Arguments -Parameters: -nbits - The number of bits in the bitvector -init - If true then the bits are initialized to 1, otherwise 0 -*/ +* nbits - The number of bits in the bitvector +* init - If true then the bits are initialized to 1, otherwise 0 +"] fn create(nbits: uint, init: bool) -> t { let elt = if init { !0u } else { 0u }; let storage = vec::to_mut(vec::init_elt(nbits / uint_bits + 1u, elt)); @@ -74,21 +62,12 @@ fn union(v0: t, v1: t) -> bool { let sub = lor; ret process(v0, v1, sub); } fn land(w0: uint, w1: uint) -> uint { ret w0 & w1; } -/* -Function: intersect - +#[doc = " Calculates the intersection of two bitvectors -Sets `v0` to the intersection of `v0` and `v1` - -Preconditions: - -Both bitvectors must be the same length - -Returns: - -True if `v0` was changed -*/ +Sets `v0` to the intersection of `v0` and `v1`. Both bitvectors must be the +same length. Returns 'true' if `v0` was changed. +"] fn intersect(v0: t, v1: t) -> bool { let sub = land; ret process(v0, v1, sub); @@ -96,26 +75,14 @@ fn intersect(v0: t, v1: t) -> bool { fn right(_w0: uint, w1: uint) -> uint { ret w1; } -/* -Function: assign - +#[doc = " Assigns the value of `v1` to `v0` -Preconditions: - -Both bitvectors must be the same length - -Returns: - -True if `v0` was changed -*/ +Both bitvectors must be the same length. Returns `true` if `v0` was changed +"] fn assign(v0: t, v1: t) -> bool { let sub = right; ret process(v0, v1, sub); } -/* -Function: clone - -Makes a copy of a bitvector -*/ +#[doc = "Makes a copy of a bitvector"] fn clone(v: t) -> t { let storage = vec::to_mut(vec::init_elt(v.nbits / uint_bits + 1u, 0u)); let len = vec::len(v.storage); @@ -123,11 +90,7 @@ fn clone(v: t) -> t { ret @{storage: storage, nbits: v.nbits}; } -/* -Function: get - -Retreive the value at index `i` -*/ +#[doc = "Retreive the value at index `i`"] pure fn get(v: t, i: uint) -> bool { assert (i < v.nbits); let bits = uint_bits; @@ -139,19 +102,12 @@ pure fn get(v: t, i: uint) -> bool { // FIXME: This doesn't account for the actual size of the vectors, // so it could end up comparing garbage bits -/* -Function: equal - +#[doc = " Compares two bitvectors -Preconditions: - -Both bitvectors must be the same length - -Returns: - -True if both bitvectors contain identical elements -*/ +Both bitvectors must be the same length. Returns `true` if both bitvectors +contain identical elements. +"] fn equal(v0: t, v1: t) -> bool { // FIXME: when we can break or return from inside an iterator loop, // we can eliminate this painful while-loop @@ -165,51 +121,31 @@ fn equal(v0: t, v1: t) -> bool { ret true; } -/* -Function: clear - -Set all bits to 0 -*/ +#[doc = "Set all bits to 0"] fn clear(v: t) { uint::range(0u, vec::len(v.storage)) {|i| v.storage[i] = 0u; }; } -/* -Function: set_all - -Set all bits to 1 -*/ +#[doc = "Set all bits to 1"] fn set_all(v: t) { uint::range(0u, v.nbits) {|i| set(v, i, true); }; } -/* -Function: invert - -Invert all bits -*/ +#[doc = "Invert all bits"] fn invert(v: t) { uint::range(0u, vec::len(v.storage)) {|i| v.storage[i] = !v.storage[i]; }; } -/* -Function: difference - +#[doc = " Calculate the difference between two bitvectors Sets each element of `v0` to the value of that element minus the element -of `v1` at the same index. +of `v1` at the same index. Both bitvectors must be the same length. -Preconditions: - -Both bitvectors must be the same length - -Returns: - -True if `v0` was changed -*/ +Returns `true` if `v0` was changed. +"] fn difference(v0: t, v1: t) -> bool { invert(v1); let b = intersect(v0, v1); @@ -217,15 +153,11 @@ fn difference(v0: t, v1: t) -> bool { ret b; } -/* -Function: set - +#[doc = " Set the value of a bit at a given index -Preconditions: - -`i` must be less than the length of the bitvector -*/ +`i` must be less than the length of the bitvector. +"] fn set(v: t, i: uint, x: bool) { assert (i < v.nbits); let bits = uint_bits; @@ -236,22 +168,14 @@ fn set(v: t, i: uint, x: bool) { } -/* -Function: is_true - -Returns true if all bits are 1 -*/ +#[doc = "Returns true if all bits are 1"] fn is_true(v: t) -> bool { for i: uint in to_vec(v) { if i != 1u { ret false; } } ret true; } -/* -Function: is_false - -Returns true if all bits are 0 -*/ +#[doc = "Returns true if all bits are 0"] fn is_false(v: t) -> bool { for i: uint in to_vec(v) { if i == 1u { ret false; } } ret true; @@ -259,39 +183,35 @@ fn is_false(v: t) -> bool { fn init_to_vec(v: t, i: uint) -> uint { ret if get(v, i) { 1u } else { 0u }; } -/* -Function: to_vec +#[doc = " +Converts the bitvector to a vector of uint with the same length. -Converts the bitvector to a vector of uint with the same length. Each uint -in the resulting vector has either value 0u or 1u. -*/ +Each uint in the resulting vector has either value 0u or 1u. +"] fn to_vec(v: t) -> [uint] { let sub = bind init_to_vec(v, _); ret vec::init_fn::(v.nbits, sub); } -/* -Function: to_str -Converts the bitvector to a string. The resulting string has the same -length as the bitvector, and each character is either '0' or '1'. -*/ +#[doc = " +Converts the bitvector to a string. + +The resulting string has the same length as the bitvector, and each character +is either '0' or '1'. +"] fn to_str(v: t) -> str { let rs = ""; for i: uint in to_vec(v) { if i == 1u { rs += "1"; } else { rs += "0"; } } ret rs; } -/* -Function: eq_vec +#[doc = " +Compare a bitvector to a vector of uint -Compare a bitvector to a vector of uint. The uint vector is expected to -only contain the values 0u and 1u. - -Preconditions: - -Both the bitvector and vector must have the same length -*/ +The uint vector is expected to only contain the values 0u and 1u. Both the +bitvector and vector must have the same length +"] fn eq_vec(v0: t, v1: [uint]) -> bool { assert (v0.nbits == vec::len::(v1)); let len = v0.nbits; diff --git a/src/libstd/c_vec.rs b/src/libstd/c_vec.rs index 53dccda3f15..e17a44234f4 100644 --- a/src/libstd/c_vec.rs +++ b/src/libstd/c_vec.rs @@ -1,6 +1,4 @@ -/* -Module: c_vec - +#[doc = " Library to interface with chunks of memory allocated in C. It is often desirable to safely interface with memory allocated from C, @@ -25,8 +23,7 @@ itself around, the c_vec could be garbage collected, and the memory within could be destroyed. There are legitimate uses for the pointer elimination form -- for instance, to pass memory back into C -- but great care must be taken to ensure that a reference to the c_vec::t is still held if needed. - - */ +"]; export t; export create, create_with_dtor; @@ -34,14 +31,12 @@ export get, set; export len; export ptr; -/* - Type: t - - The type representing a native chunk of memory. Wrapped in a enum for - opacity; FIXME #818 when it is possible to have truly opaque types, this - should be revisited. - */ +#[doc = " +The type representing a native chunk of memory +Wrapped in a enum for opacity; FIXME #818 when it is possible to have +truly opaque types, this should be revisited. +"] enum t { t({ base: *mutable T, len: uint, rsrc: @dtor_res}) } @@ -57,16 +52,14 @@ resource dtor_res(dtor: option) { Section: Introduction forms */ -/* -Function: create - +#[doc = " Create a c_vec::t from a native buffer with a given length. -Parameters: +# Arguments -base - A native pointer to a buffer -len - The number of elements in the buffer -*/ +* base - A native pointer to a buffer +* len - The number of elements in the buffer +"] unsafe fn create(base: *mutable T, len: uint) -> t { ret t({base: base, len: len, @@ -74,19 +67,17 @@ unsafe fn create(base: *mutable T, len: uint) -> t { }); } -/* -Function: create_with_dtor - +#[doc = " Create a c_vec::t from a native buffer, with a given length, and a function to run upon destruction. -Parameters: +# Arguments -base - A native pointer to a buffer -len - The number of elements in the buffer -dtor - A function to run when the value is destructed, useful - for freeing the buffer, etc. -*/ +* base - A native pointer to a buffer +* len - The number of elements in the buffer +* dtor - A function to run when the value is destructed, useful + for freeing the buffer, etc. +"] unsafe fn create_with_dtor(base: *mutable T, len: uint, dtor: fn@()) -> t { ret t({base: base, @@ -99,29 +90,21 @@ unsafe fn create_with_dtor(base: *mutable T, len: uint, dtor: fn@()) Section: Operations */ -/* -Function: get - +#[doc = " Retrieves an element at a given index -Failure: - -If `ofs` is greater or equal to the length of the vector -*/ +Fails if `ofs` is greater or equal to the length of the vector +"] fn get(t: t, ofs: uint) -> T { assert ofs < len(t); ret unsafe { *ptr::mut_offset((*t).base, ofs) }; } -/* -Function: set - +#[doc = " Sets the value of an element at a given index -Failure: - -If `ofs` is greater or equal to the length of the vector -*/ +Fails if `ofs` is greater or equal to the length of the vector +"] fn set(t: t, ofs: uint, v: T) { assert ofs < len(t); unsafe { *ptr::mut_offset((*t).base, ofs) = v }; @@ -131,20 +114,12 @@ fn set(t: t, ofs: uint, v: T) { Section: Elimination forms */ -/* -Function: len - -Returns the length of the vector -*/ +#[doc = "Returns the length of the vector"] fn len(t: t) -> uint { ret (*t).len; } -/* -Function: ptr - -Returns a pointer to the first element of the vector -*/ +#[doc = "Returns a pointer to the first element of the vector"] unsafe fn ptr(t: t) -> *mutable T { ret (*t).base; } diff --git a/src/libstd/dbg.rs b/src/libstd/dbg.rs index f37a97bcb42..5278caf867e 100644 --- a/src/libstd/dbg.rs +++ b/src/libstd/dbg.rs @@ -1,12 +1,4 @@ - - - -/** - * Unsafe debugging functions for inspecting values. - * - * Your RUST_LOG environment variable must contain "stdlib" for any debug - * logging. - */ +#[doc = "Unsafe debugging functions for inspecting values."]; #[abi = "cdecl"] native mod rustrt { diff --git a/src/libstd/deque.rs b/src/libstd/deque.rs index f12c72f80e1..83452e6ab68 100644 --- a/src/libstd/deque.rs +++ b/src/libstd/deque.rs @@ -1,40 +1,18 @@ +#[doc = "A deque. Untested as of yet. Likely buggy"]; + import option::{some, none}; -/* -Module: deque - -A deque. Untested as of yet. Likely buggy. -*/ - -/* -Iface: t -*/ iface t { - // Method: size fn size() -> uint; - // Method: add_front fn add_front(T); - // Method: add_back fn add_back(T); - // Method: pop_front fn pop_front() -> T; - // Method: pop_back fn pop_back() -> T; - // Method: peek_front fn peek_front() -> T; - // Method: peek_back fn peek_back() -> T; - // Method: get fn get(int) -> T; } -/* -Section: Functions -*/ - -/* -Function: create -*/ // FIXME eventually, a proper datatype plus an exported impl would be // preferrable fn create() -> t { diff --git a/src/libstd/four.rs b/src/libstd/four.rs index e1804be2b91..744dc0a4c91 100644 --- a/src/libstd/four.rs +++ b/src/libstd/four.rs @@ -1,8 +1,6 @@ // -*- rust -*- -/* -Module: four - +#[doc = " The fourrternary Belnap relevance logic FOUR represented as ADT This allows reasoning with four logic values (true, false, none, both). @@ -10,7 +8,7 @@ This allows reasoning with four logic values (true, false, none, both). Implementation: Truth values are represented using a single u8 and all operations are done using bit operations which is fast on current cpus. -*/ +"]; import tri; @@ -19,152 +17,93 @@ export not, and, or, xor, implies, implies_materially; export eq, ne, is_true, is_false; export from_str, to_str, all_values, to_trit, to_bit; -/* -Type: t - +#[doc = " The type of fourrternary logic values It may be thought of as tuple `(y, x)` of two bools - -*/ +"] type t = u8; const b0: u8 = 1u8; const b1: u8 = 2u8; const b01: u8 = 3u8; -/* -Constant: none - -Logic value `(0, 0)` for bottom (neither true or false) -*/ +#[doc = "Logic value `(0, 0)` for bottom (neither true or false)"] const none: t = 0u8; -/* -Constant: true - -Logic value `(0, 1)` for truth -*/ +#[doc = "Logic value `(0, 1)` for truth"] const true: t = 1u8; -/* -Constant: false - -Logic value `(1, 0)` for falsehood -*/ +#[doc = "Logic value `(1, 0)` for falsehood"] const false: t = 2u8; -/* -Constant: both - -Logic value `(1, 1)` for top (both true and false) -*/ +#[doc = "Logic value `(1, 1)` for top (both true and false)"] const both: t = 3u8; -/* Function: not - +#[doc = " Negation/Inverse -Returns: - -`'(v.y, v.x)` -*/ +Returns `'(v.y, v.x)` +"] pure fn not(v: t) -> t { ((v << 1u8) | (v >> 1u8)) & b01 } -/* Function: and - +#[doc = " Conjunction -Returns: - -`(a.x | b.x, a.y & b.y)` -*/ +Returns `(a.x | b.x, a.y & b.y)` +"] pure fn and(a: t, b: t) -> t { ((a & b) & b0) | ((a | b) & b1) } -/* Function: or - +#[doc = " Disjunction -Returns: - -`(a.x & b.x, a.y | b.y)` -*/ +Returns `(a.x & b.x, a.y | b.y)` +"] pure fn or(a: t, b: t) -> t { ((a | b) & b0) | ((a & b) & b1) } -/* Function: xor - +#[doc = " Classic exclusive or -Returns: - -`or(and(a, not(b)), and(not(a), b))` -*/ +Returns `or(and(a, not(b)), and(not(a), b))` +"] pure fn xor(a: t, b: t) -> t { or(and(a, not(b)), and(not(a), b)) } -/* -Function: implies - +#[doc = " Strong implication (from `a` strongly follows `b`) -Returns: - -`( x1 & y2, !x1 | x2)` -*/ +Returns `( x1 & y2, !x1 | x2)` +"] pure fn implies(a: t, b: t) -> t { ((a << 1u8) & b & b1) | (((!a) | b) & b0) } -/* -Function: implies_materially - +#[doc = " Classic (material) implication in the logic (from `a` materially follows `b`) -Returns: - -`or(not(a), b)` -*/ +Returns `or(not(a), b)` +"] pure fn implies_materially(a: t, b: t) -> t { or(not(a), b) } -/* -Predicate: eq - -Returns: - -true if truth values `a` and `b` are indistinguishable in the logic -*/ +#[doc = " +Returns true if truth values `a` and `b` are indistinguishable in the logic +"] pure fn eq(a: t, b: t) -> bool { a == b } -/* -Predicate: ne - -Returns: - -true if truth values `a` and `b` are distinguishable in the logic -*/ +#[doc = " +Returns true if truth values `a` and `b` are distinguishable in the logic +"] pure fn ne(a: t, b: t) -> bool { a != b } -/* -Predicate: is_true - -Returns: - -true if `v` represents truth in the logic (is `true` or `both`) -*/ +#[doc = " +Returns true if `v` represents truth in the logic (is `true` or `both`) +"] pure fn is_true(v: t) -> bool { (v & b0) != 0u8 } -/* -Predicate: is_false - -Returns: - -true if `v` represents falsehood in the logic (is `false` or `none`) -*/ +#[doc = " +Returns true if `v` represents falsehood in the logic (is `false` or `none`) +"] pure fn is_false(v: t) -> bool { (v & b0) == 0u8 } -/* -Function: from_str - -Parse logic value from `s` -*/ +#[doc = "Parse logic value from `s`"] pure fn from_str(s: str) -> t { alt check s { "none" { none } @@ -174,11 +113,7 @@ pure fn from_str(s: str) -> t { } } -/* -Function: to_str - -Convert `v` into a string -*/ +#[doc = "Convert `v` into a string"] pure fn to_str(v: t) -> str { // FIXME replace with consts as soon as that works alt check v { @@ -189,12 +124,10 @@ pure fn to_str(v: t) -> str { } } -/* -Function: all_values - -Iterates over all truth values by passing them to `blk` -in an unspecified order -*/ +#[doc = " +Iterates over all truth values by passing them to `blk` in an unspecified +order +"] fn all_values(blk: fn(v: t)) { blk(both); blk(four::true); @@ -202,22 +135,15 @@ fn all_values(blk: fn(v: t)) { blk(none); } -/* -Function: to_bit - -Returns: - -An u8 whose first bit is set if `if_true(v)` holds -*/ +#[doc = " +Returns an `u8` whose first bit is set if `if_true(v)` holds +"] fn to_bit(v: t) -> u8 { v & b0 } -/* -Function: to_tri - -Returns: - -A trit of `v` (`both` and `none` are both coalesced into `trit::unknown`) -*/ +#[doc = " +Returns a trit of `v` (`both` and `none` are both coalesced into +`trit::unknown`) +"] fn to_trit(v: t) -> tri::t { v & (v ^ not(v)) } #[cfg(test)] diff --git a/src/libstd/fun_treemap.rs b/src/libstd/fun_treemap.rs index d497b2a4963..3e1a11665fe 100644 --- a/src/libstd/fun_treemap.rs +++ b/src/libstd/fun_treemap.rs @@ -1,6 +1,4 @@ -/* -Module: fun_treemap - +#[doc = " A functional key,value store that works on anything. This works using a binary search tree. In the first version, it's a @@ -9,8 +7,7 @@ red-black tree or something else. This is copied and modified from treemap right now. It's missing a lot of features. - -*/ +"]; import option::{some, none}; import option = option; @@ -21,35 +18,17 @@ export insert; export find; export traverse; -/* Section: Types */ - -/* -Type: treemap -*/ type treemap = @tree_node; -/* -Tag: tree_node -*/ enum tree_node { empty, node(@K, @V, @tree_node, @tree_node) } -/* Section: Operations */ - -/* -Function: init - -Create a treemap -*/ +#[doc = "Create a treemap"] fn init() -> treemap { @empty } -/* -Function: insert - -Insert a value into the map -*/ +#[doc = "Insert a value into the map"] fn insert(m: treemap, k: K, v: V) -> treemap { @alt m { @empty { node(@k, @v, @empty, @empty) } @@ -63,11 +42,7 @@ fn insert(m: treemap, k: K, v: V) -> treemap { } } -/* -Function: find - -Find a value based on the key -*/ +#[doc = "Find a value based on the key"] fn find(m: treemap, k: K) -> option { alt *m { empty { none } @@ -79,11 +54,7 @@ fn find(m: treemap, k: K) -> option { } } -/* -Function: traverse - -Visit all pairs in the map in order. -*/ +#[doc = "Visit all pairs in the map in order."] fn traverse(m: treemap, f: fn(K, V)) { alt *m { empty { } diff --git a/src/libstd/getopts.rs b/src/libstd/getopts.rs index 62ef4839d64..2177f2468ef 100644 --- a/src/libstd/getopts.rs +++ b/src/libstd/getopts.rs @@ -1,49 +1,49 @@ -/* -Module: getopts +#[doc = " +Simple getopt alternative. -Simple getopt alternative. Construct a vector of options, either by using -reqopt, optopt, and optflag or by building them from components yourself, and -pass them to getopts, along with a vector of actual arguments (not including -argv[0]). You'll either get a failure code back, or a match. You'll have to -verify whether the amount of 'free' arguments in the match is what you -expect. Use opt_* accessors to get argument values out of the match object. +Construct a vector of options, either by using reqopt, optopt, and optflag or +by building them from components yourself, and pass them to getopts, along +with a vector of actual arguments (not including argv[0]). You'll either get a +failure code back, or a match. You'll have to verify whether the amount of +'free' arguments in the match is what you expect. Use opt_* accessors to get +argument values out of the match object. Single-character options are expected to appear on the command line with a single preceeding dash; multiple-character options are expected to be proceeded by two dashes. Options that expect an argument accept their argument following either a space or an equals sign. -Example: +# Example The following example shows simple command line parsing for an application that requires an input file to be specified, accepts an optional output file name following -o, and accepts both -h and --help as optional flags. -> fn main(args: [str]) { -> let opts = [ -> optopt("o"), -> optflag("h"), -> optflag("help") -> ]; -> let match = alt getopts(vec::shift(args), opts) { -> ok(m) { m } -> err(f) { fail fail_str(f) } -> }; -> if opt_present(match, "h") || opt_present(match, "help") { -> print_usage(); -> ret; -> } -> let output = opt_maybe_str(match, "o"); -> let input = if !vec::is_empty(match.free) { -> match.free[0] -> } else { -> print_usage(); -> ret; -> } -> do_work(input, output); -> } + fn main(args: [str]) { + let opts = [ + optopt(\"o\"), + optflag(\"h\"), + optflag(\"help\") + ]; + let match = alt getopts(vec::shift(args), opts) { + ok(m) { m } + err(f) { fail fail_str(f) } + }; + if opt_present(match, \"h\") || opt_present(match, \"help\") { + print_usage(); + ret; + } + let output = opt_maybe_str(match, \"o\"); + let input = if !vec::is_empty(match.free) { + match.free[0] + } else { + print_usage(); + ret; + } + do_work(input, output); + } -*/ +"]; import core::result; import core::result::{err, ok}; @@ -71,11 +71,7 @@ enum hasarg { yes, no, maybe, } enum occur { req, optional, multi, } -/* -Type: opt - -A description of a possible option -*/ +#[doc = "A description of a possible option"] type opt = {name: name, hasarg: hasarg, occur: occur}; fn mkname(nm: str) -> name { @@ -84,60 +80,40 @@ fn mkname(nm: str) -> name { } else { long(nm) }; } -/* -Function: reqopt - -Create an option that is required and takes an argument -*/ +#[doc = "Create an option that is required and takes an argument"] fn reqopt(name: str) -> opt { ret {name: mkname(name), hasarg: yes, occur: req}; } -/* -Function: optopt - -Create an option that is optional and takes an argument -*/ +#[doc = "Create an option that is optional and takes an argument"] fn optopt(name: str) -> opt { ret {name: mkname(name), hasarg: yes, occur: optional}; } -/* -Function: optflag - -Create an option that is optional and does not take an argument -*/ +#[doc = "Create an option that is optional and does not take an argument"] fn optflag(name: str) -> opt { ret {name: mkname(name), hasarg: no, occur: optional}; } -/* -Function: optflagopt - -Create an option that is optional and takes an optional argument -*/ +#[doc = "Create an option that is optional and takes an optional argument"] fn optflagopt(name: str) -> opt { ret {name: mkname(name), hasarg: maybe, occur: optional}; } -/* -Function: optmulti - +#[doc = " Create an option that is optional, takes an argument, and may occur multiple times -*/ +"] fn optmulti(name: str) -> opt { ret {name: mkname(name), hasarg: yes, occur: multi}; } enum optval { val(str), given, } -/* -Type: match - +#[doc = " The result of checking command line arguments. Contains a vector of matches and a vector of free strings. -*/ +"] type match = {opts: [opt], vals: [mutable [optval]], free: [str]}; fn is_arg(arg: str) -> bool { @@ -152,12 +128,10 @@ fn find_opt(opts: [opt], nm: name) -> option { vec::position(opts, { |opt| opt.name == nm }) } -/* -Type: fail_ - +#[doc = " The type returned when the command line does not conform to the expected format. Pass this value to to get an error message. -*/ +"] enum fail_ { argument_missing(str), unrecognized_option(str), @@ -166,11 +140,7 @@ enum fail_ { unexpected_argument(str), } -/* -Function: fail_str - -Convert a enum into an error string -*/ +#[doc = "Convert a `fail_` enum into an error string"] fn fail_str(f: fail_) -> str { ret alt f { argument_missing(nm) { "Argument to option '" + nm + "' missing." } @@ -185,30 +155,19 @@ fn fail_str(f: fail_) -> str { }; } -/* -Type: result - +#[doc = " The result of parsing a command line with a set of options (result::t) - -Variants: - -ok(match) - Returned from getopts on success -err(fail_) - Returned from getopts on failure -*/ +"] type result = result::t; -/* -Function: getopts - +#[doc = " Parse command line arguments according to the provided options -Returns: - -ok(match) - On success. Use functions such as - , etc. to interrogate results. -err(fail_) - On failure. Use to get an error message. -*/ +On success returns `ok(opt)`. Use functions such as `opt_present` `opt_str`, +etc. to interrogate results. Returns `err(fail_)` on failure. Use +to get an error message. +"] fn getopts(args: [str], opts: [opt]) -> result unsafe { let n_opts = vec::len::(opts); fn f(_x: uint) -> [optval] { ret []; } @@ -311,35 +270,25 @@ fn opt_vals(m: match, nm: str) -> [optval] { fn opt_val(m: match, nm: str) -> optval { ret opt_vals(m, nm)[0]; } -/* -Function: opt_present - -Returns true if an option was matched -*/ +#[doc = "Returns true if an option was matched"] fn opt_present(m: match, nm: str) -> bool { ret vec::len::(opt_vals(m, nm)) > 0u; } -/* -Function: opt_str - +#[doc = " Returns the string argument supplied to a matching option -Failure: - -- If the option was not matched -- If the match did not take an argument -*/ +Fails if the option was not matched or if the match did not take an argument +"] fn opt_str(m: match, nm: str) -> str { ret alt opt_val(m, nm) { val(s) { s } _ { fail } }; } -/* -Function: opt_str - +#[doc = " Returns a vector of the arguments provided to all matches of the given option. + Used when an option accepts multiple values. -*/ +"] fn opt_strs(m: match, nm: str) -> [str] { let acc: [str] = []; for v: optval in opt_vals(m, nm) { @@ -348,11 +297,9 @@ fn opt_strs(m: match, nm: str) -> [str] { ret acc; } -/* -Function: opt_str - +#[doc = " Returns the string argument supplied to a matching option or none -*/ +"] fn opt_maybe_str(m: match, nm: str) -> option { let vals = opt_vals(m, nm); if vec::len::(vals) == 0u { ret none::; } @@ -360,15 +307,13 @@ fn opt_maybe_str(m: match, nm: str) -> option { } -/* -Function: opt_default - +#[doc = " Returns the matching string, a default, or none Returns none if the option was not present, `def` if the option was present but no argument was provided, and the argument if the option was present and an argument was provided. -*/ +"] fn opt_default(m: match, nm: str, def: str) -> option { let vals = opt_vals(m, nm); if vec::len::(vals) == 0u { ret none::; } diff --git a/src/libstd/json.rs b/src/libstd/json.rs index 26e4cc3165e..499e3f36061 100644 --- a/src/libstd/json.rs +++ b/src/libstd/json.rs @@ -1,6 +1,8 @@ // Rust JSON serialization library // Copyright (c) 2011 Google Inc. +#[doc = "json serialization"]; + import result::{ok, err}; import io; import io::{reader_util, writer_util}; @@ -22,23 +24,13 @@ export list; export dict; export null; -/* -Tag: json - -Represents a json value. -*/ +#[doc = "Represents a json value"] enum json { - /* Variant: num */ num(float), - /* Variant: string */ string(str), - /* Variant: boolean */ boolean(bool), - /* Variant: list */ list([json]), - /* Variant: dict */ dict(map::hashmap), - /* Variant: null */ null, } @@ -48,11 +40,7 @@ type error = { msg: str, }; -/* -Function: to_writer - -Serializes a json value into a io::writer. -*/ +#[doc = "Serializes a json value into a io::writer"] fn to_writer(wr: io::writer, j: json) { alt j { num(n) { wr.write_str(float::to_str(n, 6u)); } @@ -114,11 +102,7 @@ fn to_writer(wr: io::writer, j: json) { } } -/* -Function: to_str - -Serializes a json value into a string. -*/ +#[doc = "Serializes a json value into a string"] fn to_str(j: json) -> str { io::with_str_writer { |wr| to_writer(wr, j) } } @@ -469,12 +453,7 @@ impl parser for parser { } } -/* -Function: from_reader - -Deserializes a json value from an io::reader. -*/ - +#[doc = "Deserializes a json value from an io::reader"] fn from_reader(rdr: io::reader) -> result::t { let parser = { rdr: rdr, @@ -486,20 +465,12 @@ fn from_reader(rdr: io::reader) -> result::t { parser.parse() } -/* -Function: from_str - -Deserializes a json value from a string. -*/ +#[doc = "Deserializes a json value from a string"] fn from_str(s: str) -> result::t { io::with_str_reader(s, from_reader) } -/* -Function: eq - -Test if two json values are equal. -*/ +#[doc = "Test if two json values are equal"] fn eq(value0: json, value1: json) -> bool { alt (value0, value1) { (num(f0), num(f1)) { f0 == f1 } diff --git a/src/libstd/list.rs b/src/libstd/list.rs index 3c2d6988587..613a4790d36 100644 --- a/src/libstd/list.rs +++ b/src/libstd/list.rs @@ -1,66 +1,45 @@ -/* -Module: list - -A standard linked list -*/ +#[doc = "A standard linked list"]; import core::option; import option::*; import option::{some, none}; -/* Section: Types */ - -/* -Tag: list -*/ enum list { - /* Variant: cons */ cons(T, @list), - /* Variant: nil */ nil, } -/*Section: Operations */ - -/* -Function: from_vec - -Create a list from a vector -*/ +#[doc = "Create a list from a vector"] fn from_vec(v: [const T]) -> list { *vec::foldr(v, @nil::, { |h, t| @cons(h, t) }) } -/* -Function: foldl - +#[doc = " Left fold -Applies `f` to `u` and the first element in the list, then applies -`f` to the result of the previous call and the second element, -and so on, returning the accumulated result. +Applies `f` to `u` and the first element in the list, then applies `f` to the +result of the previous call and the second element, and so on, returning the +accumulated result. -Parameters: +# Arguments -ls - The list to fold -z - The initial value -f - The function to apply -*/ +* ls - The list to fold +* z - The initial value +* f - The function to apply +"] fn foldl(ls: list, z: T, f: fn(T, U) -> T) -> T { let accum: T = z; iter(ls) {|elt| accum = f(accum, elt);} accum } -/* -Function: find - +#[doc = " Search for an element that matches a given predicate Apply function `f` to each element of `v`, starting from the first. When function `f` returns true then an option containing the element is returned. If `f` matches no elements then none is returned. -*/ +"] fn find(ls: list, f: fn(T) -> option) -> option { let ls = ls; @@ -75,11 +54,7 @@ fn find(ls: list, f: fn(T) -> option) ret none; } -/* -Function: has - -Returns true if a list contains an element with the given value -*/ +#[doc = "Returns true if a list contains an element with the given value"] fn has(ls: list, elt: T) -> bool { let ls = ls; while true { @@ -91,11 +66,7 @@ fn has(ls: list, elt: T) -> bool { ret false; } -/* -Function: is_empty - -Returns true if the list is empty. -*/ +#[doc = "Returns true if the list is empty"] pure fn is_empty(ls: list) -> bool { alt ls { nil { true } @@ -103,31 +74,19 @@ pure fn is_empty(ls: list) -> bool { } } -/* -Function: is_not_empty - -Returns true if the list is not empty. -*/ +#[doc = "Returns true if the list is not empty"] pure fn is_not_empty(ls: list) -> bool { ret !is_empty(ls); } -/* -Function: len - -Returns the length of a list -*/ +#[doc = "Returns the length of a list"] fn len(ls: list) -> uint { let count = 0u; iter(ls) {|_e| count += 1u;} count } -/* -Function: tail - -Returns all but the first element of a list -*/ +#[doc = "Returns all but the first element of a list"] pure fn tail(ls: list) -> list { alt ls { cons(_, tl) { ret *tl; } @@ -135,20 +94,12 @@ pure fn tail(ls: list) -> list { } } -/* -Function: head - -Returns the first element of a list -*/ +#[doc = "Returns the first element of a list"] pure fn head(ls: list) -> T { alt check ls { cons(hd, _) { hd } } } -/* -Function: append - -Appends one list to another -*/ +#[doc = "Appends one list to another"] pure fn append(l: list, m: list) -> list { alt l { nil { ret m; } @@ -156,11 +107,7 @@ pure fn append(l: list, m: list) -> list { } } -/* -Function: iter - -Iterate over a list -*/ +#[doc = "Iterate over a list"] fn iter(l: list, f: fn(T)) { alt l { cons(hd, tl) { diff --git a/src/libstd/map.rs b/src/libstd/map.rs index bb67b574a44..6eae6992bcb 100644 --- a/src/libstd/map.rs +++ b/src/libstd/map.rs @@ -1,107 +1,65 @@ -/* -Module: map - -A map type -*/ +#[doc = "A map type"]; import chained::hashmap; export hashmap, hashfn, eqfn, set, map, chained, mk_hashmap, new_str_hash; export new_bytes_hash, new_int_hash, new_uint_hash, set_add; -/* Section: Types */ +#[doc = " +A function that returns a hash of a value -/* -Type: hashfn - -A function that returns a hash of a value. -The hash should concentrate entropy in the -lower bits. -*/ +The hash should concentrate entropy in the lower bits. +"] type hashfn = fn@(K) -> uint; -/* -Type: eqfn - -Equality -*/ type eqfn = fn@(K, K) -> bool; -/* -Type: set - -A convenience type to treat a hashmap as a set -*/ +#[doc = "A convenience type to treat a hashmap as a set"] type set = hashmap; type hashmap = chained::t; -/* -IFace: map -*/ iface map { - /* - Method: size - - Return the number of elements in the map - */ + #[doc = "Return the number of elements in the map"] fn size() -> uint; - /* - Method: insert - Add a value to the map. If the map already contains a value for - the specified key then the original value is replaced. + #[doc = " + Add a value to the map. - Returns: + If the map already contains a value for the specified key then the + original value is replaced. - True if the key did not already exist in the map - */ + Returns true if the key did not already exist in the map + "] fn insert(K, V) -> bool; - /* - Method: contains_key - Returns true if the map contains a value for the specified key - */ + #[doc = "Returns true if the map contains a value for the specified key"] fn contains_key(K) -> bool; - /* - Method: get - Get the value for the specified key - - Failure: - - If the key does not exist in the map - */ + #[doc = " + Get the value for the specified key. Fails if the key does not exist in + the map. + "] fn get(K) -> V; - /* - Method: find - Get the value for the specified key. If the key does not exist - in the map then returns none. - */ + #[doc = " + Get the value for the specified key. If the key does not exist in + the map then returns none. + "] fn find(K) -> option; - /* - Method: remove + #[doc = " Remove and return a value from the map. If the key does not exist in the map then returns none. - */ + "] fn remove(K) -> option; - /* - Method: items - Iterate over all the key/value pairs in the map - */ + #[doc = "Iterate over all the key/value pairs in the map"] fn items(fn(K, V)); - /* - Method: keys - Iterate over all the keys in the map - */ + #[doc = "Iterate over all the keys in the map"] fn keys(fn(K)); - /* - Iterate over all the values in the map - */ + #[doc = "Iterate over all the values in the map"] fn values(fn(V)); } @@ -345,51 +303,33 @@ fn mk_hashmap(hasher: hashfn, eqer: eqfn) chained::mk(hasher, eqer) } -/* -Function: new_str_hash - -Construct a hashmap for string keys -*/ +#[doc = "Construct a hashmap for string keys"] fn new_str_hash() -> hashmap { ret mk_hashmap(str::hash, str::eq); } -/* -Function: new_bytes_hash - -Construct a hashmap for byte string keys -*/ +#[doc = "Construct a hashmap for byte string keys"] fn new_bytes_hash() -> hashmap<[u8], V> { ret mk_hashmap(vec::u8::hash, vec::u8::eq); } -/* -Function: new_int_hash - -Construct a hashmap for int keys -*/ +#[doc = "Construct a hashmap for int keys"] fn new_int_hash() -> hashmap { fn hash_int(&&x: int) -> uint { int::hash(x) } fn eq_int(&&a: int, &&b: int) -> bool { ret a == b; } ret mk_hashmap(hash_int, eq_int); } -/* -Function: new_uint_hash - -Construct a hashmap for uint keys -*/ +#[doc = "Construct a hashmap for uint keys"] fn new_uint_hash() -> hashmap { fn hash_uint(&&x: uint) -> uint { uint::hash(x) } fn eq_uint(&&a: uint, &&b: uint) -> bool { ret a == b; } ret mk_hashmap(hash_uint, eq_uint); } -/* -Function: set_add - +#[doc = " Convenience function for adding keys to a hashmap with nil type keys -*/ +"] fn set_add(set: set, key: K) -> bool { ret set.insert(key, ()); } #[cfg(test)] diff --git a/src/libstd/net.rs b/src/libstd/net.rs index 06db7f7d7c8..796b87bb747 100644 --- a/src/libstd/net.rs +++ b/src/libstd/net.rs @@ -1,17 +1,7 @@ -/* -Module: net -*/ - import vec; import uint; -/* Section: Types */ - -/* -Tag: ip_addr - -An IP address -*/ +#[doc = "An IP address"] enum ip_addr { /* Variant: ipv4 @@ -21,13 +11,7 @@ enum ip_addr { ipv4(u8, u8, u8, u8), } -/* Section: Operations */ - -/* -Function: format_addr - -Convert an to a str -*/ +#[doc = "Convert an `ip_addr` to a str"] fn format_addr(ip: ip_addr) -> str { alt ip { ipv4(a, b, c, d) { @@ -37,17 +21,13 @@ fn format_addr(ip: ip_addr) -> str { } } -/* -Function: parse_addr +#[doc = " +Convert a str to `ip_addr` -Convert a str to +Converts a string of the format `x.x.x.x` into an ip_addr enum. -Converts a string of the format "x.x.x.x" into an ip_addr enum. - -Failure: - -String must be a valid IPv4 address -*/ +Fails if the string is not a valid IPv4 address +"] fn parse_addr(ip: str) -> ip_addr { let parts = vec::map(str::split_char(ip, '.'), {|s| alt uint::from_str(s) { diff --git a/src/libstd/rand.rs b/src/libstd/rand.rs index 35525b70710..f9052e6c848 100644 --- a/src/libstd/rand.rs +++ b/src/libstd/rand.rs @@ -1,8 +1,4 @@ -/* -Module: rand - -Random number generation -*/ +#[doc = "Random number generation"] enum rctx {} @@ -13,52 +9,24 @@ native mod rustrt { fn rand_free(c: *rctx); } -/* Section: Types */ - -/* -Obj: rng - -A random number generator -*/ +#[doc = "A random number generator"] iface rng { - /* - Method: next - - Return the next random integer - */ + #[doc = "Return the next random integer"] fn next() -> u32; - /* - Method: next_float - - Return the next random float - */ + #[doc = "Return the next random float"] fn next_float() -> float; - /* - Method: gen_str - - Return a random string composed of A-Z, a-z, 0-9. - */ + #[doc = "Return a random string composed of A-Z, a-z, 0-9."] fn gen_str(len: uint) -> str; - /* - Method: gen_bytes - - Return a random byte string. - */ + #[doc = "Return a random byte string."] fn gen_bytes(len: uint) -> [u8]; } resource rand_res(c: *rctx) { rustrt::rand_free(c); } -/* Section: Operations */ - -/* -Function: mk_rng - -Create a random number generator -*/ +#[doc = "Create a random number generator"] fn mk_rng() -> rng { impl of rng for @rand_res { fn next() -> u32 { ret rustrt::rand_next(**self); } diff --git a/src/libstd/rope.rs b/src/libstd/rope.rs index ea99d58aa86..1166241f010 100644 --- a/src/libstd/rope.rs +++ b/src/libstd/rope.rs @@ -1,7 +1,4 @@ -/* -Module: rope - - +#[doc = " High-level text containers. Ropes are a high-level representation of text that offers @@ -18,79 +15,70 @@ structure of ropes makes them suitable as a form of index to speed-up access to Unicode characters by index in long chunks of text. The following operations are algorithmically faster in ropes: -- extracting a subrope is logarithmic (linear in strings); -- appending/prepending is near-constant time (linear in strings); -- concatenation is near-constant time (linear in strings); -- char length is constant-time (linear in strings); -- access to a character by index is logarithmic (linear in strings); - */ + +* extracting a subrope is logarithmic (linear in strings); +* appending/prepending is near-constant time (linear in strings); +* concatenation is near-constant time (linear in strings); +* char length is constant-time (linear in strings); +* access to a character by index is logarithmic (linear in strings); +"]; -/* - Type: rope - - The type of ropes. - */ +#[doc = "The type of ropes."] type rope = node::root; /* Section: Creating a rope */ -/* - Function:empty - - Create an empty rope - */ +#[doc = "Create an empty rope"] fn empty() -> rope { ret node::empty; } -/* - Function: of_str +#[doc = " +Adopt a string as a rope. - Adopt a string as a rope. +# Arguments - Parameters: +* str - A valid string. -str - A valid string. - - Returns: +# Return value A rope representing the same string as `str`. Depending of the length of `str`, this rope may be empty, flat or complex. -Performance notes: -- this operation does not copy the string; -- the function runs in linear time. - */ +# Performance notes + +* this operation does not copy the string; +* the function runs in linear time. +"] fn of_str(str: @str) -> rope { ret of_substr(str, 0u, str::len(*str)); } -/* -Function: of_substr - +#[doc = " As `of_str` but for a substring. -Performance note: -- this operation does not copy the substring. +# Arguments +* byte_offset - The offset of `str` at which the rope starts. +* byte_len - The number of bytes of `str` to use. -Parameters: +# Return value -byte_offset - The offset of `str` at which the rope starts. -byte_len - The number of bytes of `str` to use. +A rope representing the same string as `str::substr(str, byte_offset, +byte_len)`. Depending on `byte_len`, this rope may be empty, flat or +complex. -Returns: +# Performance note -A rope representing the same string as -`str::substr(str, byte_offset, byte_len)`. -Depending on `byte_len`, this rope may be empty, flat or complex. +This operation does not copy the substring. -Safety notes: -- this function does _not_ check the validity of the substring; -- this function fails if `byte_offset` or `byte_len` do not match `str`. - */ +# Safety notes + +* this function does _not_ check the validity of the substring; +* this function fails if `byte_offset` or `byte_len` do not match `str`. +"] fn of_substr(str: @str, byte_offset: uint, byte_len: uint) -> rope { if byte_len == 0u { ret node::empty; } if byte_offset + byte_len > str::len(*str) { fail; } @@ -101,59 +89,49 @@ fn of_substr(str: @str, byte_offset: uint, byte_len: uint) -> rope { Section: Adding things to a rope */ -/* -Function: append_char - +#[doc = " Add one char to the end of the rope -Performance note: -- this function executes in near-constant time - */ +# Performance note + +* this function executes in near-constant time +"] fn append_char(rope: rope, char: char) -> rope { ret append_str(rope, @str::from_chars([char])); } -/* -Function: append_str - +#[doc = " Add one string to the end of the rope -Performance note: -- this function executes in near-linear time - */ +# Performance note + +* this function executes in near-linear time +"] fn append_str(rope: rope, str: @str) -> rope { ret append_rope(rope, of_str(str)) } -/* -Function: prepend_char - +#[doc = " Add one char to the beginning of the rope -Performance note: -- this function executes in near-constant time - */ +# Performance note +* this function executes in near-constant time +"] fn prepend_char(rope: rope, char: char) -> rope { ret prepend_str(rope, @str::from_chars([char])); } -/* -Function: prepend_str - +#[doc = " Add one string to the beginning of the rope -Performance note: -- this function executes in near-linear time - */ +# Performance note +* this function executes in near-linear time +"] fn prepend_str(rope: rope, str: @str) -> rope { ret append_rope(of_str(str), rope) } -/* -Function: append_rope - -Concatenate two ropes - */ +#[doc = "Concatenate two ropes"] fn append_rope(left: rope, right: rope) -> rope { alt(left) { node::empty { ret right; } @@ -168,15 +146,13 @@ fn append_rope(left: rope, right: rope) -> rope { } } -/* -Function: concat - +#[doc = " Concatenate many ropes. If the ropes are balanced initially and have the same height, the resulting rope remains balanced. However, this function does not take any further measure to ensure that the result is balanced. - */ +"] fn concat(v: [rope]) -> rope { //Copy `v` into a mutable vector let len = vec::len(v); @@ -209,19 +185,17 @@ Section: Keeping ropes healthy */ -/* -Function: bal - +#[doc = " Balance a rope. -Returns: +# Return value A copy of the rope in which small nodes have been grouped in memory, and with a reduced height. If you perform numerous rope concatenations, it is generally a good idea to rebalance your rope at some point, before using it for other purposes. - */ +"] fn bal(rope:rope) -> rope { alt(rope) { node::empty { ret rope } @@ -239,19 +213,19 @@ Section: Transforming ropes */ -/* -Function: sub_chars - +#[doc = " Extract a subrope from a rope. -Performance note: -- on a balanced rope, this operation takes algorithmic time; -- this operation does not involve any copying +# Performance note -Safety note: -- this function fails if char_offset/char_len do not represent -valid positions in rope - */ +* on a balanced rope, this operation takes algorithmic time; +* this operation does not involve any copying + +# Safety note + +* this function fails if char_offset/char_len do not represent + valid positions in rope +"] fn sub_chars(rope: rope, char_offset: uint, char_len: uint) -> rope { if char_len == 0u { ret node::empty; } alt(rope) { @@ -265,19 +239,19 @@ fn sub_chars(rope: rope, char_offset: uint, char_len: uint) -> rope { } } -/* -Function:sub_bytes - +#[doc = " Extract a subrope from a rope. -Performance note: -- on a balanced rope, this operation takes algorithmic time; -- this operation does not involve any copying +# Performance note -Safety note: -- this function fails if byte_offset/byte_len do not represent -valid positions in rope - */ +* on a balanced rope, this operation takes algorithmic time; +* this operation does not involve any copying + +# Safety note + +* this function fails if byte_offset/byte_len do not represent + valid positions in rope +"] fn sub_bytes(rope: rope, byte_offset: uint, byte_len: uint) -> rope { if byte_len == 0u { ret node::empty; } alt(rope) { @@ -295,18 +269,16 @@ fn sub_bytes(rope: rope, byte_offset: uint, byte_len: uint) -> rope { Section: Comparing ropes */ -/* -Function: cmp - +#[doc = " Compare two ropes by Unicode lexicographical order. This function compares only the contents of the rope, not their structure. -Returns: +# Return value A negative value if `left < right`, 0 if eq(left, right) or a positive value if `left > right` -*/ +"] fn cmp(left: rope, right: rope) -> int { alt((left, right)) { (node::empty, node::empty) { ret 0; } @@ -318,78 +290,70 @@ fn cmp(left: rope, right: rope) -> int { } } -/* -Function: eq - -Returns: - - `true` if both ropes have the same content (regardless of their structure), -`false` otherwise -*/ +#[doc = " +Returns `true` if both ropes have the same content (regardless of +their structure), `false` otherwise +"] fn eq(left: rope, right: rope) -> bool { ret cmp(left, right) == 0; } -/* -Function: le +#[doc = " +# Arguments -Parameters - left - an arbitrary rope - right - an arbitrary rope +* left - an arbitrary rope +* right - an arbitrary rope -Returns: +# Return value - `true` if `left <= right` in lexicographical order (regardless of their +`true` if `left <= right` in lexicographical order (regardless of their structure), `false` otherwise -*/ +"] fn le(left: rope, right: rope) -> bool { ret cmp(left, right) <= 0; } -/* -Function: lt +#[doc = " +# Arguments -Parameters - left - an arbitrary rope - right - an arbitrary rope +* left - an arbitrary rope +* right - an arbitrary rope -Returns: +# Return value - `true` if `left < right` in lexicographical order (regardless of their +`true` if `left < right` in lexicographical order (regardless of their structure), `false` otherwise -*/ +"] fn lt(left: rope, right: rope) -> bool { ret cmp(left, right) < 0; } -/* -Function: ge +#[doc = " +# Arguments -Parameters - left - an arbitrary rope - right - an arbitrary rope +* left - an arbitrary rope +* right - an arbitrary rope -Returns: +# Return value `true` if `left >= right` in lexicographical order (regardless of their structure), `false` otherwise -*/ +"] fn ge(left: rope, right: rope) -> bool { ret cmp(left, right) >= 0; } -/* -Function: gt +#[doc = " +# Arguments -Parameters - left - an arbitrary rope - right - an arbitrary rope +* left - an arbitrary rope +* right - an arbitrary rope -Returns: +# Return value - `true` if `left > right` in lexicographical order (regardless of their +`true` if `left > right` in lexicographical order (regardless of their structure), `false` otherwise -*/ +"] fn gt(left: rope, right: rope) -> bool { ret cmp(left, right) > 0; } @@ -398,9 +362,7 @@ fn gt(left: rope, right: rope) -> bool { Section: Iterating */ -/* -Function: loop_chars - +#[doc = " Loop through a rope, char by char While other mechanisms are available, this is generally the best manner @@ -409,16 +371,17 @@ loop that iterates through the contents string by string (e.g. to print the contents of the rope or output it to the system), however, you should rather use `traverse_components`. -Parameters: -rope - A rope to traverse. It may be empty. -it - A block to execute with each consecutive character of the rope. -Return `true` to continue, `false` to stop. +# Arguments -Returns: +* rope - A rope to traverse. It may be empty. +* it - A block to execute with each consecutive character of the rope. + Return `true` to continue, `false` to stop. + +# Return value `true` If execution proceeded correctly, `false` if it was interrupted, that is if `it` returned `false` at any point. - */ +"] fn loop_chars(rope: rope, it: fn(char) -> bool) -> bool { alt(rope) { node::empty { ret true } @@ -426,15 +389,13 @@ fn loop_chars(rope: rope, it: fn(char) -> bool) -> bool { } } -/* -Function: iter_chars - +#[doc = " Loop through a rope, char by char, until the end. -Parameters: -rope - A rope to traverse. It may be empty -it - A block to execute with each consecutive character of the rope. - */ +# Arguments +* rope - A rope to traverse. It may be empty +* it - A block to execute with each consecutive character of the rope. +"] fn iter_chars(rope: rope, it: fn(char)) { loop_chars(rope) {|x| it(x); @@ -442,9 +403,7 @@ fn iter_chars(rope: rope, it: fn(char)) { }; } -/* -Function: loop_leaves - +#[doc =" Loop through a rope, string by string While other mechanisms are available, this is generally the best manner of @@ -455,17 +414,17 @@ a file, etc.. If you prefer a loop that iterates through the contents char by char (e.g. to search for a char), however, you should rather use `traverse`. -Parameters: +# Arguments -rope - A rope to traverse. It may be empty -it - A block to execute with each consecutive string component of the rope. -Return `true` to continue, `false` to stop +* rope - A rope to traverse. It may be empty +* it - A block to execute with each consecutive string component of the rope. + Return `true` to continue, `false` to stop -Returns: +# Return value `true` If execution proceeded correctly, `false` if it was interrupted, that is if `it` returned `false` at any point. - */ +"] fn loop_leaves(rope: rope, it: fn(node::leaf) -> bool) -> bool{ alt(rope) { node::empty { ret true } @@ -502,15 +461,17 @@ mod iterator { Section: Rope properties */ -/* - Function: height +#[doc =" +Returns the height of the rope. - Returns: The height of the rope, i.e. a bound on the number of -operations which must be performed during a character access before -finding the leaf in which a character is contained. +The height of the rope is a bound on the number of operations which +must be performed during a character access before finding the leaf in +which a character is contained. - Performance note: Constant time. -*/ +# Performance note + +Constant time. +"] fn height(rope: rope) -> uint { alt(rope) { node::empty { ret 0u; } @@ -520,13 +481,13 @@ fn height(rope: rope) -> uint { -/* - Function: char_len +#[doc =" +The number of character in the rope - Returns: The number of character in the rope +# Performance note - Performance note: Constant time. - */ +Constant time. +"] pure fn char_len(rope: rope) -> uint { alt(rope) { node::empty { ret 0u; } @@ -534,14 +495,13 @@ pure fn char_len(rope: rope) -> uint { } } -/* - Function: char_len +#[doc = " +The number of bytes in the rope - Returns: The number of bytes in the rope +# Performance note - Performance note: Constant time. - FIXME: char or byte? - */ +Constant time. +"] pure fn byte_len(rope: rope) -> uint { alt(rope) { node::empty { ret 0u; } @@ -549,21 +509,22 @@ pure fn byte_len(rope: rope) -> uint { } } -/* - Function: char_at +#[doc = " +The character at position `pos` - Parameters: - pos - A position in the rope +# Arguments - Returns: The character at position `pos` +* pos - A position in the rope - Safety notes: The function will fail if `pos` - is not a valid position in the rope. +# Safety notes - Performance note: This function executes in a time - proportional to the height of the rope + the (bounded) - length of the largest leaf. - */ +The function will fail if `pos` is not a valid position in the rope. + +# Performance note + +This function executes in a time proportional to the height of the +rope + the (bounded) length of the largest leaf. +"] fn char_at(rope: rope, pos: uint) -> char { alt(rope) { node::empty { fail } @@ -577,140 +538,84 @@ fn char_at(rope: rope, pos: uint) -> char { */ mod node { - /* - Enum: node::root - - Implementation of type `rope` - - Constants: - empty - An empty rope - content - A non-empty rope - */ + #[doc = "Implementation of type `rope`"] enum root { + #[doc = "An empty rope"] empty, + #[doc = "A non-empty rope"] content(@node), } - /* - Struct: node::leaf + #[doc = " + A text component in a rope. - A text component in a rope. + This is actually a slice in a rope, so as to ensure maximal sharing. - This is actually a slice in a rope, so as to ensure maximal sharing. - */ + # Fields + + * byte_offset = The number of bytes skippen in `content` + * byte_len - The number of bytes of `content` to use + * char_len - The number of chars in the leaf. + * content - Contents of the leaf. + + Note that we can have `char_len < str::char_len(content)`, if + this leaf is only a subset of the string. Also note that the + string can be shared between several ropes, e.g. for indexing + purposes. + "] type leaf = { - - /* - Field: byte_offset - - The number of bytes skipped in `content` - */ - byte_offset: uint, - - /* - Field: byte_len - - The number of bytes of `content` to use - */ - byte_len: uint, - - /* - Field: char_len - - - The number of chars in the leaf. - */ - char_len: uint, - - /* - Field: content - - Contents of the leaf. - - Note that we can have `char_len < str::char_len(content)`, if this - leaf is only a subset of the string. Also note that the string - can be shared between several ropes, e.g. for indexing purposes. - */ - content: @str + byte_offset: uint, + byte_len: uint, + char_len: uint, + content: @str }; + #[doc = " + A node obtained from the concatenation of two other nodes - /* - Struct node::concat + # Fields - A node obtained from the concatenation of two other nodes - */ - type concat = { - - /* - Field: left - - The node containing the beginning of the text. - */ - left: @node,//TODO: Perhaps a `vec` instead of `left`/`right` - - /* - Field: right - - The node containing the end of the text. - */ - right: @node, - - /* - Field: char_len - - The number of chars contained in all leaves of this node. - */ - char_len: uint, - - /* - Field: byte_len - - The number of bytes in the subrope. + * left - The node containing the beginning of the text. + * right - The node containing the end of the text. + * char_len - The number of chars contained in all leaves of this node. + * byte_len - The number of bytes in the subrope. Used to pre-allocate the correct amount of storage for serialization. - */ + + * height - Height of the subrope. + + Used for rebalancing and to allocate stacks for traversals. + "] + type concat = { + left: @node,//TODO: Perhaps a `vec` instead of `left`/`right` + right: @node, + char_len: uint, byte_len: uint, - - /* - Field: height - - Height of the subrope. - - Used for rebalancing and to allocate stacks for - traversals. - */ height: uint }; - /* - Enum: node::node - - leaf - A leaf consisting in a `str` - concat - The concatenation of two ropes - */ enum node { + #[doc = "A leaf consisting in a `str`"] leaf(leaf), + #[doc = "The concatenation of two ropes"] concat(concat), } - /* + #[doc = " The maximal number of chars that _should_ be permitted in a single node. This is not a strict value - */ + "] const hint_max_leaf_char_len: uint = 256u; - /* + #[doc = " The maximal height that _should_ be permitted in a tree. This is not a strict value - */ + "] const hint_max_node_height: uint = 16u; - /* - Function: of_str - + #[doc = " Adopt a string as a node. If the string is longer than `max_leaf_char_len`, it is @@ -719,53 +624,54 @@ mod node { Performance note: The complexity of this function is linear in the length of `str`. - */ + "] fn of_str(str: @str) -> @node { ret of_substr(str, 0u, str::len(*str)); } - /* - Function: of_substr - + #[doc =" Adopt a slice of a string as a node. If the slice is longer than `max_leaf_char_len`, it is logically split between as many leaves as necessary. Regardless, the string itself is not copied - Parameters: - byte_start - The byte offset where the slice of `str` starts. - byte_len - The number of bytes from `str` to use. + # Arguments - Safety note: - - Behavior is undefined if `byte_start` or `byte_len` do not represent - valid positions in `str` - */ + * byte_start - The byte offset where the slice of `str` starts. + * byte_len - The number of bytes from `str` to use. + + # Safety note + + Behavior is undefined if `byte_start` or `byte_len` do not represent + valid positions in `str` + "] fn of_substr(str: @str, byte_start: uint, byte_len: uint) -> @node { ret of_substr_unsafer(str, byte_start, byte_len, str::count_chars(*str, byte_start, byte_len)); } - /* - Function: of_substr_unsafer - + #[doc = " Adopt a slice of a string as a node. If the slice is longer than `max_leaf_char_len`, it is logically split between as many leaves as necessary. Regardless, the string itself is not copied - byte_start - The byte offset where the slice of `str` starts. - byte_len - The number of bytes from `str` to use. - char_len - The number of chars in `str` in the interval - [byte_start, byte_start+byte_len( + # Arguments - Safety note: - - Behavior is undefined if `byte_start` or `byte_len` do not represent - valid positions in `str` - - Behavior is undefined if `char_len` does not accurately represent the - number of chars between byte_start and byte_start+byte_len - */ + * byte_start - The byte offset where the slice of `str` starts. + * byte_len - The number of bytes from `str` to use. + * char_len - The number of chars in `str` in the interval + [byte_start, byte_start+byte_len( + + # Safety notes + + * Behavior is undefined if `byte_start` or `byte_len` do not represent + valid positions in `str` + * Behavior is undefined if `char_len` does not accurately represent the + number of chars between byte_start and byte_start+byte_len + "] fn of_substr_unsafer(str: @str, byte_start: uint, byte_len: uint, char_len: uint) -> @node { assert(byte_start + byte_len <= str::len(*str)); @@ -838,16 +744,14 @@ mod node { } } - - /* - Function: tree_from_forest_destructive - + #[doc =" Concatenate a forest of nodes into one tree. - Parameters: - forest - The forest. This vector is progressively rewritten during - execution and should be discarded as meaningless afterwards. - */ + # Arguments + + * forest - The forest. This vector is progressively rewritten during + execution and should be discarded as meaningless afterwards. + "] fn tree_from_forest_destructive(forest: [mutable @node]) -> @node { let i = 0u; let len = vec::len(forest); @@ -917,13 +821,13 @@ mod node { ret str; } - /* - Function: flatten - + #[doc =" Replace a subtree by a single leaf with the same contents. - Performance note: This function executes in linear time. - */ + * Performance note + + This function executes in linear time. + "] fn flatten(node: @node) -> @node unsafe { alt(*node) { leaf(_) { ret node } @@ -938,21 +842,21 @@ mod node { } } - /* - Function: bal - + #[doc =" Balance a node. - Algorithm: - - if the node height is smaller than `hint_max_node_height`, do nothing - - otherwise, gather all leaves as a forest, rebuild a balanced node, - concatenating small leaves along the way + # Algorithm - Returns: - - `option::none` if no transformation happened - - `option::some(x)` otherwise, in which case `x` has the same contents + * if the node height is smaller than `hint_max_node_height`, do nothing + * otherwise, gather all leaves as a forest, rebuild a balanced node, + concatenating small leaves along the way + + # Return value + + * `option::none` if no transformation happened + * `option::some(x)` otherwise, in which case `x` has the same contents as `node` bot lower height and/or fragmentation. - */ + "] fn bal(node: @node) -> option<@node> { if height(node) < hint_max_node_height { ret option::none; } //1. Gather all leaves as a forest @@ -970,24 +874,25 @@ mod node { } - /* - Function: sub_bytes - + #[doc =" Compute the subnode of a node. - Parameters: - node - A node - byte_offset - A byte offset in `node` - byte_len - The number of bytes to return + # Arguments - Performance notes: - - this function performs no copying; - - this function executes in a time proportional to the height of `node`. + * node - A node + * byte_offset - A byte offset in `node` + * byte_len - The number of bytes to return - Safety notes: - - this function fails if `byte_offset` or `byte_len` do not represent + # Performance notes + + * this function performs no copying; + * this function executes in a time proportional to the height of `node`. + + # Safety notes + + This function fails if `byte_offset` or `byte_len` do not represent valid positions in `node`. - */ + "] fn sub_bytes(node: @node, byte_offset: uint, byte_len: uint) -> @node { let node = node; let byte_offset = byte_offset; @@ -1031,24 +936,25 @@ mod node { core::unreachable(); } - /* - Function: sub_chars - + #[doc =" Compute the subnode of a node. - Parameters: - node - A node - char_offset - A char offset in `node` - char_len - The number of chars to return + # Arguments - Performance notes: - - this function performs no copying; - - this function executes in a time proportional to the height of `node`. + * node - A node + * char_offset - A char offset in `node` + * char_len - The number of chars to return - Safety notes: - - this function fails if `char_offset` or `char_len` do not represent + # Performance notes + + * this function performs no copying; + * this function executes in a time proportional to the height of `node`. + + # Safety notes + + This function fails if `char_offset` or `char_len` do not represent valid positions in `node`. - */ + "] fn sub_chars(node: @node, char_offset: uint, char_len: uint) -> @node { let node = node; let char_offset = char_offset; @@ -1144,22 +1050,20 @@ mod node { }) } - /* - Function: loop_leaves - + #[doc =" Loop through a node, leaf by leaf - Parameters: + # Arguments - rope - A node to traverse. - it - A block to execute with each consecutive leaf of the node. - Return `true` to continue, `false` to stop + * rope - A node to traverse. + * it - A block to execute with each consecutive leaf of the node. + Return `true` to continue, `false` to stop - Returns: + # Arguments `true` If execution proceeded correctly, `false` if it was interrupted, that is if `it` returned `false` at any point. - */ + "] fn loop_leaves(node: @node, it: fn(leaf) -> bool) -> bool{ let current = node; while true { @@ -1179,21 +1083,23 @@ mod node { core::unreachable(); } - /* - Function: char_at + #[doc =" + # Arguments - Parameters: - pos - A position in the rope + * pos - A position in the rope - Returns: The character at position `pos` + # Return value - Safety notes: The function will fail if `pos` - is not a valid position in the rope. + The character at position `pos` + + # Safety notes + + The function will fail if `pos` is not a valid position in the rope. Performance note: This function executes in a time proportional to the height of the rope + the (bounded) length of the largest leaf. - */ + "] fn char_at(node: @node, pos: uint) -> char { let node = node; let pos = pos; diff --git a/src/libstd/run_program.rs b/src/libstd/run_program.rs index fa827c96f2f..1334e7db723 100644 --- a/src/libstd/run_program.rs +++ b/src/libstd/run_program.rs @@ -1,8 +1,4 @@ -/* -Module: run - -Process spawning -*/ +#[doc ="Process spawning"]; import option::{some, none}; import str::sbuf; import ctypes::{fd_t, pid_t, void}; @@ -21,87 +17,51 @@ native mod rustrt { -> pid_t; } -/* Section: Types */ - -/* -Iface: program - -A value representing a child process -*/ +#[doc ="A value representing a child process"] iface program { - /* - Method: get_id - - Returns the process id of the program - */ + #[doc ="Returns the process id of the program"] fn get_id() -> pid_t; - /* - Method: input - - Returns an io::writer that can be used to write to stdin - */ + #[doc ="Returns an io::writer that can be used to write to stdin"] fn input() -> io::writer; - /* - Method: output - - Returns an io::reader that can be used to read from stdout - */ + #[doc ="Returns an io::reader that can be used to read from stdout"] fn output() -> io::reader; - /* - Method: err - - Returns an io::reader that can be used to read from stderr - */ + #[doc ="Returns an io::reader that can be used to read from stderr"] fn err() -> io::reader; - /* - Method: close_input - - Closes the handle to the child processes standard input - */ + #[doc = "Closes the handle to the child processes standard input"] fn close_input(); - /* - Method: finish - + #[doc = " Waits for the child process to terminate. Closes the handle to stdin if necessary. - */ + "] fn finish() -> int; - /* - Method: destroy - - Closes open handles - */ + #[doc ="Closes open handles"] fn destroy(); } -/* Section: Operations */ - -/* -Function: spawn_process - +#[doc = " Run a program, providing stdin, stdout and stderr handles -Parameters: +# Arguments -prog - The path to an executable -args - Vector of arguments to pass to the child process -env - optional env-modification for child -dir - optional dir to run child in (default current dir) -in_fd - A file descriptor for the child to use as std input -out_fd - A file descriptor for the child to use as std output -err_fd - A file descriptor for the child to use as std error +* prog - The path to an executable +* args - Vector of arguments to pass to the child process +* env - optional env-modification for child +* dir - optional dir to run child in (default current dir) +* in_fd - A file descriptor for the child to use as std input +* out_fd - A file descriptor for the child to use as std output +* err_fd - A file descriptor for the child to use as std error -Returns: +# Return value The process id of the spawned process -*/ +"] fn spawn_process(prog: str, args: [str], env: option<[(str,str)]>, dir: option, @@ -188,43 +148,39 @@ fn with_dirp(d: option, } } -/* -Function: run_program - +#[doc =" Spawns a process and waits for it to terminate -Parameters: +# Arguments -prog - The path to an executable -args - Vector of arguments to pass to the child process +* prog - The path to an executable +* args - Vector of arguments to pass to the child process -Returns: +# Return value The process id -*/ +"] fn run_program(prog: str, args: [str]) -> int { ret waitpid(spawn_process(prog, args, none, none, 0i32, 0i32, 0i32)); } -/* -Function: start_program - +#[doc =" Spawns a process and returns a program The returned value is a boxed resource containing a object that can be used for sending and recieving data over the standard file descriptors. The resource will ensure that file descriptors are closed properly. -Parameters: +# Arguments -prog - The path to an executable -args - Vector of arguments to pass to the child process +* prog - The path to an executable +* args - Vector of arguments to pass to the child process -Returns: +# Return value A boxed resource of -*/ +"] fn start_program(prog: str, args: [str]) -> program { let pipe_input = os::pipe(); let pipe_output = os::pipe(); @@ -291,22 +247,20 @@ fn read_all(rd: io::reader) -> str { ret buf; } -/* -Function: program_output - +#[doc =" Spawns a process, waits for it to exit, and returns the exit code, and contents of stdout and stderr. -Parameters: +# Arguments -prog - The path to an executable -args - Vector of arguments to pass to the child process +* prog - The path to an executable +* args - Vector of arguments to pass to the child process -Returns: +# Return value A record, {status: int, out: str, err: str} containing the exit code, the contents of stdout and the contents of stderr. -*/ +"] fn program_output(prog: str, args: [str]) -> {status: int, out: str, err: str} { let pr = start_program(prog, args); @@ -316,11 +270,7 @@ fn program_output(prog: str, args: [str]) -> ret {status: pr.finish(), out: out, err: err}; } -/* -Function: waitpid - -Waits for a process to exit and returns the exit code -*/ +#[doc ="Waits for a process to exit and returns the exit code"] fn waitpid(pid: pid_t) -> int { ret waitpid_os(pid); diff --git a/src/libstd/serialization.rs b/src/libstd/serialization.rs index ce402165fdd..19cbd7a610b 100644 --- a/src/libstd/serialization.rs +++ b/src/libstd/serialization.rs @@ -1,8 +1,4 @@ -/* -Module: serialization - -Support code for serialization. -*/ +#[doc = "Support code for serialization."]; import list::list; import ebml::writer; diff --git a/src/libstd/sha1.rs b/src/libstd/sha1.rs index 06702fc140a..22d26fc2bd9 100644 --- a/src/libstd/sha1.rs +++ b/src/libstd/sha1.rs @@ -1,18 +1,16 @@ -/* -Module: sha1 - +#[doc =" An implementation of the SHA-1 cryptographic hash. -First create a object using the constructor, then -feed it input using the or methods, which may be +First create a `sha1` object using the `mk_sha1` constructor, then +feed it input using the `input` or `input_str` methods, which may be called any number of times. After the entire input has been fed to the hash read the result using -the or methods. +the `result` or `result_str` methods. -The object may be reused to create multiple hashes by calling -the method. -*/ +The `sha1` object may be reused to create multiple hashes by calling +the `reset` method. +"]; /* * A SHA-1 implementation derived from Paul E. Jones's reference @@ -22,50 +20,26 @@ the method. export sha1; export mk_sha1; -/* Section: Types */ - -/* -Iface: sha1 - -The SHA-1 interface -*/ +#[doc = "The SHA-1 interface"] iface sha1 { - /* - Method: input - - Provide message input as bytes - */ + #[doc = "Provide message input as bytes"] fn input([u8]); - /* - Method: input_str - - Provide message input as string - */ + #[doc = "Provide message input as string"] fn input_str(str); - /* - Method: result - + #[doc = " Read the digest as a vector of 20 bytes. After calling this no further input may be provided until reset is called. - */ + "] fn result() -> [u8]; - /* - Method: result_str - + #[doc = " Read the digest as a hex string. After calling this no further input may be provided until reset is called. - */ + "] fn result_str() -> str; - /* - Method: reset - - Reset the SHA-1 state for reuse - */ + #[doc = "Reset the SHA-1 state for reuse"] fn reset(); } -/* Section: Operations */ - // Some unexported constants const digest_buf_len: uint = 5u; const msg_block_len: uint = 64u; @@ -76,11 +50,7 @@ const k2: u32 = 0x8F1BBCDCu32; const k3: u32 = 0xCA62C1D6u32; -/* -Function: mk_sha1 - -Construct a object -*/ +#[doc = "Construct a `sha` object"] fn mk_sha1() -> sha1 { type sha1state = {h: [mutable u32], diff --git a/src/libstd/smallintmap.rs b/src/libstd/smallintmap.rs index b608ddf4a64..3ddc2bb5d6e 100644 --- a/src/libstd/smallintmap.rs +++ b/src/libstd/smallintmap.rs @@ -1,59 +1,44 @@ -/* -Module: smallintmap - +#[doc = " A simple map based on a vector for small integer keys. Space requirements are O(highest integer key). -*/ +"]; import core::option; import core::option::{some, none}; // FIXME: Should not be @; there's a bug somewhere in rustc that requires this // to be. -/* -Type: smallintmap -*/ type smallintmap = @{mutable v: [mutable option]}; -/* -Function: mk - -Create a smallintmap -*/ +#[doc = "Create a smallintmap"] fn mk() -> smallintmap { let v: [mutable option] = [mutable]; ret @{mutable v: v}; } -/* -Function: insert - +#[doc = " Add a value to the map. If the map already contains a value for the specified key then the original value is replaced. -*/ +"] fn insert(m: smallintmap, key: uint, val: T) { vec::grow_set::>(m.v, key, none::, some::(val)); } -/* -Function: find - +#[doc = " Get the value for the specified key. If the key does not exist in the map then returns none -*/ +"] fn find(m: smallintmap, key: uint) -> option { if key < vec::len::>(m.v) { ret m.v[key]; } ret none::; } -/* -Method: get - +#[doc = " Get the value for the specified key -Failure: +# Failure If the key does not exist in the map -*/ +"] fn get(m: smallintmap, key: uint) -> T { alt find(m, key) { none { #error("smallintmap::get(): key not present"); fail; } @@ -61,11 +46,9 @@ fn get(m: smallintmap, key: uint) -> T { } } -/* -Method: contains_key - +#[doc = " Returns true if the map contains a value for the specified key -*/ +"] fn contains_key(m: smallintmap, key: uint) -> bool { ret !option::is_none(find::(m, key)); } @@ -80,11 +63,7 @@ fn max_key(m: smallintmap) -> uint { ret vec::len::>(m.v); } -/* -Impl: map - -Implements the map::map interface for smallintmap -*/ +#[doc = "Implements the map::map interface for smallintmap"] impl of map::map for smallintmap { fn size() -> uint { let sz = 0u; @@ -136,11 +115,7 @@ impl of map::map for smallintmap { } } -/* -Funtion: as_map - -Cast the given smallintmap to a map::map -*/ +#[doc = "Cast the given smallintmap to a map::map"] fn as_map(s: smallintmap) -> map::map { s as map::map:: } diff --git a/src/libstd/sort.rs b/src/libstd/sort.rs index 92e037f7f66..8a4d59d9cfa 100644 --- a/src/libstd/sort.rs +++ b/src/libstd/sort.rs @@ -1,25 +1,18 @@ -/* -Module: sort - -Sorting methods -*/ +#[doc = "Sorting methods"]; import vec::len; export merge_sort; export quick_sort; export quick_sort3; -/* Type: le */ type le = fn(T, T) -> bool; -/* -Function: merge_sort - +#[doc = " Merge sort. Returns a new vector containing the sorted list. Has worst case O(n log n) performance, best case O(n), but is not space efficient. This is a stable sort. -*/ +"] fn merge_sort(le: le, v: [const T]) -> [T] { type slice = (uint, uint); @@ -88,14 +81,12 @@ fn qsort(compare_func: le, arr: [mutable T], left: uint, } } -/* -Function: quick_sort - +#[doc = " Quicksort. Sorts a mutable vector in place. Has worst case O(n^2) performance, average case O(n log n). This is an unstable sort. -*/ +"] fn quick_sort(compare_func: le, arr: [mutable T]) { if len::(arr) == 0u { ret; } qsort::(compare_func, arr, 0u, len::(arr) - 1u); @@ -150,18 +141,16 @@ fn qsort3(compare_func_lt: le, compare_func_eq: le, } // FIXME: This should take lt and eq types -/* -Function: quick_sort3 - +#[doc = " Fancy quicksort. Sorts a mutable vector in place. -Based on algorithm presented by Sedgewick and Bentley -. +Based on algorithm presented by [Sedgewick and Bentley] +(http://www.cs.princeton.edu/~rs/talks/QuicksortIsOptimal.pdf). According to these slides this is the algorithm of choice for 'randomly ordered keys, abstract compare' & 'small number of key values'. This is an unstable sort. -*/ +"] fn quick_sort3(compare_func_lt: le, compare_func_eq: le, arr: [mutable T]) { if len::(arr) == 0u { ret; } diff --git a/src/libstd/std.rc b/src/libstd/std.rc index 83e4a04f0df..604e5cb63a7 100644 --- a/src/libstd/std.rc +++ b/src/libstd/std.rc @@ -7,6 +7,8 @@ #[license = "MIT"]; #[crate_type = "lib"]; +#[doc = "The Rust standard library"]; + export fs, io, net, run, uv; export c_vec, four, tri, util; export bitv, deque, fun_treemap, list, map, smallintmap, sort, treemap, ufind; diff --git a/src/libstd/tempfile.rs b/src/libstd/tempfile.rs index eaf1409da1d..c7e3e60ef20 100644 --- a/src/libstd/tempfile.rs +++ b/src/libstd/tempfile.rs @@ -1,17 +1,10 @@ -/* -Module: tempfile - -Temporary files and directories -*/ +#[doc = "Temporary files and directories"]; import core::option; import fs; import option::{none, some}; import rand; -/* -Function: mkdtemp -*/ fn mkdtemp(prefix: str, suffix: str) -> option { let r = rand::mk_rng(); let i = 0u; diff --git a/src/libstd/term.rs b/src/libstd/term.rs index eb9b977455d..e782abb8e6f 100644 --- a/src/libstd/term.rs +++ b/src/libstd/term.rs @@ -1,67 +1,37 @@ -/* -Module: term - -Simple ANSI color library -*/ +#[doc = "Simple ANSI color library"]; import core::option; // TODO: Windows support. -/* Const: color_black */ const color_black: u8 = 0u8; -/* Const: color_red */ const color_red: u8 = 1u8; -/* Const: color_green */ const color_green: u8 = 2u8; -/* Const: color_yellow */ const color_yellow: u8 = 3u8; -/* Const: color_blue */ const color_blue: u8 = 4u8; -/* Const: color_magenta */ const color_magenta: u8 = 5u8; -/* Const: color_cyan */ const color_cyan: u8 = 6u8; -/* Const: color_light_gray */ const color_light_gray: u8 = 7u8; -/* Const: color_light_grey */ const color_light_grey: u8 = 7u8; -/* Const: color_dark_gray */ const color_dark_gray: u8 = 8u8; -/* Const: color_dark_grey */ const color_dark_grey: u8 = 8u8; -/* Const: color_bright_red */ const color_bright_red: u8 = 9u8; -/* Const: color_bright_green */ const color_bright_green: u8 = 10u8; -/* Const: color_bright_yellow */ const color_bright_yellow: u8 = 11u8; -/* Const: color_bright_blue */ const color_bright_blue: u8 = 12u8; -/* Const: color_bright_magenta */ const color_bright_magenta: u8 = 13u8; -/* Const: color_bright_cyan */ const color_bright_cyan: u8 = 14u8; -/* Const: color_bright_white */ const color_bright_white: u8 = 15u8; fn esc(writer: io::writer) { writer.write([0x1bu8, '[' as u8]); } -/* -Function: reset - -Reset the foreground and background colors to default -*/ +#[doc = "Reset the foreground and background colors to default"] fn reset(writer: io::writer) { esc(writer); writer.write(['0' as u8, 'm' as u8]); } -/* -Function: color_supported - -Returns true if the terminal supports color -*/ +#[doc = "Returns true if the terminal supports color"] fn color_supported() -> bool { let supported_terms = ["xterm-color", "xterm", "screen-bce", "xterm-256color"]; @@ -84,20 +54,12 @@ fn set_color(writer: io::writer, first_char: u8, color: u8) { writer.write([first_char, ('0' as u8) + color, 'm' as u8]); } -/* -Function: fg - -Set the foreground color -*/ +#[doc = "Set the foreground color"] fn fg(writer: io::writer, color: u8) { ret set_color(writer, '3' as u8, color); } -/* -Function: fg - -Set the background color -*/ +#[doc = "Set the background color"] fn bg(writer: io::writer, color: u8) { ret set_color(writer, '4' as u8, color); } diff --git a/src/libstd/test.rs b/src/libstd/test.rs index 6f39ea14047..d8d14df667a 100644 --- a/src/libstd/test.rs +++ b/src/libstd/test.rs @@ -1,3 +1,5 @@ +#[doc(hidden)]; + // Support code for rustc's built in test runner generator. Currently, // none of this is meant for users. It is intended to support the // simplest interface possible for representing and running tests diff --git a/src/libstd/time.rs b/src/libstd/time.rs index aaf94657a8b..dcdc82434ab 100644 --- a/src/libstd/time.rs +++ b/src/libstd/time.rs @@ -1,26 +1,16 @@ -/* -Module: time -*/ - #[abi = "cdecl"] native mod rustrt { fn get_time(&sec: u32, &usec: u32); fn precise_time_ns(&ns: u64); } -/* -Type: timeval - -A record specifying a time value in seconds and microseconds. -*/ +#[doc = "A record specifying a time value in seconds and microseconds."] type timeval = {sec: u32, usec: u32}; -/* -Function: get_time - +#[doc = " Returns the current time as a `timeval` containing the seconds and microseconds since 1970-01-01T00:00:00Z. -*/ +"] fn get_time() -> timeval { let sec = 0u32; let usec = 0u32; @@ -28,20 +18,16 @@ fn get_time() -> timeval { ret {sec: sec, usec: usec}; } -/* -Function: precise_time_ns - +#[doc = " Returns the current value of a high-resolution performance counter in nanoseconds since an unspecified epoch. -*/ +"] fn precise_time_ns() -> u64 { let ns = 0u64; rustrt::precise_time_ns(ns); ns } -/* -Function: precise_time_s - +#[doc = " Returns the current value of a high-resolution performance counter in seconds since an unspecified epoch. -*/ +"] fn precise_time_s() -> float { ret (precise_time_ns() as float) / 1000000000.; } diff --git a/src/libstd/treemap.rs b/src/libstd/treemap.rs index 1647ea8f977..e8084ac4f5e 100644 --- a/src/libstd/treemap.rs +++ b/src/libstd/treemap.rs @@ -1,13 +1,10 @@ -/* -Module: treemap - +#[doc = " A key,value store that works on anything. This works using a binary search tree. In the first version, it's a very naive algorithm, but it will probably be updated to be a red-black tree or something else. - -*/ +"]; import core::option::{some, none}; import option = core::option; @@ -18,32 +15,14 @@ export insert; export find; export traverse; -/* Section: Types */ - -/* -Type: treemap -*/ type treemap = @mutable tree_node; -/* -Tag: tree_node -*/ enum tree_node { empty, node(@K, @V, treemap, treemap) } -/* Section: Operations */ - -/* -Function: init - -Create a treemap -*/ +#[doc = "Create a treemap"] fn init() -> treemap { @mutable empty } -/* -Function: insert - -Insert a value into the map -*/ +#[doc = "Insert a value into the map"] fn insert(m: treemap, k: K, v: V) { alt m { @empty { *m = node(@k, @v, @mutable empty, @mutable empty); } @@ -62,11 +41,7 @@ fn insert(m: treemap, k: K, v: V) { } } -/* -Function: find - -Find a value based on the key -*/ +#[doc = "Find a value based on the key"] fn find(m: treemap, k: K) -> option { alt *m { empty { none } @@ -81,11 +56,7 @@ fn find(m: treemap, k: K) -> option { } } -/* -Function: traverse - -Visit all pairs in the map in order. -*/ +#[doc = "Visit all pairs in the map in order."] fn traverse(m: treemap, f: fn(K, V)) { alt *m { empty { } diff --git a/src/libstd/tri.rs b/src/libstd/tri.rs index 5835dbf8c42..b40444a8a07 100644 --- a/src/libstd/tri.rs +++ b/src/libstd/tri.rs @@ -1,8 +1,6 @@ // -*- rust -*- -/* -Module: tri - +#[doc = " ADT for the ternary Kleene logic K3 This allows reasoning with three logic values (true, false, unknown). @@ -10,132 +8,85 @@ This allows reasoning with three logic values (true, false, unknown). Implementation: Truth values are represented using a single u8 and all operations are done using bit operations which is fast on current cpus. -*/ +"]; export t, true, false, unknown; export not, and, or, xor, implies, eq, ne, is_true, is_false; export from_str, to_str, all_values, to_bit; -/* -Type: t - -The type of ternary logic values -*/ +#[doc = "The type of ternary logic values"] type t = u8; const b0: u8 = 1u8; const b1: u8 = 2u8; const b01: u8 = 3u8; -/* -Constant: unknown - -Logic value for unknown (maybe true xor maybe false) -*/ +#[doc = "Logic value for unknown (maybe true xor maybe false)"] const unknown: t = 0u8; -/* -Constant: true - -Logic value for truth -*/ +#[doc = "Logic value for truth"] const true: t = 1u8; -/* -Constant: false - -Logic value for falsehood -*/ +#[doc = "Logic value for falsehood"] const false: t = 2u8; -/* Function: not - -Negation/Inverse -*/ +#[doc = "Negation/Inverse"] pure fn not(v: t) -> t { ((v << 1u8) | (v >> 1u8)) & b01 } -/* Function: and - -Conjunction -*/ +#[doc = "Conjunction"] pure fn and(a: t, b: t) -> t { ((a | b) & b1) | ((a & b) & b0) } -/* Function: or - -Disjunction -*/ +#[doc = "Disjunction"] pure fn or(a: t, b: t) -> t { ((a & b) & b1) | ((a | b) & b0) } -/* -Function: xor - -Exclusive or -*/ +#[doc = "Exclusive or"] pure fn xor(a: t, b: t) -> t { let anb = a & b; let aob = a & not(b); ret ((anb & b1) | (anb << 1u8) | (aob >> 1u8) | (aob & b0)) & b01; } -/* -Function: implies - -Classic implication, i.e. from `a` follows `b` -*/ +#[doc = "Classic implication, i.e. from `a` follows `b`"] pure fn implies(a: t, b: t) -> t { ret ((a & b1) >> 1u8) | (b & b0) | ((a << 1u8) & b & b1); } -/* -Predicate: eq - -Returns: +#[doc = " +# Return value true if truth values `a` and `b` are indistinguishable in the logic -*/ +"] pure fn eq(a: t, b: t) -> bool { a == b } -/* -Predicate: ne - -Returns: +#[doc = " +# Return value true if truth values `a` and `b` are distinguishable in the logic -*/ +"] pure fn ne(a: t, b: t) -> bool { a != b } -/* -Predicate: is_true - -Returns: +#[doc = " +# Return value true if `v` represents truth in the logic -*/ +"] pure fn is_true(v: t) -> bool { v == tri::true } -/* -Predicate: is_false - -Returns: +#[doc = " +# Return value true if `v` represents false in the logic -*/ +"] pure fn is_false(v: t) -> bool { v == tri::false } -/* -Predicate: is_unknown - -Returns: +#[doc = " +# Return value true if `v` represents the unknown state in the logic -*/ +"] pure fn is_unknown(v: t) -> bool { v == unknown } -/* -Function: from_str - -Parse logic value from `s` -*/ +#[doc = "Parse logic value from `s`"] pure fn from_str(s: str) -> t { alt check s { "unknown" { unknown } @@ -144,11 +95,7 @@ pure fn from_str(s: str) -> t { } } -/* -Function: to_str - -Convert `v` into a string -*/ +#[doc = "Convert `v` into a string"] pure fn to_str(v: t) -> str { // FIXME replace with consts as soon as that works alt check v { @@ -158,25 +105,21 @@ pure fn to_str(v: t) -> str { } } -/* -Function: all_values - +#[doc = " Iterates over all truth values by passing them to `blk` in an unspecified order -*/ +"] fn all_values(blk: fn(v: t)) { blk(tri::false); blk(unknown); blk(tri::true); } -/* -Function: to_bit - -Returns: +#[doc = " +# Return value An u8 whose first bit is set if `if_true(v)` holds -*/ +"] fn to_bit(v: t) -> u8 { v & b0 } #[cfg(test)] diff --git a/src/libstd/util.rs b/src/libstd/util.rs index 2be273f8ab9..fc0a326dee7 100644 --- a/src/libstd/util.rs +++ b/src/libstd/util.rs @@ -1,26 +1,11 @@ -/* -Module: util -*/ - -/* -Function: id - -The identity function -*/ +#[doc = "The identity function"] pure fn id(x: T) -> T { x } /* FIXME (issue #141): See test/run-pass/constrained-type.rs. Uncomment * the constraint once fixed. */ -/* -Function: rational - -A rational number -*/ +#[doc = "A rational number"] type rational = {num: int, den: int}; // : int::positive(*.den); -/* -Function: rational_leq -*/ pure fn rational_leq(x: rational, y: rational) -> bool { // NB: Uses the fact that rationals have positive denominators WLOG: