Add more std docs

src/lib/term.rs

@@ -1,52 +1,65 @@
+/*
+Module: term
 
+Simple ANSI color library
+*/
 
-
-// Simple ANSI color library.
-//
 // 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::buf_writer) { writer.write([0x1bu8, '[' as u8]); }
 
+/*
+Function: reset
+
+Reset the foreground and background colors to default
+*/
 fn reset(writer: io::buf_writer) {
     esc(writer);
     writer.write(['0' as u8, 'm' as u8]);
 }
 
+/*
+Function: color_supported
+
+Returns true if the terminal supports color
+*/
 fn color_supported() -> bool {
     let supported_terms = ["xterm-color", "xterm", "screen-bce"];
     ret alt generic_os::getenv("TERM") {
@@ -67,15 +80,23 @@ fn set_color(writer: io::buf_writer, first_char: u8, color: u8) {
     writer.write([first_char, ('0' as u8) + color, 'm' as u8]);
 }
 
+/*
+Function: fg
+
+Set the foreground color
+*/
 fn fg(writer: io::buf_writer, color: u8) {
     ret set_color(writer, '3' as u8, color);
 }
 
+/*
+Function: fg
+
+Set the background color
+*/
 fn bg(writer: io::buf_writer, color: u8) {
     ret set_color(writer, '4' as u8, color);
 }
-// export fg;
-// export bg;
 
 // Local Variables:
 // fill-column: 78;

src/lib/time.rs

@@ -1,12 +1,18 @@
+/*
+Module: time
+*/
 
+// FIXME: Document what these functions do
 
 native "c-stack-cdecl" mod rustrt {
     fn get_time(&sec: u32, &usec: u32);
     fn nano_time(&ns: u64);
 }
 
+/* Type: timeval */
 type timeval = {sec: u32, usec: u32};
 
+/* Function: get_time */
 fn get_time() -> timeval {
     let sec = 0u32;
     let usec = 0u32;
@@ -14,8 +20,10 @@ fn get_time() -> timeval {
     ret {sec: sec, usec: usec};
 }
 
+/* Function: precise_time_ns */
 fn precise_time_ns() -> u64 { let ns = 0u64; rustrt::nano_time(ns); ret ns; }
 
+/* Function: precise_time_s */
 fn precise_time_s() -> float {
     ret (precise_time_ns() as float) / 1000000000.;
 }

src/lib/u32.rs

@@ -1,6 +1,21 @@
-pure fn max_value() -> u32 { ret 4294967296u32; }
+/*
+Module: u32
+*/
+
+/*
+Function: min_value
+
+Return the minimal value for a u32
+*/
 pure fn min_value() -> u32 { ret 0u32; }
 
+/*
+Function: max_value
+
+Return the maximal value for a u32
+*/
+pure fn max_value() -> u32 { ret 4294967296u32; }
+
 //
 // Local Variables:
 // mode: rust

src/lib/u64.rs

@@ -1,6 +1,26 @@
-pure fn max_value() -> u64 { ret 18446744073709551615u64; }
+/*
+Module: u64
+*/
+
+/*
+Function: min_value
+
+Return the minimal value for a u64
+*/
 pure fn min_value() -> u64 { ret 0u64; }
 
+/*
+Function: max_value
+
+Return the maximal value for a u64
+*/
+pure fn max_value() -> u64 { ret 18446744073709551615u64; }
+
+/*
+Function: to_str
+
+Convert to a string in a given base
+*/
 fn to_str(n: u64, radix: uint) -> str {
     assert (0u < radix && radix <= 16u);
 
@@ -36,4 +56,9 @@ fn to_str(n: u64, radix: uint) -> str {
     ret s;
 }
 
+/*
+Function: str
+
+Convert to a string
+*/
 fn str(n: u64) -> str { ret to_str(n, 10u); }

src/lib/u8.rs

@@ -49,6 +49,11 @@ pure fn ge(x: u8, y: u8) -> bool { ret x >= y; }
 /* Predicate: gt */
 pure fn gt(x: u8, y: u8) -> bool { ret x > y; }
 
+/*
+Function: range
+
+Iterate over the range [`lo`..`hi`)
+*/
 fn range(lo: u8, hi: u8, it: block(u8)) {
     while lo < hi { it(lo); lo += 1u8; }
 }

src/lib/unsafe.rs

@@ -1,4 +1,8 @@
-// Unsafe operations.
+/*
+Module: unsafe
+
+Unsafe operations
+*/
 
 native "rust-intrinsic" mod rusti {
     fn cast<T, U>(src: T) -> U;
@@ -8,7 +12,21 @@ native "c-stack-cdecl" mod rustrt {
     fn leak<T>(-thing: T);
 }
 
-// Casts the value at `src` to U. The two types must have the same length.
+/*
+Function: reinterpret_cast
+
+Casts the value at `src` to U. The two types must have the same length.
+*/
 fn reinterpret_cast<T, U>(src: T) -> U { ret rusti::cast(src); }
 
+/*
+Function: leak
+
+Move `thing` into the void.
+
+The leak function will take ownership of the provided value but neglect
+to run any required cleanup or memory-management operations on it. This
+can be used for various acts of magick, particularly when using
+reinterpret_cast on managed pointer types.
+*/
 fn leak<T>(-thing: T) { rustrt::leak(thing); }

src/lib/util.rs

@@ -1,23 +1,49 @@
+/*
+Module: util
+*/
 
+/*
+Function: id
+
+The identity function
+*/
 pure fn id<T>(x: T) -> T { x }
 
+/*
+Function: unreachable
+
+A standard function to use to indicate unreachable code. Because the
+function is guaranteed to fail typestate will correctly identify
+any code paths following the appearance of this function as unreachable.
+*/
 fn unreachable() -> ! {
     fail "Internal error: entered unreachable code";
 }
 
 /* FIXME (issue #141):  See test/run-pass/constrained-type.rs.  Uncomment
  * the constraint once fixed. */
+/*
+Function: rational
+
+A rational number
+*/
 type rational = {num: int, den: int}; // : int::positive(*.den);
 
-// : 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:
 
     x.num * y.den <= y.num * x.den
 }
 
+/*
+Function: orb
+*/
 pure fn orb(a: bool, b: bool) -> bool { a || b }
 
+// FIXME: Document what this is for or delete it
 tag void {
     void(@void);
 }