From 970fa47ecfa6801c8b9c822e79e7c4313c8d29ef Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Sun, 3 Oct 2021 22:30:20 +0200 Subject: [PATCH] Update code docs for string functions and macros as well Signed-off-by: Joachim Wiberg --- src/conio.h | 50 ++++++++++++++++++++++++++++++++++++++------------ src/queue.h | 7 ++++++- src/strdupa.h | 12 ++++++++++++ src/strlcat.c | 26 ++++++++++++++++++++------ src/strlcpy.c | 23 +++++++++++++++++++---- src/strlite.h | 45 ++++++++++++++++++++++++++++++++++++++------- src/strmatch.c | 43 ++++++++++++++++++++++++------------------- src/strndupa.h | 13 +++++++++++++ src/strnlen.h | 15 ++++++++++++++- src/strtonum.c | 48 ++++++++++++++++++++++++++++++++++++++++++------ src/strtrim.c | 19 +++++++++++++------ src/tree.h | 7 ++++++- 12 files changed, 245 insertions(+), 63 deletions(-) diff --git a/src/conio.h b/src/conio.h index 2f45e3c..33fc3a6 100644 --- a/src/conio.h +++ b/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 -/* 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); diff --git a/src/queue.h b/src/queue.h index c5a867b..ba09df1 100644 --- a/src/queue.h +++ b/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. * diff --git a/src/strdupa.h b/src/strdupa.h index 3b6cf94..74613ca 100644 --- a/src/strdupa.h +++ b/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 /* size_t */ #include /* 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); \ diff --git a/src/strlcat.c b/src/strlcat.c index d38e322..d325089 100644 --- a/src/strlcat.c +++ b/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 #include #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) diff --git a/src/strlcpy.c b/src/strlcpy.c index 80c8fd0..ec3c55f 100644 --- a/src/strlcpy.c +++ b/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 #include #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) diff --git a/src/strlite.h b/src/strlite.h index dc33998..6d8aab4 100644 --- a/src/strlite.h +++ b/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) { diff --git a/src/strmatch.c b/src/strmatch.c index b0b98ef..6dd1bf6 100644 --- a/src/strmatch.c +++ 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 #include /** - * 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) { diff --git a/src/strndupa.h b/src/strndupa.h index 023694c..124a3e8 100644 --- a/src/strndupa.h +++ b/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 /* 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); \ diff --git a/src/strnlen.h b/src/strnlen.h index d4e222b..bde1a8e 100644 --- a/src/strnlen.h +++ b/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 /* 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; diff --git a/src/strtonum.c b/src/strtonum.c index 51029a2..215b8ae 100644 --- a/src/strtonum.c +++ b/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 #include #include #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) diff --git a/src/strtrim.c b/src/strtrim.c index 5bdb3ee..9e53d6d 100644 --- a/src/strtrim.c +++ b/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 #include #include @@ -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) { diff --git a/src/tree.h b/src/tree.h index 974e14b..665d4e5 100644 --- a/src/tree.h +++ b/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. *