Mercurial > hg > th-libs

changeset 616:594f197f7005

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Slight improvements to the almost non-existing Doxygen documentation.
author Matti Hamalainen <ccr@tnsp.org>
date Fri, 17 Jan 2020 03:18:40 +0200
parents b87395754c8d
children a3d5ddbb6f16
files th_args.c th_ioctx.h th_string.c th_string.h
diffstat 4 files changed, 125 insertions(+), 34 deletions(-) [+]
line wrap: on
line diff
--- 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)
--- 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);
--- 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;
--- 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);