docs: add doxygen documentation

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);