Mercurial > hg > th-libs

changeset 436:9148bc3fa838

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Begin adding Doxygen documentation for some things. Very rudimentary, and most things are not documented yet.
author Matti Hamalainen <ccr@tnsp.org>
date Wed, 10 May 2017 21:00:37 +0300
parents 468d521240c6
children 96810a91eeb3
files th_args.c th_args.h th_crypto.h th_file.h th_ioctx.h
diffstat 5 files changed, 73 insertions(+), 31 deletions(-) [+]
line wrap: on
line diff
--- a/th_args.c	Fri Apr 07 02:49:08 2017 +0300
+++ b/th_args.c	Wed May 10 21:00:37 2017 +0300
@@ -5,6 +5,8 @@
  *
  * Please read file 'COPYING' for information on license and distribution.
  */
+/// @file
+/// @brief Simple commandline argument processing functions
 #ifndef TH_EXTERNAL
 #include "th_util.h"
 #include "th_args.h"
@@ -12,7 +14,17 @@
 #endif
 
 
-/* Parse long and short options
+/**
+ * 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 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
  */
 static BOOL th_args_process_opt(
     char *currArg, int *argIndex,
@@ -95,8 +107,18 @@
 }
 
 
-/* Process arguments, handling short and long options by
- * calling the given callback functions.
+/**
+ * Process given array of commandline arguments, handling short
+ * and long options by calling the respective callback functions.
+ *
+ * @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
  */
 BOOL th_args_process(int argc, char *argv[],
      const th_optarg *opts, const int nopts,
@@ -157,7 +179,12 @@
 }
 
 
-/* Print help for commandline arguments/options
+/**
+ * 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)
  */
 void th_args_help(FILE *fh,
     const th_optarg *opts, const int nopts,
--- a/th_args.h	Fri Apr 07 02:49:08 2017 +0300
+++ b/th_args.h	Wed May 10 21:00:37 2017 +0300
@@ -5,6 +5,8 @@
  *
  * Please read file 'COPYING' for information on license and distribution.
  */
+/// @file
+/// @brief Simple commandline argument processing function
 #ifndef TH_ARGS
 #define TH_ARGS
 
@@ -15,27 +17,29 @@
 extern "C" {
 #endif
 
-/* Option flags
+/** @def Option argument flags
  */
-#define OPT_NONE             (0)    // Simple option with no arguments
-#define OPT_ARGREQ           (1)    // Option requires an argument
-#define OPT_ARGMASK          (1)    // Mask for option argument flags
+#define OPT_NONE             (0)    ///< Simple option with no arguments
+#define OPT_ARGREQ           (1)    ///< Option requires an argument
+#define OPT_ARGMASK          (1)    ///< Mask for option argument flags
 
-#define OPTH_BAILOUT         0x0001 // Bail out on errors
-#define OPTH_ONLY_OPTS       0x0010 // Handle only options
-#define OPTH_ONLY_OTHER      0x0020 // Handle only "non-options"
-#define OPTH_ONLY_MASK       0x00f0 // Mask
+/** @def Option processing flags
+ */
+#define OPTH_BAILOUT         0x0001 ///< Bail out on errors
+#define OPTH_ONLY_OPTS       0x0010 ///< Handle only options
+#define OPTH_ONLY_OTHER      0x0020 ///< Handle only "non-options"
+#define OPTH_ONLY_MASK       0x00f0 ///< Mask
 
 
-/* Option argument structure
+/** Option argument structure
  */
 typedef struct
 {
-    int id;
-    char o_short;
-    char *o_long;
-    char *desc;
-    int flags;
+    int id;           ///< Option ID (should be unique for each option)
+    char o_short;     ///< Short option name (one character)
+    char *o_long;     ///< Long option name
+    char *desc;       ///< Option description
+    int flags;        ///< Flags (see OPT_*)
 } th_optarg;
 
 
--- a/th_crypto.h	Fri Apr 07 02:49:08 2017 +0300
+++ b/th_crypto.h	Wed May 10 21:00:37 2017 +0300
@@ -7,6 +7,8 @@
  * written by Colin Plumb in 1993, no copyright is claimed.
  * This code is in the public domain; do with it what you wish.
  */
+/// @file
+/// @brief Cryptography and hash related functions
 #ifndef TH_CRYPTO_H
 #define TH_CRYPTO_H 1
 
@@ -22,17 +24,22 @@
 #endif
 
 
+/** @def MD5 digest related defines
+ */
 #define TH_MD5HASH_LENGTH       (16)
 #define TH_MD5HASH_LENGTH_CH    (TH_MD5HASH_LENGTH * 2)
 
+
+/** MD5 digest state structure
+ */
 typedef struct
 {
-    uint32_t bits[2];    // Message length in bits, lsw first
-    uint32_t buf[4];     // Digest buffer
-    uint8_t in[64];      // Accumulate block
+    uint32_t bits[2];    ///< Message length in bits, lsw first
+    uint32_t buf[4];     ///< Digest buffer
+    uint8_t in[64];      ///< Accumulate block
 } th_md5state_t;
 
-typedef uint8_t th_md5hash_t[TH_MD5HASH_LENGTH];
+typedef uint8_t th_md5hash_t[TH_MD5HASH_LENGTH]; ///< A structure containing MD5 digest hash
 
 
 void    th_md5_init(th_md5state_t *ctx);
--- a/th_file.h	Fri Apr 07 02:49:08 2017 +0300
+++ b/th_file.h	Wed May 10 21:00:37 2017 +0300
@@ -5,6 +5,8 @@
  *
  * Please read file 'COPYING' for information on license and distribution.
  */
+/// @file
+/// @brief File, path, etc. related helper functions
 #ifndef TH_FILE_H
 #define TH_FILE_H
 
--- a/th_ioctx.h	Fri Apr 07 02:49:08 2017 +0300
+++ b/th_ioctx.h	Wed May 10 21:00:37 2017 +0300
@@ -23,26 +23,28 @@
 struct th_ioctx_ops;
 
 
+/** I/O context structure
+ */
 typedef struct th_ioctx
 {
-    char *filename;
-    char *mode;
-    void *data;
-    time_t atime;
-    int64_t size;
-    int status;
-    size_t line;
+    char *filename;     ///< Context filename, if any. May be NULL.
+    char *mode;         ///< Context's stdio open "mode", may also be NULL.
+    void *data;         ///< Internal data
+    time_t atime;       ///< Last access time
+    int64_t size;       ///< Size in bytes
+    int status;         ///< Status
+    size_t line;        ///< Line number
 
     void (*error)(struct th_ioctx *, const int err, const char *msg);
     void (*msg)(struct th_ioctx *, const int level, const char *msg);
 
-    const struct th_ioctx_ops *fops;
+    const struct th_ioctx_ops *fops; ///< Pointer to I/O ops struct to be used with this context
 } th_ioctx;
 
 
 typedef struct th_ioctx_ops
 {
-    char    *name;
+    char    *name;                   ///< Name of this I/O ops definition
 
     int     (*fopen)(th_ioctx *ctx);
     void    (*fclose)(th_ioctx *ctx);