Update code docs for string functions and macros as well

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>

src/conio.h

@@ -15,6 +15,15 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
+/**
+ * @file conio.h
+ * @author Joachim Wiberg
+ * @date 2009-2021
+ * @copyright ISC License
+ *
+ * Helper macros and functions for interacting with TTY terminals.
+ */
+
 #ifdef __cplusplus
 extern "C"
 {
@@ -25,7 +34,7 @@ extern "C"
 
 #include <stdio.h>
 
-/* Attributes */
+/** Attributes */
 #define RESETATTR    0
 #define BRIGHT       1
 #define DIM          2
@@ -34,7 +43,7 @@ extern "C"
 #define REVERSE      7
 #define HIDDEN       8
 
-/* Colors for text and background */
+/** Colors for text and background */
 #define BLACK        0x0
 #define RED          0x1
 #define GREEN        0x2
@@ -54,39 +63,50 @@ extern "C"
 #define WHITE        0x17
 
 #ifndef SCREEN_WIDTH
-#define SCREEN_WIDTH 80		/* Override using, e.g. #define SCREEN_WIDTH tty_width() */
+#define SCREEN_WIDTH 80	/**< Fallback screen width, possible to override. */
 #endif
 
-/* Esc[2JEsc[1;1H             - Clear screen and move cursor to 1,1 (upper left) pos. */
+/** Clear screen and move cursor to 1,1 (upper left) pos. */
 #define clrscr()              fputs("\033[2J\033[1;1H", stdout)
-/* Esc[K                      - Erases from the current cursor position to the end of the current line. */
+/** Erases from the current cursor position to the end of the current line. */
 #define clreol()              fputs("\033[K", stdout)
-/* Esc[2K                     - Erases the entire current line. */
+/** Erases the entire current line. */
 #define delline()             fputs("\033[2K", stdout)
-/* Esc[Line;ColumnH           - Moves the cursor to the specified position (coordinates) */
+/** Moves the cursor to the specified position (coordinates) */
 #define gotoxy(x,y)           fprintf(stdout, "\033[%d;%dH", y, x)
-/* Esc[?25l (lower case L)    - Hide Cursor */
+/** Hide Cursor */
 #define hidecursor()          fputs("\033[?25l", stdout)
-/* Esc[?25h (lower case H)    - Show Cursor */
+/** Show Cursor */
 #define showcursor()          fputs("\033[?25h", stdout)
 
-/* Esc[Value;...;Valuem       - Set Graphics Mode (attr, color, val) */
+/** Set Graphics Mode (attr, color, val) */
 #define __set_gm(a,c,v)							\
 	if (!c)								\
 		fprintf(stdout, "\033[%dm", a);				\
 	else								\
 		fprintf(stdout, "\033[%d;%dm", c & 0x10 ? 1 : 0, (c & 0xF) + v)
+
+/** Set text attribute */
 #define textattr(attr)        __set_gm(attr, 0, 0)
+/** Set text color */
 #define textcolor(color)      __set_gm(RESETATTR, color, 30)
+/** Set text background */
 #define textbackground(color) __set_gm(RESETATTR, color, 40)
 
 void initscr(int *row, int *col);
 
-/* Print table heading @line to @fp, with optional leading newline
- * Example:
+/**
+ * Print table heading, with optional leading newline.
+ * @param fp    output stream
+ * @param line  string to print
+ * @param nl    leading newline or not
+ * @param attr  attribute
+ *
+ * @verbatim
  * _________________ <-- Empty line with UNDERSCORE to frame first heading
  * First heading     <-- In normal/RESETATTR
  * SUBHEADING        <-- In REVERSE and with capital letters like 'top'
+ * @endverbatim
  */
 static inline void printhdr(FILE *fp, const char *line, int nl, int attr)
 {
@@ -99,6 +119,12 @@ static inline void printhdr(FILE *fp, const char *line, int nl, int attr)
 		SCREEN_WIDTH - (int)strlen(line), "");
 }
 
