From d85a30845731920e74efc2078b54a0158d2d22cc Mon Sep 17 00:00:00 2001 From: Panu Matilainen Date: Mon, 4 Mar 2024 11:37:50 +0200 Subject: [PATCH] Add minimal docs to everything in popt.h --- src/popt.h | 84 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 64 insertions(+), 20 deletions(-) diff --git a/src/popt.h b/src/popt.h index 22a9e0b..26cfd42 100644 --- a/src/popt.h +++ b/src/popt.h @@ -36,8 +36,8 @@ #define POPT_ARG_SHORT 13U /*!< arg ==> short */ #define POPT_ARG_BITSET (16U+14U) /*!< arg ==> bit set */ -#define POPT_ARG_MASK 0x000000FFU -#define POPT_GROUP_MASK 0x0000FF00U +#define POPT_ARG_MASK 0x000000FFU /*!< option type mask */ +#define POPT_GROUP_MASK 0x0000FF00U /*!< option group mask */ /** * \name Arg modifiers @@ -54,7 +54,7 @@ #define POPT_ARGFLAG_XOR 0x02000000U /*!< arg will be xor'ed */ #define POPT_ARGFLAG_NOT 0x01000000U /*!< arg will be negated */ #define POPT_ARGFLAG_LOGICALOPS \ - (POPT_ARGFLAG_OR|POPT_ARGFLAG_AND|POPT_ARGFLAG_XOR) + (POPT_ARGFLAG_OR|POPT_ARGFLAG_AND|POPT_ARGFLAG_XOR) /*!< arg has a logical op */ #define POPT_BIT_SET (POPT_ARG_VAL|POPT_ARGFLAG_OR) /*!< set arg bit(s) */ @@ -105,6 +105,7 @@ #define POPT_CONTEXT_ARG_OPTS (1U << 4) /*!< return args as options with value 0 */ /** + * Defines a single option that may passed to the program. */ struct poptOption { const char * longName; /*!< may be NULL */ @@ -122,7 +123,7 @@ struct poptOption { struct poptAlias { const char * longName; /*!< may be NULL */ char shortName; /*!< may be NUL */ - int argc; + int argc; /*!< argument count */ const char ** argv; /*!< must be free()able */ }; @@ -143,6 +144,9 @@ typedef struct poptItem_s { * Empty table marker to enable displaying popt alias/exec options. */ extern struct poptOption poptAliasOptions[]; +/** + * Include in your options table for automatic alias/exec option listing + */ #define POPT_AUTOALIAS { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptAliasOptions, \ 0, "Options implemented via popt alias/exec:", NULL }, @@ -151,24 +155,35 @@ extern struct poptOption poptAliasOptions[]; */ extern struct poptOption poptHelpOptions[]; +/** + * Localized popt options + */ extern struct poptOption * poptHelpOptionsI18N; +/** + * Include in your options table for automatic help option listing + */ #define POPT_AUTOHELP { NULL, '\0', POPT_ARG_INCLUDE_TABLE, poptHelpOptions, \ 0, "Help options:", NULL }, - +/** + * Include in your options table as the last element + */ #define POPT_TABLEEND { NULL, '\0', 0, NULL, 0, NULL, NULL } /** + * The main popt context type */ typedef struct poptContext_s * poptContext; /** + * The main popt option type */ #ifndef __cplusplus typedef struct poptOption * poptOption; #endif /** + * Callback reason values */ enum poptCallbackReason { POPT_CALLBACK_REASON_PRE = 0, @@ -323,14 +338,14 @@ int poptSaneFile(const char * fn); /** * Read a file into a buffer. * @param fn file name - * @retval *bp buffer (malloc'd) (or NULL) - * @retval *nbp no. of bytes in buffer (including final NUL) (or NULL) + * @param[out] *bp buffer (malloc'd) (or NULL) + * @param[out] *nbp no. of bytes in buffer (including final NUL) (or NULL) * @param flags 1 to trim escaped newlines * return 0 on success */ int poptReadFile(const char * fn, char ** bp, size_t * nbp, int flags); -#define POPT_READFILE_TRIMNEWLINES 1 +#define POPT_READFILE_TRIMNEWLINES 1 /*!< trim new lines on read? */ /** * Read configuration file. @@ -366,8 +381,8 @@ int poptReadDefaultConfig(poptContext con, int useEnv); * * @param argc no. of arguments * @param argv argument array - * @retval argcPtr address of returned no. of arguments - * @retval argvPtr address of returned argument array + * @param[out] argcPtr address of returned no. of arguments + * @param[out] argvPtr address of returned argument array * @return 0 on success, POPT_ERROR_NOARG on failure */ int poptDupArgv(int argc, const char **argv, @@ -382,8 +397,8 @@ int poptDupArgv(int argc, const char **argv, * be free'd. * * @param s string to parse - * @retval argcPtr address of returned no. of arguments - * @retval argvPtr address of returned argument array + * @param[out] argcPtr address of returned no. of arguments + * @param[out] argvPtr address of returned argument array */ int poptParseArgvString(const char * s, int * argcPtr, const char *** argvPtr); @@ -492,7 +507,7 @@ int poptStrippedArgv(poptContext con, int argc, char ** argv); /** * Add a string to an argv array. - * @retval *argvp argv array + * @param[out] *argvp argv array * @param argInfo (unused) * @param val string arg to add (using strdup) * @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION @@ -541,30 +556,59 @@ int poptSaveShort(short * arg, unsigned int argInfo, long aLong); */ int poptSaveInt(int * arg, unsigned int argInfo, long aLong); -/* The bit set typedef. */ +/** + * The bit set typedef. + */ typedef struct poptBits_s { - unsigned int bits[1]; + unsigned int bits[1]; /*!< internal */ } * poptBits; #define _POPT_BITS_N 1024U /*!< estimated population */ -#define _POPT_BITS_M ((3U * _POPT_BITS_N) / 2U) +#define _POPT_BITS_M ((3U * _POPT_BITS_N) / 2U) /*!< internal */ #define _POPT_BITS_K 16U /*!< no. of linear hash combinations */ -extern unsigned int _poptBitsN; -extern unsigned int _poptBitsM; -extern unsigned int _poptBitsK; +extern unsigned int _poptBitsN; /*!< internal */ +extern unsigned int _poptBitsM; /*!< internal */ +extern unsigned int _poptBitsK; /*!< internal */ +/** + * Add bits + */ int poptBitsAdd(poptBits bits, const char * s); + +/** + * Test bits + */ int poptBitsChk(poptBits bits, const char * s); + +/** + * Clear bitfield + */ int poptBitsClr(poptBits bits); + +/** + * Delete bits + */ int poptBitsDel(poptBits bits, const char * s); + +/** + * Test for bit intersection + */ int poptBitsIntersect(poptBits * ap, const poptBits b); + +/** + * Test for bit union + */ int poptBitsUnion(poptBits * ap, const poptBits b); + +/** + * Args + */ int poptBitsArgs(poptContext con, poptBits * ap); /** * Save a string into a bit set (experimental). - * @retval *bits bit set (lazily malloc'd if NULL) + * @param[out] bitsp bit set (lazily malloc'd if NULL) * @param argInfo logical operation (see POPT_ARGFLAG_*) * @param s string to add to bit set * @return 0 on success, POPT_ERROR_NULLARG/POPT_ERROR_BADOPERATION