From 389f53c6ffa79ad8194f1b53422e0679fbc672a9 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Thu, 15 Mar 2012 18:58:14 -0700 Subject: [PATCH] core: Docs --- src/libcore/path.rs | 34 +++++++++++++++++++++++++++------- src/libcore/rand.rs | 4 +++- src/libcore/str.rs | 25 ++++++++++++++++++++++++- src/libcore/tuple.rs | 5 +++++ src/libcore/vec.rs | 15 ++++++++++++--- 5 files changed, 71 insertions(+), 12 deletions(-) diff --git a/src/libcore/path.rs b/src/libcore/path.rs index 4e0d64b6d44..0e33a0e30b5 100644 --- a/src/libcore/path.rs +++ b/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 diff --git a/src/libcore/rand.rs b/src/libcore/rand.rs index 938720755d2..a2e985ba008 100644 --- a/src/libcore/rand.rs +++ b/src/libcore/rand.rs @@ -1,4 +1,6 @@ -#[doc = "Random number generation"] +#[doc = "Random number generation"]; + +export rng; enum rctx {} diff --git a/src/libcore/str.rs b/src/libcore/str.rs index 05b097079d9..9fb3517d8cf 100644 --- a/src/libcore/str.rs +++ b/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)}) } diff --git a/src/libcore/tuple.rs b/src/libcore/tuple.rs index e7fdaf8f2ba..98840dadc11 100644 --- a/src/libcore/tuple.rs +++ b/src/libcore/tuple.rs @@ -1,13 +1,18 @@ +#[doc = "Operations on tuples"]; + +#[doc = "Return the first element of a pair"] pure fn first(pair: (T, U)) -> T { let (t, _) = pair; ret t; } +#[doc = "Return the second element of a pair"] pure fn second(pair: (T, U)) -> U { let (_, u) = pair; ret u; } +#[doc = "Return the results of swapping the two elements of a pair"] pure fn swap(pair: (T, U)) -> (U, T) { let (t, u) = pair; ret (u, t); diff --git a/src/libcore/vec.rs b/src/libcore/vec.rs index 795da4d7026..30609fe9c3c 100644 --- a/src/libcore/vec.rs +++ b/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(&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(v: [T], f: fn(T) -> U) -> [U] { @@ -406,6 +408,10 @@ fn map(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(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(v: [T], f: fn(T) -> [U]) -> [U] { } #[doc = " -Function: map2 - Apply a function to each pair of elements and return the results "] fn map2(v0: [const T], v1: [const U], @@ -860,13 +864,17 @@ fn as_mut_buf(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 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;