core: Docs

src/libcore/path.rs

@@ -1,10 +1,36 @@
-#[doc = "Path data type and helper functions"]
+#[doc = "Path data type and helper functions"];
+
+export path;
+export consts;
+export path_is_absolute;
+export path_sep;
+export dirname;
+export basename;
+export connect;
+export connect_many;
+export split;
+export splitext;
+export normalize;
+
+// FIXME: This type should probably be constrained
+#[doc = "A path or fragment of a filesystem path"]
+type path = str;
 
 #[cfg(target_os = "macos")]
 #[cfg(target_os = "freebsd")]
 #[cfg(target_os = "linux")]
 mod consts {
+    #[doc = "
+    The primary path seperator character for the platform
+
+    On all platforms it is '/'
+    "]
     const path_sep: char = '/';
+    #[doc = "
+    The secondary path seperator character for the platform
+
+    On Unixes it is '/'. On Windows it is '\\'.
+    "]
     const alt_path_sep: char = '/';
 }
 
@@ -35,15 +61,9 @@ fn path_is_absolute(p: str) -> bool {
             || str::char_at(p, 2u) == consts::alt_path_sep);
 }
 
-
-
 #[doc = "Get the default path separator for the host platform"]
 fn path_sep() -> str { ret str::from_char(consts::path_sep); }
 
-// FIXME: This type should probably be constrained
-#[doc = "A path or fragment of a filesystem path"]
-type path = str;
-
 fn split_dirname_basename (pp: path) -> {dirname: str, basename: str} {
     alt str::rfind(pp, {|ch|
         ch == consts::path_sep || ch == consts::alt_path_sep

src/libcore/rand.rs

@@ -1,4 +1,6 @@
-#[doc = "Random number generation"]
+#[doc = "Random number generation"];
+
+export rng;
 
 enum rctx {}
 

src/libcore/str.rs

@@ -961,6 +961,7 @@ fn is_utf8(v: [const u8]) -> bool {
     ret true;
 }
 
+#[doc = "Determines if a vector of `u16` contains valid UTF-16"]
 fn is_utf16(v: [const u16]) -> bool {
     let len = v.len();
     let mut i = 0u;
@@ -981,6 +982,7 @@ fn is_utf16(v: [const u16]) -> bool {
     ret true;
 }
 
+#[doc = "Converts to a vector of `u16` encoded as UTF-16"]
 fn to_utf16(s: str) -> [u16] {
     let mut u = [];
     chars_iter(s) {|cch|
@@ -1200,7 +1202,7 @@ Loop through a substring, char by char
 # Safety note
 
 * This function does not check whether the substring is valid.
-* This function fails if `byte_offset` or `byte_len` do not
+* This function fails if `start` or `end` do not
   represent valid positions inside `s`
 
 # Arguments
@@ -1227,6 +1229,27 @@ fn all_between(s: str, start: uint, end: uint, it: fn(char) -> bool) -> bool {
     ret true;
 }
 
+#[doc = "
+Loop through a substring, char by char
+
+# Safety note
+
+* This function does not check whether the substring is valid.
+* This function fails if `start` or `end` do not
+  represent valid positions inside `s`
+
+# Arguments
+
+* s - A string to traverse. It may be empty.
+* start - The byte offset at which to start in the string.
+* end - The end of the range to traverse
+* it - A block to execute with each consecutive character of `s`.
+       Return `true` to continue, `false` to stop.
+
+# Return value
+
+`true` if `it` returns `true` for any character
+"]
 fn any_between(s: str, start: uint, end: uint, it: fn(char) -> bool) -> bool {
     !all_between(s, start, end, {|c| !it(c)})
 }

src/libcore/tuple.rs

@@ -1,13 +1,18 @@
+#[doc = "Operations on tuples"];
+
+#[doc = "Return the first element of a pair"]
 pure fn first<T:copy, U:copy>(pair: (T, U)) -> T {
     let (t, _) = pair;
     ret t;
 }
 
+#[doc = "Return the second element of a pair"]
 pure fn second<T:copy, U:copy>(pair: (T, U)) -> U {
     let (_, u) = pair;
     ret u;
 }
 
+#[doc = "Return the results of swapping the two elements of a pair"]
 pure fn swap<T:copy, U:copy>(pair: (T, U)) -> (U, T) {
     let (t, u) = pair;
     ret (u, t);

src/libcore/vec.rs

@@ -1,3 +1,5 @@
+#[doc = "Vectors"];
+
 import option::{some, none};
 import uint::next_power_of_two;
 import ptr::addr_of;
@@ -396,7 +398,7 @@ fn grow_set<T: copy>(&v: [mutable T], index: uint, initval: T, val: T) {
 
 // Functional utilities
 
-#[doc ="
+#[doc = "
 Apply a function to each element of a vector and return the results
 "]
 fn map<T, U>(v: [T], f: fn(T) -> U) -> [U] {
@@ -406,6 +408,10 @@ fn map<T, U>(v: [T], f: fn(T) -> U) -> [U] {
     ret result;
 }
 
+#[doc = "
+Apply a function eo each element of a vector and return a concatenation
+of each result vector
+"]
 fn flat_map<T, U>(v: [T], f: fn(T) -> [U]) -> [U] {
     let mut result = [];
     for elem: T in v { result += f(elem); }
@@ -413,8 +419,6 @@ fn flat_map<T, U>(v: [T], f: fn(T) -> [U]) -> [U] {
 }
 
 #[doc = "
-Function: map2
-
 Apply a function to each pair of elements and return the results
 "]
 fn map2<T: copy, U: copy, V>(v0: [const T], v1: [const U],
@@ -860,13 +864,17 @@ fn as_mut_buf<E,T>(v: [mutable E], f: fn(*mutable E) -> T) -> T unsafe {
     let buf = unsafe::to_ptr(v) as *mutable E; f(buf)
 }
 
+#[doc = "An extension implementation providing a `len` method"]
 impl vec_len<T> for [T] {
+    #[doc = "Return the length of the vector"]
     #[inline(always)]
     fn len() -> uint { len(self) }
 }
 
+#[doc = "Unsafe operations"]
 mod unsafe {
     // FIXME: This should have crate visibility
+    #[doc = "The internal representation of a vector"]
     type vec_repr = {mutable fill: uint, mutable alloc: uint, data: u8};
 
     #[doc = "
@@ -912,6 +920,7 @@ mod unsafe {
     }
 }
 
+#[doc = "Operations on `[u8]`"]
 mod u8 {
     export cmp;
     export lt, le, eq, ne, ge, gt;