# HG changeset patch # User Matti Hamalainen # Date 1494439237 -10800 # Node ID 9148bc3fa838a91cf42958a073d103a103cf76ca # Parent 468d521240c65123f39914ac38aef0487eff3f87 Begin adding Doxygen documentation for some things. Very rudimentary, and most things are not documented yet. diff -r 468d521240c6 -r 9148bc3fa838 th_args.c --- 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, diff -r 468d521240c6 -r 9148bc3fa838 th_args.h --- 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; diff -r 468d521240c6 -r 9148bc3fa838 th_crypto.h --- 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); diff -r 468d521240c6 -r 9148bc3fa838 th_file.h --- 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 diff -r 468d521240c6 -r 9148bc3fa838 th_ioctx.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);