Index: uspace/lib/posix/string.c
===================================================================
--- uspace/lib/posix/string.c	(revision 27eddb52d56ef05faab213ab06ffed225dd60a7b)
+++ uspace/lib/posix/string.c	(revision 5273eb61feee028a95e33b24a42e3d66cba864b7)
@@ -31,5 +31,5 @@
  * @{
  */
-/** @file
+/** @file String manipulation.
  */
 
@@ -48,9 +48,9 @@
 
 /**
- * Returns true if s2 is a prefix of s1.
- *
- * @param s1
- * @param s2
- * @return
+ * Decides whether s2 is a prefix of s1.
+ *
+ * @param s1 String in which to look for a prefix.
+ * @param s2 Prefix string to look for.
+ * @return True if s2 is a prefix of s1, false otherwise.
  */
 static bool begins_with(const char *s1, const char *s2)
@@ -69,7 +69,8 @@
  * if no occurence is found.
  *
- * @param s1
- * @param s2
- * @return
+ * @param s1 String in which to look for the bytes.
+ * @param s2 String of bytes to look for.
+ * @return Pointer to the found byte on success, pointer to the
+ *     string terminator otherwise.
  */
 static char *strpbrk_null(const char *s1, const char *s2)
@@ -83,10 +84,11 @@
 
 /**
- *
- * @param dest
- * @param src
- * @return
- */
-char *posix_strcpy(char *dest, const char *src)
+ * Copy a string.
+ *
+ * @param dest Destination pre-allocated buffer.
+ * @param src Source string to be copied.
+ * @return Pointer to the destination buffer.
+ */
+char *posix_strcpy(char *restrict dest, const char *restrict src)
 {
 	posix_stpcpy(dest, src);
@@ -95,11 +97,12 @@
 
 /**
- *
- * @param dest
- * @param src
- * @param n
- * @return
- */
-char *posix_strncpy(char *dest, const char *src, size_t n)
+ * Copy fixed length string.
+ *
+ * @param dest Destination pre-allocated buffer.
+ * @param src Source string to be copied.
+ * @param n Number of bytes to be stored into destination buffer.
+ * @return Pointer to the destination buffer.
+ */
+char *posix_strncpy(char *restrict dest, const char *restrict src, size_t n)
 {
 	posix_stpncpy(dest, src, n);
@@ -108,8 +111,9 @@
 
 /**
- *
- * @param dest
- * @param src
- * @return Pointer to the nul character in the dest string
+ * Copy a string.
+ *
+ * @param dest Destination pre-allocated buffer.
+ * @param src Source string to be copied.
+ * @return Pointer to the nul character in the destination string.
  */
 char *posix_stpcpy(char *restrict dest, const char *restrict src)
@@ -132,9 +136,10 @@
 
 /**
- *
- * @param dest
- * @param src
- * @param n
- * @return Pointer to the first written nul character or &dest[n]
+ * Copy fixed length string.
+ *
+ * @param dest Destination pre-allocated buffer.
+ * @param src Source string to be copied.
+ * @param n Number of bytes to be stored into destination buffer.
+ * @return Pointer to the first written nul character or &dest[n].
  */
 char *posix_stpncpy(char *restrict dest, const char *restrict src, size_t n)
@@ -162,10 +167,11 @@
 
 /**
- *
- * @param dest
- * @param src
- * @return
- */
-char *posix_strcat(char *dest, const char *src)
+ * Concatenate two strings.
+ *
+ * @param dest String to which src shall be appended.
+ * @param src String to be appended after dest.
+ * @return Pointer to destination buffer.
+ */
+char *posix_strcat(char *restrict dest, const char *restrict src)
 {
 	assert(dest != NULL);
@@ -177,11 +183,12 @@
 
 /**
- *
- * @param dest
- * @param src
- * @param n
- * @return
- */
-char *posix_strncat(char *dest, const char *src, size_t n)
+ * Concatenate a string with part of another.
+ *
+ * @param dest String to which part of src shall be appended.
+ * @param src String whose part shall be appended after dest.
+ * @param n Number of bytes to append after dest.
+ * @return Pointer to destination buffer.
+ */
+char *posix_strncat(char *restrict dest, const char *restrict src, size_t n)
 {
 	assert(dest != NULL);
@@ -195,12 +202,13 @@
 
 /**
- *
- * @param dest
- * @param src
- * @param c
- * @param n
+ * Copy limited number of bytes in memory.
+ *
+ * @param dest Destination buffer.
+ * @param src Source buffer.
+ * @param c Character after which the copying shall stop.
+ * @param n Number of bytes that shall be copied if not stopped earlier by c.
  * @return Pointer to the first byte after c in dest if found, NULL otherwise.
  */
-void *posix_memccpy(void *dest, const void *src, int c, size_t n)
+void *posix_memccpy(void *restrict dest, const void *restrict src, int c, size_t n)
 {
 	assert(dest != NULL);
@@ -223,7 +231,8 @@
 
 /**
- *
- * @param s
- * @return Newly allocated string
+ * Duplicate a string.
+ *
+ * @param s String to be duplicated.
+ * @return Newly allocated copy of the string.
  */
 char *posix_strdup(const char *s)
@@ -233,8 +242,9 @@
 
 /**
- *
- * @param s
- * @param n
- * @return Newly allocated string of length at most n
+ * Duplicate a specific number of bytes from a string.
+ *
+ * @param s String to be duplicated.
+ * @param n Maximum length of the resulting string..
+ * @return Newly allocated string copy of length at most n.
  */
 char *posix_strndup(const char *s, size_t n)
@@ -255,10 +265,11 @@
 
 /**
- *
- * @param mem1
- * @param mem2
- * @param n
+ * Compare bytes in memory.
+ *
+ * @param mem1 First area of memory to be compared.
+ * @param mem2 Second area of memory to be compared.
+ * @param n Maximum number of bytes to be compared.
  * @return Difference of the first pair of inequal bytes,
- *     or 0 if areas have the same content
+ *     or 0 if areas have the same content.
  */
 int posix_memcmp(const void *mem1, const void *mem2, size_t n)
@@ -280,8 +291,10 @@
 
 /**
- *
- * @param s1
- * @param s2
- * @return
+ * Compare two strings.
+ *
+ * @param s1 First string to be compared.
+ * @param s2 Second string to be compared.
+ * @return Difference of the first pair of inequal characters,
+ *     or 0 if strings have the same content.
  */
 int posix_strcmp(const char *s1, const char *s2)
@@ -294,9 +307,11 @@
 
 /**
- *
- * @param s1
- * @param s2
- * @param n
- * @return
+ * Compare part of two strings.
+ *
+ * @param s1 First string to be compared.
+ * @param s2 Second string to be compared.
+ * @param n Maximum number of characters to be compared.
+ * @return Difference of the first pair of inequal characters,
+ *     or 0 if strings have the same content.
  */
 int posix_strncmp(const char *s1, const char *s2, size_t n)
@@ -318,9 +333,11 @@
 
 /**
- *
- * @param mem
- * @param c
- * @param n
- * @return
+ * Find byte in memory.
+ *
+ * @param mem Memory area in which to look for the byte.
+ * @param c Byte to look for.
+ * @param n Maximum number of bytes to be inspected.
+ * @return Pointer to the specified byte on success,
+ *     NULL pointer otherwise.
  */
 void *posix_memchr(const void *mem, int c, size_t n)
@@ -339,8 +356,10 @@
 
 /**
- *
- * @param s
- * @param c
- * @return
+ * Scan string for a first occurence of a character.
+ *
+ * @param s String in which to look for the character.
+ * @param c Character to look for.
+ * @return Pointer to the specified character on success,
+ *     NULL pointer otherwise.
  */
 char *posix_strchr(const char *s, int c)
@@ -353,8 +372,10 @@
 
 /**
- *
- * @param s
- * @param c
- * @return
+ * Scan string for a last occurence of a character.
+ *
+ * @param s String in which to look for the character.
+ * @param c Character to look for.
+ * @return Pointer to the specified character on success,
+ *     NULL pointer otherwise.
  */
 char *posix_strrchr(const char *s, int c)
@@ -376,4 +397,12 @@
 }
 
+/**
+ * Scan string for a first occurence of a character.
+ *
+ * @param s String in which to look for the character.
+ * @param c Character to look for.
+ * @return Pointer to the specified character on success, pointer to the
+ *     string terminator otherwise.
+ */
 char *gnu_strchrnul(const char *s, int c)
 {
@@ -388,8 +417,10 @@
 
 /**
- *
- * @param s1
- * @param s2
- * @return
+ * Scan a string for a first occurence of one of provided bytes.
+ *
+ * @param s1 String in which to look for the bytes.
+ * @param s2 String of bytes to look for.
+ * @return Pointer to the found byte on success,
+ *     NULL pointer otherwise.
  */
 char *posix_strpbrk(const char *s1, const char *s2)
@@ -403,8 +434,9 @@
 
 /**
- *
- * @param s1
- * @param s2
- * @return
+ * Get the length of a complementary substring.
+ *
+ * @param s1 String that shall be searched for complementary prefix.
+ * @param s2 String of bytes that shall not occur in the prefix.
+ * @return Length of the prefix.
  */
 size_t posix_strcspn(const char *s1, const char *s2)
@@ -418,8 +450,9 @@
 
 /**
- *
- * @param s1
- * @param s2
- * @return
+ * Get length of a substring.
+ *
+ * @param s1 String that shall be searched for prefix.
+ * @param s2 String of bytes that the prefix must consist of.
+ * @return Length of the prefix.
  */
 size_t posix_strspn(const char *s1, const char *s2)
@@ -438,8 +471,10 @@
 
 /**
- *
- * @param s1
- * @param s2
- * @return
+ * Find a substring.
+ *
+ * @param s1 String in which to look for a substring.
+ * @param s2 Substring to look for.
+ * @return Pointer to the first character of the substring in s1, or NULL if
+ *     not found.
  */
 char *posix_strstr(const char *s1, const char *s2)
@@ -467,9 +502,12 @@
 
 /**
+ * String comparison using collating information.
+ *
  * Currently ignores locale and just calls strcmp.
  *
- * @param s1
- * @param s2
- * @return
+ * @param s1 First string to be compared.
+ * @param s2 Second string to be compared.
+ * @return Difference of the first pair of inequal characters,
+ *     or 0 if strings have the same content.
  */
 int posix_strcoll(const char *s1, const char *s2)
@@ -482,12 +520,16 @@
 
 /**
- * strcoll is equal to strcmp here, so this just makes a copy.
- *
- * @param s1
- * @param s2
- * @param n
- * @return
- */
-size_t posix_strxfrm(char *s1, const char *s2, size_t n)
+ * Transform a string in such a way that the resulting string yields the same
+ * results when passed to the strcmp as if the original string is passed to
+ * the strcoll.
+ *
+ * Since strcoll is equal to strcmp here, this just makes a copy.
+ *
+ * @param s1 Transformed string.
+ * @param s2 Original string.
+ * @param n Maximum length of the transformed string.
+ * @return Length of the transformed string.
+ */
+size_t posix_strxfrm(char *restrict s1, const char *restrict s2, size_t n)
 {
 	assert(s1 != NULL || n == 0);
@@ -504,7 +546,8 @@
 
 /**
- *
- * @param errnum
- * @return
+ * Get error message string.
+ *
+ * @param errnum Error code for which to obtain human readable string.
+ * @return Error message.
  */
 char *posix_strerror(int errnum)
@@ -518,9 +561,10 @@
 
 /**
- *
- * @param errnum Error code
- * @param buf Buffer to store a human readable string to
- * @param bufsz Size of buffer pointed to by buf
- * @return
+ * Get error message string.
+ *
+ * @param errnum Error code for which to obtain human readable string.
+ * @param buf Buffer to store a human readable string to.
+ * @param bufsz Size of buffer pointed to by buf.
+ * @return Zero on success, errno otherwise.
  */
 int posix_strerror_r(int errnum, char *buf, size_t bufsz)
@@ -541,7 +585,8 @@
 
 /**
- *
- * @param s
- * @return
+ * Get length of the string.
+ *
+ * @param s String which length shall be determined.
+ * @return Length of the string.
  */
 size_t posix_strlen(const char *s)
@@ -553,8 +598,9 @@
 
 /**
- *
- * @param s
- * @param n
- * @return
+ * Get limited length of the string.
+ *
+ * @param s String which length shall be determined.
+ * @param n Maximum number of bytes that can be examined to determine length.
+ * @return The lower of either string length or n limit.
  */
 size_t posix_strnlen(const char *s, size_t n)
@@ -573,7 +619,8 @@
 
 /**
- *
- * @param signum
- * @return
+ * Get description of a signal.
+ *
+ * @param signum Signal number.
+ * @return Human readable signal description.
  */
 char *posix_strsignal(int signum)
