Merge branch 'libgen-doc' into 'master'

add descriptions to libgen functions

See merge request redox-os/relibc!1468

src/byte_literal.rs

@@ -15,7 +15,7 @@ impl ByteLiteral {
     /// - Octal: `040`..=`176`
     /// - Decimal: `30`..=`126`
     /// - Hexadecimal: `20`..=`7E`
-    /// - Byte literals: b` `..=b`~`
+    /// - Byte literals: The space character (` `) upto and including tilde (`~`)
     pub fn cast_cchar(input: u8) -> c_char {
         match input {
             b' '..=b'~' => {

src/header/libgen/mod.rs

@@ -5,49 +5,60 @@
 use crate::{byte_literal::ByteLiteral, header::string::strlen, platform::types::c_char};
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/basename.html>.
+///
+/// Takes the pathname pointed to by `path` and returns a pointer to the final
+/// component of the pathname, deleting any trailing `/` characters.
+///
+/// Always successful. The return value never represents an error.
 #[unsafe(no_mangle)]
-pub unsafe extern "C" fn basename(str: *mut c_char) -> *mut c_char {
-    if str.is_null() || unsafe { strlen(str) == 0 } {
+pub unsafe extern "C" fn basename(path: *mut c_char) -> *mut c_char {
+    if path.is_null() || unsafe { strlen(path) == 0 } {
         return c".".as_ptr().cast_mut();
     }
-    let mut end = unsafe { strlen(str) as isize - 1 };
-    while end >= 0 && unsafe { *str.offset(end) == ByteLiteral::cast_cchar(b'/') } {
+    let mut end = unsafe { strlen(path) as isize - 1 };
+    while end >= 0 && unsafe { *path.offset(end) == ByteLiteral::cast_cchar(b'/') } {
         end -= 1;
     }
     if end == -1 {
         return c"/".as_ptr().cast_mut();
     }
     let mut begin = end;
-    while begin >= 0 && unsafe { *str.offset(begin) != ByteLiteral::cast_cchar(b'/') } {
+    while begin >= 0 && unsafe { *path.offset(begin) != ByteLiteral::cast_cchar(b'/') } {
         begin -= 1;
     }
     unsafe {
-        *str.offset(end + 1) = 0;
-        str.offset(begin + 1).cast::<c_char>()
+        *path.offset(end + 1) = 0;
+        path.offset(begin + 1).cast::<c_char>()
     }
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/dirname.html>.
+///
+/// Takes a pointer to a character string that contains a pathname, and return
+/// a pointer to a string that is a pathname of the directory containing the
+/// entry of the final pathname component.
+///
+/// Always successful. The return value never represents an error.
 #[unsafe(no_mangle)]
-pub unsafe extern "C" fn dirname(str: *mut c_char) -> *mut c_char {
-    if str.is_null() || unsafe { strlen(str) == 0 } {
+pub unsafe extern "C" fn dirname(path: *mut c_char) -> *mut c_char {
+    if path.is_null() || unsafe { strlen(path) == 0 } {
         return c".".as_ptr().cast_mut();
     }
-    let mut end = unsafe { strlen(str) as isize - 1 };
-    while end > 0 && unsafe { *str.offset(end) == ByteLiteral::cast_cchar(b'/') } {
+    let mut end = unsafe { strlen(path) as isize - 1 };
+    while end > 0 && unsafe { *path.offset(end) == ByteLiteral::cast_cchar(b'/') } {
         end -= 1;
     }
-    while end >= 0 && unsafe { *str.offset(end) != ByteLiteral::cast_cchar(b'/') } {
+    while end >= 0 && unsafe { *path.offset(end) != ByteLiteral::cast_cchar(b'/') } {
         end -= 1;
     }
-    while end > 0 && unsafe { *str.offset(end) == ByteLiteral::cast_cchar(b'/') } {
+    while end > 0 && unsafe { *path.offset(end) == ByteLiteral::cast_cchar(b'/') } {
         end -= 1;
     }
     if end == -1 {
         return c".".as_ptr().cast_mut();
     }
     unsafe {
-        *str.offset(end + 1) = 0;
+        *path.offset(end + 1) = 0;
     }
-    str
+    path
 }

src/header/string/mod.rs

@@ -447,6 +447,11 @@ pub unsafe extern "C" fn strlcpy(dst: *mut c_char, src: *const c_char, dstsize:
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/strlen.html>.
+///
+/// Returns the number of bytes in the string to which `s` points, not
+/// including the `NUL` character.
+///
+/// Always successful. The return value never represents an error.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn strlen(s: *const c_char) -> size_t {
     unsafe { NulTerminated::new(s) }