libstd: Update docs

9 files changed, 177 insertions, 13 deletions

diff --git a/src/libstd/c_vec.rs b/src/libstd/c_vec.rs
index ff5f636d103..7c2f1be7084 100644
--- a/src/libstd/c_vec.rs
+++ b/src/libstd/c_vec.rs
@@ -57,6 +57,16 @@ resource dtor_res(dtor: option::t<fn@()>) {
  Section: Introduction forms
  */
 
+/*
+Function: create
+
+Create a c_vec::t from a native buffer with a given size.
+
+Parameters:
+
+base - A native pointer to a buffer
+size - The number of elements in the buffer
+*/
 unsafe fn create<T>(base: *mutable T, size: uint) -> t<T> {
     ret t({base: base,
            size: size,
@@ -64,6 +74,19 @@ unsafe fn create<T>(base: *mutable T, size: uint) -> t<T> {
           });
 }
 
+/*
+Function: create_with_dtor
+
+Create a c_vec::t from a native buffer, with a given size,
+and a function to run upon destruction.
+
+Parameters:
+
+base - A native pointer to a buffer
+size - 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<T>(base: *mutable T, size: uint, dtor: fn@())
   -> t<T> {
     ret t({base: base,
@@ -76,11 +99,29 @@ unsafe fn create_with_dtor<T>(base: *mutable T, size: uint, dtor: fn@())
  Section: Operations
  */
 
+/*
+Function: get
+
+Retrieves an element at a given index
+
+Failure:
+
+If `ofs` is greater or equal to the length of the vector
+*/
 fn get<copy T>(t: t<T>, ofs: uint) -> T {
     assert ofs < (*t).size;
     ret unsafe { *ptr::mut_offset((*t).base, ofs) };
 }
 
+/*
+Function: set
+
+Sets the value of an element at a given index
+
+Failure:
+
+If `ofs` is greater or equal to the length of the vector
+*/
 fn set<copy T>(t: t<T>, ofs: uint, v: T) {
     assert ofs < (*t).size;
     unsafe { *ptr::mut_offset((*t).base, ofs) = v };
@@ -90,10 +131,21 @@ fn set<copy T>(t: t<T>, ofs: uint, v: T) {
  Section: Elimination forms
  */
 
+// FIXME: Rename to len
+/*
+Function: size
+
+Returns the length of the vector
+*/
 fn size<T>(t: t<T>) -> uint {
     ret (*t).size;
 }
 
+/*
+Function: ptr
+
+Returns a pointer to the first element of the vector
+*/
 unsafe fn ptr<T>(t: t<T>) -> *mutable T {
     ret (*t).base;
 }
diff --git a/src/libstd/ctypes.rs b/src/libstd/ctypes.rs
index 82e414a864c..509eb3ef057 100644
--- a/src/libstd/ctypes.rs
+++ b/src/libstd/ctypes.rs
@@ -4,39 +4,143 @@ Module: ctypes
 Definitions useful for C interop
 */
 
+/*
+FIXME: Add a test that uses some native code to verify these sizes,
+which are not obviously correct for all potential platforms.
+*/
+
+/*
+Type: c_int
+
+A signed integer with the same size as a C `int`
+*/
 type c_int = i32;
+
+/*
+Type: c_uint
+
+An unsigned integer with the same size as a C `unsigned int`
+*/
 type c_uint = u32;
 
-type void = int; // Not really the same as C
+/*
+Type: long
+
+A signed integer with the same size as a C `long`
+*/
 type long = int;
+
+/*
+Type: unsigned
+
+An unsigned integer with the same size as a C `unsigned int`
+*/
 type unsigned = u32;
+
+/*
+Type: ulong
+
+An unsigned integer with the same size as a C `unsigned long`
+*/
 type ulong = uint;
 
-type intptr_t = uint;
+/*
+Type: intptr_t
+
+A signed integer with the same size as a pointer. This is
+guaranteed to always be the same type as a Rust `int`
+*/
+type intptr_t = uint; // FIXME: int
+
+/*
+Type: uintptr_t
+
+An unsigned integer with the same size as a pointer. This is
+guaranteed to always be the same type as a Rust `uint`.
+*/
 type uintptr_t = uint;
 type uint32_t = u32;
 
+/*
+Type: void
+
+A type, a pointer to which can be used as C `void *`
+
+Note that this does not directly correspond to the C `void` type,
+which is an incomplete type. Using pointers to this type
+when interoperating with C void pointers can help in documentation.
+*/
+type void = int;
+
 // machine type equivalents of rust int, uint, float
 
+/*
+Type: m_int
+
+FIXME: What C type does this represent?
+*/
 #[cfg(target_arch="x86")]
 type m_int = i32;
 #[cfg(target_arch="x86_64")]
 type m_int = i64;
 
+/*
+Type: m_uint
+
+FIXME: What C type does this represent?
+*/
 #[cfg(target_arch="x86")]
 type m_uint = u32;
 #[cfg(target_arch="x86_64")]
 type m_uint = u64;
 
 // This *must* match with "import m_float = fXX" in std::math per arch
+/*
+Type: m_float
+
+FIXME: What C type does this represent?
+*/
 type m_float = f64;
 
+/*
+Type: size_t
+
+An unsigned integer corresponding to the C `size_t`
+*/
 type size_t = uint;
+
+/*
+Type: ssize_t
+
+A signed integer correpsonding to the C `ssize_t`
+*/
 type ssize_t = int;
+
+/*
+Type: off_t
+
+An unsigned integer corresponding to the C `off_t`
+*/
 type off_t = uint;
 
+/*
+Type: fd_t
+
+A type that can be used for C file descriptors
+*/
 type fd_t = i32;      // not actually a C type, but should be.
+
+/*
+Type: pid_t
+
+A type for representing process ID's, corresponding to C `pid_t`
+*/
 type pid_t = i32;
 
 // enum is implementation-defined, but is 32-bits in practice
+/*
+Type: enum
+
+An unsigned integer with the same size as a C enum
+*/
 type enum = u32;
diff --git a/src/libstd/float.rs b/src/libstd/float.rs
index f916e97bbf8..015dceb1dc1 100644
--- a/src/libstd/float.rs
+++ b/src/libstd/float.rs
@@ -253,25 +253,18 @@ fn pow_uint_to_uint_as_float(x: uint, pow: uint) -> float {
 }
 
 
-/**
- * Section: Constants
- */
-
-//TODO: Once this is possible, replace the body of these functions
-//by an actual constant.
-
 /* Const: NaN */
 const NaN: float = 0./0.;
 
-/* Predicate: isNaN */
-pure fn isNaN(f: float) -> bool { f != f }
-
 /* Const: infinity */
 const infinity: float = 1./0.;
 
 /* Const: neg_infinity */
 const neg_infinity: float = -1./0.;
 
+/* Predicate: isNaN */
+pure fn isNaN(f: float) -> bool { f != f }
+
 /* Function: add */
 pure fn add(x: float, y: float) -> float { ret x + y; }
 
diff --git a/src/libstd/io.rs b/src/libstd/io.rs
index 910ec8bb9ea..06e1be2fc4b 100644
--- a/src/libstd/io.rs
+++ b/src/libstd/io.rs
@@ -1,3 +1,9 @@
+/*
+Module: io
+
+Basic input/output
+*/
+
 import ctypes::fd_t;
 import ctypes::c_int;
 
diff --git a/src/libstd/math.rs b/src/libstd/math.rs
index 72056548ca5..31bfe2ba3a6 100644
--- a/src/libstd/math.rs
+++ b/src/libstd/math.rs
@@ -23,6 +23,9 @@ import ctypes::c_int;
 import m_float = math_f64;
 
 // FIXME replace with redirect to m_float::consts::FOO as soon as it works
+/*
+Module: consts
+*/
 mod consts {
     /*
     Const: pi
diff --git a/src/libstd/math_f32.rs b/src/libstd/math_f32.rs
index 2172c9f8a99..6c36db51a67 100644
--- a/src/libstd/math_f32.rs
+++ b/src/libstd/math_f32.rs
@@ -17,6 +17,7 @@ export
 
 export consts;
 
+/* Module: consts */
 mod consts {
 
     /*
diff --git a/src/libstd/math_f64.rs b/src/libstd/math_f64.rs
index 639dc4a29b2..cc8fad9f665 100644
--- a/src/libstd/math_f64.rs
+++ b/src/libstd/math_f64.rs
@@ -17,6 +17,7 @@ export
 
 export consts;
 
+/* Module: consts */
 mod consts {
 
     /*
diff --git a/src/libstd/str.rs b/src/libstd/str.rs
index fb24c59f62f..2bae8d699a5 100644
--- a/src/libstd/str.rs
+++ b/src/libstd/str.rs
@@ -174,7 +174,8 @@ fn byte_len_range(s: str, byte_offset: uint, char_len: uint) -> uint {
 /*
 Function: bytes
 
-Converts a string to a vector of bytes
+Converts a string to a vector of bytes. The result vector is not
+null-terminated.
 */
 fn bytes(s: str) -> [u8] unsafe {
     let v = unsafe::reinterpret_cast(s);
diff --git a/src/libstd/tempfile.rs b/src/libstd/tempfile.rs
index 5f504ba2349..ee7d5e3b2d9 100644
--- a/src/libstd/tempfile.rs
+++ b/src/libstd/tempfile.rs
@@ -9,6 +9,9 @@ import option;
 import option::{none, some};
 import rand;
 
+/*
+Function: mkdtemp
+*/
 fn mkdtemp(prefix: str, suffix: str) -> option::t<str> {
     let r = rand::mk_rng();
     let i = 0u;