+/**
+ * Print reverse mode table heading, e.g. black text on white background.
+ * @param fp    output stream
+ * @param line  string to print
+ * @param nl    leading newline or not
+ */
 static inline void printheader(FILE *fp, const char *line, int nl)
 {
 	printhdr(fp, line, nl, REVERSE);

src/queue.h

@@ -40,7 +40,12 @@ extern "C"
 #ifndef	_SYS_QUEUE_H_
 #define	_SYS_QUEUE_H_
 
-/*
+/**
+ * @file queue.h
+ * @author The Regents of the University of California
+ * @date 1991, 1993
+ * @copyright 3-clause BSD License
+ *
  * This file defines five types of data structures: singly-linked lists,
  * lists, simple queues, tail queues and XOR simple queues.
  *

src/strdupa.h

@@ -24,6 +24,13 @@
  * ==========================================================================
  */
 
+/**
+ * @file strdupa.h
+ * @author William Ahern
+ * @date 2009
+ * @copyright MIT License
+ */
+
 #ifdef __cplusplus
 extern "C"
 {
@@ -43,6 +50,11 @@ extern "C"
 #include <stddef.h>	/* size_t */
 #include <string.h>	/* memcpy(3) strlen(3) */
 
+/**
+ * Duplicate string on stack.
+ * @param src string to duplicate
+ * @returns the result of memcpy(3)
+ */
 #define strdupa(src) (__extension__ ({			\
 	size_t len_	= strlen(src);			\
 	char *dst_	= __builtin_alloca(len_ + 1);	\

src/strlcat.c

@@ -16,16 +16,30 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
+/**
+ * @file strlcat.c
+ * @author Todd C. Miller
+ * @date 1998, 2015
+ * @copyright ISC License
+ */
+
 #include <sys/types.h>
 #include <string.h>
 
 #ifndef strlcat
-/*
- * Appends src to string dst of size dsize (unlike strncat, dsize is the
- * full size of dst, not space left).  At most dsize-1 characters
- * will be copied.  Always NUL terminates (unless dsize <= strlen(dst)).
- * Returns strlen(src) + MIN(dsize, strlen(initial dst)).
- * If retval >= dsize, truncation occurred.
+/**
+ * Safe version of strncat() from OpenBSD
+ * @param dst   Destination string
+ * @param src   Source string
+ * @param dsize Total maximum size of @p dst
+ *
+ * Appends @p src to string @p dst of size @p dsize (unlike strncat(),
+ * @p dsize is the full size of @p dst, not space left).  At most
+ * dsize-1 characters will be copied.  Always NUL terminates (unless
+ * dsize <= strlen(dst)).
+ *
+ * @returns strlen(src) + MIN(dsize, strlen(initial dst)).  
+ *          If retval >= dsize, truncation occurred.
  */
 size_t
 strlcat(char *dst, const char *src, size_t dsize)

src/strlcpy.c

@@ -16,14 +16,29 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
+/**
+ * @file strlcpy.c
+ * @author Todd C. Miller
+ * @date 1998, 2015
+ * @copyright ISC License
+ */
+
+
 #include <sys/types.h>
 #include <string.h>
 
 #ifndef strlcpy
-/*
- * Copy string src to buffer dst of size dsize.  At most dsize-1
- * chars will be copied.  Always NUL terminates (unless dsize == 0).
- * Returns strlen(src); if retval >= dsize, truncation occurred.
+/**
+ * Safe version of strncpy() from OpenBSD
+ * @param dst   Destination string
+ * @param src   Source string
+ * @param dsize Total maximum size of @p dst
+ *
+ * This function copies string @p src to buffer @p dst of size @p dsize
+ * bytes.  At most dsize-1 chars will be copied.  Always NUL terminates
+ * (unless dsize==0).
+ *
+ * @returns strlen(src); if retval >= dsize, truncation occurred.
  */
 size_t
 strlcpy(char *dst, const char *src, size_t dsize)

src/strlite.h

@@ -21,6 +21,13 @@
  * THE SOFTWARE.
  */
 
+/**
+ * @file strlite.h
+ * @author Joachim Wiberg
+ * @date 2008-2021
+ * @copyright MIT License
+ */
+
 #ifdef __cplusplus
 extern "C"
 {
@@ -38,6 +45,7 @@ extern "C"
 #include "strnlen.h"
 
 #ifndef min
+/** Geneirc min() macro, if a < b => a, else b */
 #define min(a,b)				\
 	({					\
 		__typeof__ (a) _a = (a);	\
@@ -46,6 +54,7 @@ extern "C"
 	})
 #endif
 #ifndef max
+/** Geneirc max() macro, if a > b => a, else b */
 #define max(a,b)				\
 	({					\
 		__typeof__ (a) _a = (a);	\
@@ -69,7 +78,11 @@ long long strtonum (const char *numstr, long long minval, long long maxval, cons
 
 char   *strtrim    (char *str);
 
-/* Convert string to natural number (0-2147483647), returns -1 on error. */
+/**
+ * Convert string to natural number (0-2147483647)
+ * @param str string to convert to number.
+ * @returns -1 on error.
+ */
 static inline int atonum(const char *str)
 {
 	int val = -1;
@@ -84,13 +97,22 @@ static inline int atonum(const char *str)
 	return val;
 }
 
-/* Validate string, non NULL and not zero length */
-static inline int string_valid(const char *s)
+/**
+ * Validate string, non NULL and not zero length
+ * @param str string to validate
+ * @returns @c TRUE(1) or @c FALSE(0).
+ */
+static inline int string_valid(const char *str)
 {
-   return s && strlen(s);
+   return str && strlen(str);
 }
 
-/* Relaxed comparison, e.g., sys_string_match("small", "smaller") => TRUE */
+/**
+ * Relaxed comparison, e.g., sys_string_match("small", "smaller") => TRUE
+ * @param a first string
+ * @param b second string
+ * @returns @c TRUE(1) or @c FALSE(0).
+ */
 static inline int string_match(const char *a, const char *b)
 {
    size_t min = MIN(strlen(a), strlen(b));
@@ -98,14 +120,23 @@ static inline int string_match(const char *a, const char *b)
    return !strncasecmp(a, b, min);
 }
 
-/* Strict comparison, e.g., sys_string_match("small", "smaller") => FALSE */
+/**
+ * Strict comparison, e.g., sys_string_match("small", "smaller") => FALSE
+ * @param a first string
+ * @param b second string
+ * @returns @c TRUE(1) or @c FALSE(0).
+ */
 static inline int string_compare(const char *a, const char *b)
 {
    return strlen(a) == strlen(b) && !strcmp(a, b);
 }
 
-/* Strict comparison, like sys_string_compare(), but case insensitive,
+/**
+ * Strict comparison, like sys_string_compare(), but case insensitive,
  * e.g., sys_string_match("small", "SmAlL") => TRUE
+ * @param a first string
+ * @param b second string
+ * @returns @c TRUE(1) or @c FALSE(0).
  */
 static inline int string_case_compare(const char *a, const char *b)
 {

src/strmatch.c

@@ -15,24 +15,30 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
+/**
+ * @file strmatch.c
+ * @author Joachim Wiberg
+ * @date 2009-2021
+ * @copyright ISC License
+ */
+
 #include <errno.h>
 #include <string.h>
 
 
 /**
- * strnmatch - Finds matching strings from a finite list
- * @str: String to look for
- * @list: List of strings to search.
- * @num: Number of entries in @list.
+ * Finds matching strings from a finite list
+ * @param str   String to look for
+ * @param list  List of strings to search.
+ * @param num   Number of entries in @p list.
  *
- * This function searches the @list of strings for @str.  If a (partial) match
- * is found it returns the index in the @list.
+ * This function searches the @p list of strings for @p str.  If a
+ * (partial) match is found it returns the index in the @p list.
  *
- * Very similar in function to strmatch(), but works for sets of strings that
- * are not %NULL terminated.
+ * Very similar in function to strmatch(), but works for sets of strings
+ * that are not @c NUL terminated.
  *
- * Returns:
- * -1 on error, otherwise the index to the matching string.
+ * @returns -1 on error, otherwise the index to the matching string.
  */
 int strnmatch(const char *str, const char **list, size_t num)
 {
@@ -53,18 +59,17 @@ int strnmatch(const char *str, const char **list, size_t num)
 }
 
 /**
- * strmatch - Finds matching strings from a list
- * @str: String to look for
- * @list: %NULL terminated list of strings to search.
+ * Finds matching strings from a list
+ * @param str   String to look for.
+ * @param list  NUL terminated list of strings to search.
  *
- * This function searches the @list of strings for @str.  If a (partial) match
- * is found it returns the index in the @list.
+ * This function searches the @p list of strings for @p str.  If a
+ * (partial) match is found it returns the index in the @p list.
  *
- * Please note, the @list MUST be terminated by a %NULL element.  If that is
- * not possible for you, we recommend using strnmatch() instead.
+ * Please note, the @p list MUST be terminated by a NUL element.  If
+ * that is not possible, we recommend using strnmatch() instead.
  *
- * Returns:
- * -1 on error, otherwise the index to the matching string.
+ * @returns -1 on error, otherwise the index to the matching string.
  */
 int strmatch(const char *str, const char **list)
 {

src/strndupa.h

@@ -24,6 +24,13 @@
  * ==========================================================================
  */
 
+/**
+ * @file strndupa.h
+ * @author William Ahern
+ * @date 2009
+ * @copyright MIT License
+ */
+
 #ifdef __cplusplus
 extern "C"
 {
@@ -44,6 +51,12 @@ extern "C"
 #include <string.h>	/* memcpy(3) */
 #include "strnlen.h"
 
+/**
+ * Duplicate part of string on stack
+ * @param src string to duplicate
+ * @param lim number of bytes to dupliate
+ * @returns the result of memcpy(3)
+ */
 #define strndupa(src, lim) (__extension__ ({		\
 	size_t len_	= strnlen(src, lim);		\
 	char *dst_	= __builtin_alloca(len_ + 1);	\

src/strnlen.h

@@ -15,6 +15,13 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
+/**
+ * @file strnlen.h
+ * @author Joachim Wiberg
+ * @date 2016-2021
+ * @copyright ISC License
+ */
+
 #ifdef __cplusplus
 extern "C"
 {
@@ -32,8 +39,14 @@ extern "C"
 #if !HAVE_STRNLEN
 #include <stddef.h>	/* size_t */
 
-#define strnlen(str, lim) xstrnlen(str, lim)
+#define strnlen(str, lim) xstrnlen(str, lim) /**< Wrapper for xstrnlen() */
 
+/**
+ * Reimplementation of GLIBC strnlen()
+ * @param str string to return length of
+ * @param lim max number of bytes to read
+ * @returns length of @p str in bytes, but at most @lim bytes.
+ */
 static inline size_t xstrnlen(const char *str, size_t lim)
 {
 	size_t i = 0;

src/strtonum.c

@@ -17,24 +17,60 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
+/**
+ * @file strtonum.c
+ * @author Ted Unangst
+ * @author Todd Miller
+ * @date 2004
+ * @copyright ISC License
+ */
+
 #include <errno.h>
 #include <limits.h>
 #include <stdlib.h>
 
 #ifndef strtonum
-#define	INVALID		1
-#define	TOOSMALL	2
-#define	TOOLARGE	3
+#define	INVALID		1		/**< internal */
+#define	TOOSMALL	2		/**< internal */
+#define	TOOLARGE	3		/**< internal */
 
 #ifndef LLONG_MAX
-# define LLONG_MAX	0x7fffffffffffffffLL
+# define LLONG_MAX	0x7fffffffffffffffLL        /**< internal */
 #endif
 
 #ifndef LLONG_MIN
-# define LLONG_MIN	(-0x7fffffffffffffffLL - 1)
+# define LLONG_MIN	(-0x7fffffffffffffffLL - 1) /**< internal */
 #endif
 
-
+/**
+ * Reliably convert string value to an integer
+ * @param numstr  String to convert to a number
+ * @param minval  Lower bound to check number against
+ * @param maxval  Upper bound to check number against
+ * @param errstrp Pointer to error string
+ *
+ * This function converts the string in @p numstr to a long long value.
+ * The function was designed to facilitate safe, robust programming and
+ * overcome the shortcomings of the atoi(3) and strtol(3) family of
+ * interfaces.
+ *
+ * The string may begin with an arbitrary amount of whitespace (as
+ * determined by isspace(3)) followed by a single optional ‘+’ or ‘-’
+ * sign.
+ *
+ * The remainder of the string is converted to a long long value
+ * according to base 10.
+ *
+ * The value obtained is then checked against the provided @p minval and
+ * @p maxval bounds. If @p errstrp is non-NULL, strtonum() stores an
+ * error string in @p *errstrp indicating the failure.
+ *
+ * @returns The result of the conversion, unless the value would exceed
+ * the provided bounds or is invalid. On error, 0 is returned, @a errno
+ * is set, and @p errstrp points to an error message. @p *errstr* is set
+ * to @c NULL on success; this fact can be used to differentiate a
+ * successful return of 0 from an error.
+ */
 long long
 strtonum(const char *numstr, long long minval, long long maxval,
     const char **errstrp)

src/strtrim.c

@@ -16,6 +16,14 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
+/**
+ * @file strtrim.c
+ * @author Mattias Walström
+ * @author Joachim Wiberg
+ * @date 2014,2021
+ * @copyright ISC License
+ */
+
 #include <ctype.h>
 #include <errno.h>
 #include <stdlib.h>
@@ -23,16 +31,15 @@
 #include "lite.h"
 
 /**
- * strtrim - Strip leading and trailing whitespace from a string
- * @str: The string to trim
+ * Strip leading and trailing whitespace from a string
+ * @param str  The string to trim
  *
  * Trims a string from any leading and trailing white-space, returns the
  * trimmed result in the same buffer.
  *
- * Returns:
- * If @str is a valid, non-NULL, string this function returns the same
- * string stripped from whitespace.  This function only returns %NULL
- * if @str itself is %NULL.
+ * @returns If @p str is a valid, non-NULL string this function returns
+ * the same string stripped from whitespace.  This function only returns
+ * @c NULL if @p str itself is @c NULL.
  */
 char *strtrim(char *str)
 {

src/tree.h

@@ -32,7 +32,12 @@ extern "C"
 #ifndef	_SYS_TREE_H_
 #define	_SYS_TREE_H_
 
-/*
+/**
+ * @file tree.h
+ * @author Niels Provos
+ * @date 2002
+ * @copyright 2-clause BSD License
+ *
  * This file defines data structures for different types of trees:
  * splay trees and red-black trees.
  *