Add more std documentation

doc/Languages.txt

@@ -122,3 +122,4 @@ Language: Rust
    Function Prototype Enders: ; {
    Type Prototype Enders: ; }
    Class Prototype Enders: {
+   Variant Prototype Enders: ;

src/lib/list.rs

@@ -1,7 +1,30 @@
+/*
+Module: list
+
+A standard linked list
+*/
+
 import option::{some, none};
 
-tag list<T> { cons(T, @list<T>); nil; }
+/* Section: Types */
 
+/*
+Tag: list
+*/
+tag list<T> {
+    /* Variant: cons */
+    cons(T, @list<T>);
+    /* Variant: nil */
+    nil;
+}
+
+/*Section: Operations */
+
+/*
+Function: from_vec
+
+Create a list from a vector
+*/
 fn from_vec<T>(v: [T]) -> list<T> {
     let l = nil::<T>;
     // FIXME: This would be faster and more space efficient if it looped over
@@ -12,6 +35,21 @@ fn from_vec<T>(v: [T]) -> list<T> {
     ret l;
 }
 
+/*
+Function: foldl
+
+Left fold
+
+Applies `f` to the first argument in the list and `u`, then applies
+`f` to the second argument and the result of the previous call,
+and so on, returning the accumulated result.
+
+Parameters:
+
+ls_ - The list to fold
+u - The initial value
+f - The function to apply
+*/
 fn foldl<T, U>(ls_: list<T>, u: U, f: block(T, U) -> U) -> U {
     let accum: U = u;
     let ls = ls_;
@@ -24,6 +62,15 @@ fn foldl<T, U>(ls_: list<T>, u: U, f: block(T, U) -> U) -> U {
     ret accum;
 }
 
+/*
+Function: find
+
+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<T, U>(ls_: list<T>, f: block(T) -> option::t<U>) -> option::t<U> {
     let ls = ls_;
     while true {
@@ -37,6 +84,11 @@ fn find<T, U>(ls_: list<T>, f: block(T) -> option::t<U>) -> option::t<U> {
     ret none;
 }
 
+/*
+Function: has
+
+Returns true if a list contains an element with the given value
+*/
 fn has<T>(ls_: list<T>, elt: T) -> bool {
     let ls = ls_;
     while true {
@@ -48,19 +100,39 @@ fn has<T>(ls_: list<T>, elt: T) -> bool {
     ret false;
 }
 
+/*
+Function: length
+
+Returns the length of a list
+*/
 fn length<T>(ls: list<T>) -> uint {
     fn count<T>(_t: T, &&u: uint) -> uint { ret u + 1u; }
     ret foldl(ls, 0u, bind count(_, _));
 }
 
+/*
+Function: cdr
+
+Returns all but the first element of a list
+*/
 fn cdr<T>(ls: list<T>) -> list<T> {
     alt ls { cons(_, tl) { ret *tl; } nil. { fail "list empty" } }
 }
 
+/*
+Function: car
+
+Returns the first element of a list
+*/
 fn car<T>(ls: list<T>) -> T {
     alt ls { cons(hd, _) { ret hd; } nil. { fail "list empty" } }
 }
 
+/*
+Function: append
+
+Appends one list to another
+*/
 fn append<T>(l: list<T>, m: list<T>) -> list<T> {
     alt l {
       nil. { ret m; }

src/lib/map.rs

@@ -1,27 +1,119 @@
-/**
- * Hashmap implementation.
+/*
+Module: map
+
+A hashmap
+*/
+
+/* Section: Types */
+
+/*
+Type: hashfn
+
+A function that returns a hash of a value
 */
 type hashfn<K> = fn(K) -> uint;
 
+/*
+Type: eqfn
+
+Equality
+*/
 type eqfn<K> = fn(K, K) -> bool;
 
-type hashmap<K, V> =
-    obj {
-        fn size() -> uint;
-        fn insert(K, V) -> bool;
-        fn contains_key(K) -> bool;
-        fn get(K) -> V;
-        fn find(K) -> option::t<V>;
-        fn remove(K) -> option::t<V>;
-        fn rehash();
-        fn items(block(K, V));
-        fn keys(block(K));
-        fn values(block(V));
-    };
+/*
+Type: hashset
+
+A convenience type to treat a hashmap as a set
+*/
 type hashset<K> = hashmap<K, ()>;
 
-fn set_add<K>(set: hashset<K>, key: K) -> bool { ret set.insert(key, ()); }
+/*
+Obj: hashmap
+*/
+type hashmap<K, V> = obj {
+    /*
+    Method: size
 
+    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.
+
+    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
+    */
+    fn contains_key(K) -> bool;
+    /*
+    Method: get
+
+    Get the value for the specified key
+
+    Failure:
+
+    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.
+    */
+    fn find(K) -> option::t<V>;
+    /*
+    Method: remove
+
+    Remove and return a value from the map. If the key does not exist
+    in the map then returns none.
+    */
+    fn remove(K) -> option::t<V>;
+    /*
+    Method: rehash
+
+    Force map growth and rehashing
+    */
+    fn rehash();
+    /*
+    Method: items
+
+    Iterate over all the key/value pairs in the map
+    */
+    fn items(block(K, V));
+    /*
+    Method: keys
+
+    Iterate over all the keys in the map
+    */
+    fn keys(block(K));
+    /*
+    Iterate over all the values in the map
+    */
+    fn values(block(V));
+};
+
+/* Section: Operations */
+
+/*
+Function: mk_hashmap
+
+Construct a hashmap
+
+Parameters:
+
+hasher - The hash function for key type K
+eqer - The equality function for key type K
+*/
 fn mk_hashmap<K, V>(hasher: hashfn<K>, eqer: eqfn<K>) -> hashmap<K, V> {
     let initial_capacity: uint = 32u; // 2^5
 
@@ -194,24 +286,44 @@ fn mk_hashmap<K, V>(hasher: hashfn<K>, eqer: eqfn<K>) -> hashmap<K, V> {
     ret hashmap(hasher, eqer, bkts, initial_capacity, 0u, load_factor);
 }
 
-// Hash map constructors for basic types
+/*
+Function: new_str_hash
 
+Construct a hashmap for string keys
+*/
 fn new_str_hash<V>() -> hashmap<str, V> {
     ret mk_hashmap(str::hash, str::eq);
 }
 
+/*
+Function: new_int_hash
+
+Construct a hashmap for int keys
+*/
 fn new_int_hash<V>() -> hashmap<int, V> {
     fn hash_int(&&x: int) -> uint { ret x as uint; }
     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
+*/
 fn new_uint_hash<V>() -> hashmap<uint, V> {
     fn hash_uint(&&x: uint) -> uint { ret x; }
     fn eq_uint(&&a: uint, &&b: uint) -> bool { ret a == b; }
     ret mk_hashmap(hash_uint, eq_uint);
 }
 
+/*
+Function: set_add
+
+Convenience function for adding keys to a hashmap with nil type keys
+*/
+fn set_add<K>(set: hashset<K>, key: K) -> bool { ret set.insert(key, ()); }
+
 // Local Variables:
 // mode: rust;
 // fill-column: 78;

src/lib/math.rs

@@ -1,3 +1,5 @@
+/* Module: math */
+
 native "llvm" mod llvm {
     fn sqrt(n: float) -> float = "sqrt.f64";
     fn sin(n: float) -> float = "sin.f64";

src/lib/vec.rs

@@ -36,6 +36,11 @@ fn reserve<T>(&v: [mutable? T], n: uint) {
     rustrt::vec_reserve_shared(sys::get_type_desc::<T>(), v, n);
 }
 
+/*
+Function: len
+
+Returns the length of a vector
+*/
 pure fn len<T>(v: [mutable? T]) -> uint { unchecked { rusti::vec_len(v) } }
 
 /*
@@ -479,7 +484,7 @@ Function: find
 Search for an element that matches a given predicate
 
 Apply function `f` to each element of `v`, starting from the first.
-When function `f` matches then an option containing the element
+When function `f` returns true then an option containing the element
 is returned. If `f` matches no elements then none is returned.
 */
 fn find<T>(f: block(T) -> bool, v: [T]) -> option::t<T> {