From ea5afaacc7100ecfc2c440879a1fb80715be2779 Mon Sep 17 00:00:00 2001 From: Tom Huang Date: Sat, 19 Oct 2024 16:17:14 -0700 Subject: [PATCH] docs: add doxygen documentation --- src/argtable3.h | 120 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 119 insertions(+), 1 deletion(-) diff --git a/src/argtable3.h b/src/argtable3.h index cb190f5..fc0acbb 100644 --- a/src/argtable3.h +++ b/src/argtable3.h @@ -214,11 +214,129 @@ typedef struct arg_cmd_info { /**** arg_xxx constructor functions *********************************/ +/** + * Creates a data type in the syntax or add a new line in the glossary. + * + * Sometimes you will wish to add extra lines of text to the glossary, or even + * put your own text into the syntax string generated by arg_print_syntax. You + * can add newline characters to your argument table strings if you wish, but it + * soon gets ugly. A better way is to add `arg_rem` structs to your argument + * table. They are dummy argument table entries in the sense that they do not + * alter the argument parsing but their datatype and glossary strings do appear + * in the output generated by the arg_print_syntax and arg_print_glossary + * functions. The name `arg_rem` is for *remark*, and it is inspired by the + * `REM` statement used in the BASIC language. + * + * For example, in the `mv` example program, we use `arg_rem` to add additional + * lines for the `-u|--update` option in the glossary: + * ``` + * struct arg_lit *update = arg_litn("u", "update", 0, 1, "copy only when SOURCE files are"); + * struct arg_rem *update1 = arg_rem(NULL, " newer than destination files"); + * struct arg_rem *update1 = arg_rem(NULL, " or when destination files"); + * struct arg_rem *update2 = arg_rem(NULL, " are missing"); + * ``` + * + * which will make the glossay look like: + * ``` + * -u, --update copy only when SOURCE files are + * newer than destination files + * or when the destination files + * are missing + * ``` + * + * We also use `arg_rem` to add a data type entry for the ordinary argument in + * the syntax: + * ``` + * struct arg_rem *dest = arg_rem ("DEST|DIRECTORY", NULL); + * ``` + * + * which will make the syntax look like: + * ``` + * $ mv --help + * Usage: mv [-bfiuv] [--backup=[CONTROL]] [--reply={yes,no,query}] + * [--strip-trailing-slashes] [-S SUFFIX] [--target-directory=DIRECTORY] + * [--help] [--version] SOURCE [SOURCE]... DEST|DIRECTORY + * ``` + * + * @param datatype A pointer to a WNDCLASSEX structure. You must fill the + * structure with the appropriate class attributes before passing it to the + * function. + * @param glossary The second one, which follows @p datatype. + * + * @return + * If successful, `arg_rem` returns a pointer to the allocated `struct + * arg_rem`. Otherwise, `arg_rem` returns `NULL` if there is insufficient + * memory available. + */ ARG_EXTERN struct arg_rem* arg_rem(const char* datatype, const char* glossary); +/** + * Creates a literal argument that does not take an argument value. + * + * A literal argument is usually used to express a boolean flag, such as `-h` + * and `--version`. However, since a literal argument can appear multiple times + * in a command line, we can use the number of occurrence as an implicit + * argument value. + * + * For example, the `tar` utility uses `--verbose` or `-v` to show the files + * being worked on as `tar` is creating an archive: + * ``` + * $ tar -cvf afiles.tar apple angst aspic + * apple + * angst + * aspic + * ``` + * + * Each occurrence of `--verbose` or `-v` on the command line increases the + * verbosity level by one. Therefore, if you need more details on the output, + * specify it twice: + * ``` + * $ tar -cvvf afiles.tar apple angst aspic + * -rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple + * -rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst + * -rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic + * ``` + * + * `arg_lit0` is a helper function of `arg_litn` when we specify `mincount` to + * `0` and `maxcount` to `1`. `arg_lit1` is a helper function of `arg_litn` when + * we specify both `mincount` and `maxcount` to `1`. These helper functions are + * considered deprecated, but they will be kept for backward compatibility. You + * should use `arg_litn` in new projects, since it is more explicit and easier + * to understand. + * + * **Example** Creating literal arguments + * ``` + * struct arg_lit *list = arg_litn("lL",NULL, 0, 1, "list files"); + * struct arg_lit *verbose = arg_litn("v","verbose,debug", 0, 3, "verbosity level"); + * struct arg_lit *help = arg_litn("h","help", 0, 1, "print this help"); + * struct arg_lit *version = arg_litn(NULL,"version", 0, 1, "print version info"); + * ``` + * + * @param shortopts A string of single characters, and each character is an + * alternative short option name of the argument. For example, `"kKx"` + * means you can use `-k`, `-K`, or `-x` as the short options. If you + * don't want to use any short option, pass `NULL` to this parameter. + * @param longopts A string of alternative long option names of the argument, + * separated by commas. For example, `"verbose,debug"` means you can use + * `--verbose` or `--debug` as the long options. If you don't want to use + * any long option, pass `NULL` to this parameter. + * @param mincount The minimum number of the argument. Setting it to `0` means + * that the argument is optional. + * @param maxcount The maximum number of the argument. The value of `maxcount` + * decides how much memory we need to allocate to store argument values. + * Choose a reasonable value, so we don't increase unnecessary memory + * usage. + * @param glossary A short description of the argument. If you don't want to + * display this argument in the glossary, pass `NULL` to this parameter. + * + * @return + * If successful, `arg_litn`, `arg_lit0`, and `arg_lit1` return a pointer to + * the allocated `struct arg_lit`. Otherwise, these functions return `NULL` if + * there is insufficient memory available. + */ +ARG_EXTERN struct arg_lit* arg_litn(const char* shortopts, const char* longopts, int mincount, int maxcount, const char* glossary); ARG_EXTERN struct arg_lit* arg_lit0(const char* shortopts, const char* longopts, const char* glossary); ARG_EXTERN struct arg_lit* arg_lit1(const char* shortopts, const char* longopts, const char* glossary); -ARG_EXTERN struct arg_lit* arg_litn(const char* shortopts, const char* longopts, int mincount, int maxcount, const char* glossary); ARG_EXTERN struct arg_int* arg_int0(const char* shortopts, const char* longopts, const char* datatype, const char* glossary); ARG_EXTERN struct arg_int* arg_int1(const char* shortopts, const char* longopts, const char* datatype, const char* glossary);