api-parse-options.adoc: document per-option flags

The "Flags" section in "Documentation/technical/api-parse-options.adoc"
documents the flags that can be passed to parse_options() itself. It
does not, however, document the flags that can be set on individual
options through the `flags` member of `struct option` (and through the
`OPT_*_F()` macro variants).

These per-option flags are used throughout the codebase (for example
`PARSE_OPT_HIDDEN` is used to hide an option from `-h` while still
showing it with `--help-all`), but a reader currently has to dig into
"parse-options.h" to find them.

To remediate that, let's add an "Option flags" subsection to the
"Data Structure" section, just before the list of option macros.

Let's also make it explicit that these are distinct from the
parse_options() flags described earlier, and let's describe the `-h`
versus `--help-all` behavior for `PARSE_OPT_HIDDEN`.

Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/technical/api-parse-options.adoc b/Documentation/technical/api-parse-options.adoc
index 880eb94642587aa71b2c6e6655c4d7ef797b1cc7..fb4580e75556e062809988cb28c2c3faad6dfc5a 100644 (file)
--- a/Documentation/technical/api-parse-options.adoc
+++ b/Documentation/technical/api-parse-options.adoc
@@ -150,6 +150,67 @@ Data Structure
 
 The main data structure is an array of the `option` struct,
 say `static struct option builtin_add_options[]`.
+
+Option flags
+~~~~~~~~~~~~
+
+Each option can carry flags in the `flags` field of its `option`
+struct. These are per-option flags and are distinct from the
+`parse_options()` flags described above; they are usually set through
+the `OPT_*_F()` macro variants (see below) rather than by hand. They
+are the bitwise-or of:
+
+`PARSE_OPT_OPTARG`::
+       The option's argument is optional, i.e. both `--option` and
+       `--option=<value>` are accepted.
+
+`PARSE_OPT_NOARG`::
+       The option takes no argument at all. Using `--option=<value>`
+       is rejected.
+
+`PARSE_OPT_NONEG`::
+       Disable the automatically generated negated `--no-option`
+       form.
+
+`PARSE_OPT_HIDDEN`::
+       Hide the option: it is omitted from the usage shown by
+       `git <cmd> -h`, but is still shown by `git <cmd> --help-all`.
+       The option is parsed as usual either way. This is meant for
+       deprecated, advanced or otherwise uncommon options.
+
+`PARSE_OPT_LASTARG_DEFAULT`::
+       Use the default value (`defval`) when the option is used
+       without an argument, even for an option that normally requires
+       one. Only the last argument on the command line takes effect.
+
+`PARSE_OPT_NODASH`::
+       The option is a single character without a leading dash, such
+       as the `+` used by some commands.
+
+`PARSE_OPT_LITERAL_ARGHELP`::
+       Use the argument help string (`argh`) verbatim in the usage
+       output instead of surrounding it with `<>` or `[]`. Useful when
+       `argh` already contains a hand-formatted description.
+
+`PARSE_OPT_FROM_ALIAS`::
+       Internal flag, set on options that were expanded from a
+       configured alias. It should not be set by callers.
+
+`PARSE_OPT_NOCOMPLETE`::
+       Do not offer this option for completion.
+
+`PARSE_OPT_COMP_ARG`::
+       The option's argument, rather than the option itself, is what
+       should be completed.
+
+`PARSE_OPT_CMDMODE`::
+       The option is one of several mutually exclusive "command mode"
+       options that share the same variable. Using more than one of
+       them at once is rejected.
+
+Macros
+~~~~~~
+
 There are some macros to easily define options:
 
 `OPT__ABBREV(&int_var)`::