# HG changeset patch # User Matti Hamalainen # Date 1579223920 -7200 # Node ID 594f197f7005e06f19523dca16f42a54a46f2119 # Parent b87395754c8d0cb74f33a6aca62dde8b3217fcdf Slight improvements to the almost non-existing Doxygen documentation. diff -r b87395754c8d -r 594f197f7005 th_args.c --- a/th_args.c Fri Jan 17 00:01:55 2020 +0200 +++ b/th_args.c Fri Jan 17 03:18:40 2020 +0200 @@ -15,14 +15,15 @@ /** * Parse and optionally handle the given long or short option argument. * @param currArg current argument string - * @param argIndex pointer to index of current argument in argv[] + * @param[in,out] argIndex pointer to index of current argument in argv[] * @param argc number of arguments * @param argv argument string array - * @param opts options list array - * @param nopts number of elements in options list array - * @param handle_option function pointer to callback that handles option arguments - * @param doProcess if TRUE, actually handle the argument, aka call the handle_option() function. if FALSE, only validity of options are checked. - * @param isLong TRUE if the option is a --long-format one + * @param[in] opts options list array + * @param[in] nopts number of elements in options list array + * @param[in] handle_option function pointer to callback that handles option arguments + * @param[in] doProcess if TRUE, actually handle the argument, aka call the handle_option() function. if FALSE, only validity of options are checked. + * @param[in] isLong TRUE if the option is a --long-format one + * @returns returns @c TRUE if option processing was successful */ static BOOL th_args_process_opt( char *currArg, int *argIndex, @@ -111,12 +112,12 @@ * * @param argc number of arguments * @param argv argument list - * @param opts supported option list array - * @param nopts number of elements in the option list array - * @param handle_option callback function - * @param handle_other callback function - * @param flags processing flags - * @return return TRUE if all is well + * @param[in] opts supported option list array + * @param[in] nopts number of elements in the option list array + * @param[in] handle_option callback function + * @param[in] handle_other callback function + * @param[in] flags processing flags + * @return returns @c TRUE if arguments were processed successfully */ BOOL th_args_process(int argc, char *argv[], const th_optarg *opts, const int nopts, @@ -188,10 +189,10 @@ * Print given string indented in such a way that it is automatically * line-wrapped as necessary, taking hard linefeeds into account as well. * @param fh stdio file handle to output to - * @param spad starting pad/indent of the first line - * @param rpad how much to pad the other lines - * @param width total line width to wrap at - * @param str string to output + * @param[in] spad starting pad/indent of the first line + * @param[in] rpad how much to pad the other lines + * @param[in] width total line width to wrap at + * @param[in] str string to output */ void th_print_wrap(FILE *fh, const int spad, int const rpad, const int width, const char *str) @@ -331,10 +332,10 @@ /** * Print help for commandline arguments/options * @param fh stdio file handle to output to - * @param opts options list array - * @param nopts number of elements in options list array - * @param flags flags (currently unused) - * @param width width of the terminal or desired width of the print out + * @param[in] opts options list array + * @param[in] nopts number of elements in options list array + * @param[in] flags flags (currently unused) + * @param[in] width width of the terminal or desired width of the print out */ void th_args_help(FILE *fh, const th_optarg *opts, const int nopts, const int flags, const int width) diff -r b87395754c8d -r 594f197f7005 th_ioctx.h --- a/th_ioctx.h Fri Jan 17 00:01:55 2020 +0200 +++ b/th_ioctx.h Fri Jan 17 03:18:40 2020 +0200 @@ -17,6 +17,7 @@ #endif +// // Typedefs and structures // struct th_ioctx; @@ -44,7 +45,7 @@ typedef struct th_ioctx_ops { - char *name; ///< Name of this I/O ops definition + char *name; ///< Name of this I/O ops definition int (*fopen)(th_ioctx *ctx); void (*fclose)(th_ioctx *ctx); diff -r b87395754c8d -r 594f197f7005 th_string.c --- a/th_string.c Fri Jan 17 00:01:55 2020 +0200 +++ b/th_string.c Fri Jan 17 03:18:40 2020 +0200 @@ -12,7 +12,10 @@ #include "th_printf.c" -/* Implementation of strdup() with a NULL check +/** + * Implementation of strdup() with a @c NULL check. + * @param[in] src string to create a copy of + * @returns copy of the given string, or @c NULL if @p src was @c NULL or memory could not be allocated. */ char *th_strdup(const char *src) { @@ -31,7 +34,14 @@ } -/* Implementation of strndup() with NULL check +/** + * Implementation of strndup() with @c NULL check. Copies up to @p n + * characters from the source. A NUL terminator is always added, + * unless @p src was @c NULL or memory could not be allocated, in which + * case @c NULL pointer is returned. + * @param[in] src string pointer to be copied from + * @param[in] n maximum number of characters to copy + * @returns the resulting string or @c NULL pointer */ char *th_strndup(const char *src, const size_t n) { @@ -55,9 +65,15 @@ } -/* Like strdup, but trims whitespace from the string according to specified flags. - * See TH_TRIM_* in th_string.h. If the resulting string would be empty (length 0), - * NULL is returned. +/** + * Helper function for th_strdup_trim() and friends. Copies @p len characters from + * given string, and trims whitespace from it according to specified @p flags. + * See TH_TRIM_* in th_string.h. If @p len or the resulting trimmed string would + * be empty (length 0), no copy is allocated and a @c NULL pointer is returned. + * @param[in] src source string (does not need to be NUL terminated, as length must be specified) + * @param[in] len length of the source string, or desired number of characters to copy at maximum + * @param[in] flags trimming flags, see TH_TRIM_* in th_string.h + * @returns the resulting string or @c NULL pointer */ static char * th_strdup_trim_do(const char *src, size_t len, const int flags) { @@ -93,6 +109,14 @@ } +/** + * Create copy of the given string, but trim the result according to specified @p flags. + * See TH_TRIM_* in th_string.h. If length the resulting trimmed string would + * be empty (0), no copy is allocated and a NULL pointer is returned. + * @param[in] src source string + * @param[in] flags trimming flags, see TH_TRIM_* in th_string.h + * @returns the resulting string or @c NULL pointer + */ char *th_strdup_trim(const char *src, const int flags) { if (src == NULL) @@ -102,6 +126,16 @@ } +/** + * Create copy of the given string @p src, up to @p n characters (or less, if the string + * is shorter.) The result is trimmed according to specified @p flags. + * See TH_TRIM_* in th_string.h. If @p n or the resulting trimmed string would + * be empty (length 0), no copy is allocated and a NULL pointer is returned. + * @param[in] src source string + * @param[in] n maximum number of characters to copy from the source string + * @param[in] flags trimming flags, see TH_TRIM_* in th_string.h + * @returns the resulting string or @c NULL pointer + */ char *th_strndup_trim(const char *src, const size_t n, const int flags) { size_t len; @@ -147,6 +181,14 @@ #endif +/** + * Wrapper for either libc vsnprintf() or th-libs internal + * vsnprintf() implementation, as determined by a compile-time define. + * @param[out] buf pointer to buffer to print to + * @param[in] size available space in the buffer in bytes + * @param[in] fmt format string + * @param[in] ap a va_list variable arguments list structure + */ int th_vsnprintf(char *buf, size_t size, const char *fmt, va_list ap) { #ifdef TH_USE_INTERNAL_SPRINTF @@ -172,6 +214,14 @@ } +/** + * Wrapper for either libc snprintf() or th-libs internal + * snprintf() implementation, as determined by a compile-time define. + * @param[out] buf pointer to buffer to print to + * @param[in] size available space in the buffer in bytes + * @param[in] fmt format string + * @param[in] ... variable arguments + */ int th_snprintf(char *buf, size_t size, const char *fmt, ...) { int n; @@ -253,6 +303,13 @@ #endif +/** + * Combination of vsprintf() and strdup. Automatically allocates memory + * for the resulting string. + * @param[in] fmt format string + * @param[in] args variable arguments list structure + * @returns the resulting string or @c NULL pointer in case of error + */ char *th_strdup_vprintf(const char *fmt, va_list args) { #ifdef TH_USE_INTERNAL_SPRINTF @@ -317,6 +374,13 @@ } +/** + * Combination of sprintf() and strdup. Automatically allocates memory + * for the resulting string. + * @param[in] fmt format string + * @param[in] ... optional printf arguments + * @returns the resulting string or @c NULL pointer in case of error + */ char *th_strdup_printf(const char *fmt, ...) { char *res; @@ -330,6 +394,14 @@ } +/** + * A helper function that is given a pointer to a pointer of string, + * which will be automatically freed (if necessary) and replaced with + * a pointer to the newly created string. + * @param[in,out] buf pointer to a char pointer/string + * @param[in] fmt format string + * @param[in] args variable arguments list structure + */ void th_pstr_vprintf(char **buf, const char *fmt, va_list ap) { char *tmp = th_strdup_vprintf(fmt, ap); @@ -338,6 +410,14 @@ } +/** + * A helper function that is given a pointer to a pointer of string, + * which will be automatically freed (if necessary) and replaced with + * a pointer to the newly created string. + * @param[in,out] buf pointer to a char pointer/string + * @param[in] fmt format string + * @param[in] ... optional printf arguments + */ void th_pstr_printf(char **buf, const char *fmt, ...) { char *tmp; diff -r b87395754c8d -r 594f197f7005 th_string.h --- a/th_string.h Fri Jan 17 00:01:55 2020 +0200 +++ b/th_string.h Fri Jan 17 03:18:40 2020 +0200 @@ -42,17 +42,19 @@ #define th_toupper(c) toupper((int)(unsigned char) c) -/** @def String trimming option flags for th_strdup_trim() +/** @brief + * String trimming option flags for th_strdup_trim() */ enum { - TH_TRIM_START = 1, - TH_TRIM_END = 2, - TH_TRIM_BOTH = 3 + TH_TRIM_START = 1, ///< Trim whitespace from start of the string + TH_TRIM_END = 2, ///< Trim whitespace from end of the string + TH_TRIM_BOTH = 3, ///< Trim whitespace from start and end of the string }; -/** @def Internal *printf() implementation flags +/** @brief + * Internal *printf() implementation flags */ enum { @@ -72,18 +74,25 @@ }; -/** @def Internal *printf() context structure +/** @struct th_vprintf_ctx + * Internal printf() implementation context structure, contains state information + * used by the printf() code for "output" purposes. */ typedef struct { char *buf; ///< Resulting string buffer pointer (might not be used if printing to file or such) - size_t size, pos; ///< Size of result string buffer, and current position in it + size_t size; ///< Size of result string buffer + size_t pos; ///< Current position in the buffer int ipos; ///< Signed position void *data; ///< Pointer to other data (for example a FILE pointer) } th_vprintf_ctx; -/** @def putch() helper function typedef for internal printf() implementation +/** @brief + * A putch() helper function typedef for internal printf() implementation + * @param[in,out] ctx pointer to internal printf() state context structure. + * @param[in] ch character to be outputted + * @returns the character @p ch cast to int or @c EOF in case of error */ typedef int (*th_vprintf_putch)(th_vprintf_ctx *ctx, const char ch);