kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

api-parse-options.adoc: document hidden and OPT_*_F option macros 

In "Documentation/technical/api-parse-options.adoc", the list of option
macros does not mention the `OPT_*_F()` macro variants that take a
trailing `flags` argument, nor the `OPT_HIDDEN_GROUP()` and
`OPT_HIDDEN_BOOL()` convenience macros.

Now that a previous commit documents the per-option flags, let's
document these macros too:

  - Add a paragraph explaining the `OPT_*_F` convention and how it
    relates to the per-option flags.

  - Document `OPT_HIDDEN_GROUP()`, introduced in a previous commit,
    right after `OPT_GROUP()`.

  - Document `OPT_HIDDEN_BOOL()` right after `OPT_BOOL()`.

Signed-off-by: Christian Couder <christian.couder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
main
Christian Couder 2026-08-11 10:33:05 +02:00 committed by Junio C Hamano
parent e455bade3a
commit 08b7e358e3
1 changed files with 18 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Documentation/technical/api-parse-options.adoc
View File

@ -214,6 +214,13 @@ Macros

There are some macros to easily define options:

Many of the macros below have an `_F` variant (for example `OPT_BOOL_F`,
`OPT_STRING_F`, `OPT_INTEGER_F`, `OPT_SET_INT_F`, `OPT_BIT_F` and
`OPT_CALLBACK_F`) that takes an additional trailing `flags` argument.
That argument is the bitwise-or of the per-option flags described in the
"Option flags" section above; the non-`_F` macros are simply defined
with `flags` set to `0`.

`OPT__ABBREV(&int_var)`::
Add `--abbrev[=<n>]`.

@ -237,10 +244,21 @@ There are some macros to easily define options:
describes the group or an empty string.
Start the description with an upper-case letter.

`OPT_HIDDEN_GROUP(description)`::
Like `OPT_GROUP()`, but the group header carries
`PARSE_OPT_HIDDEN`, so it is only shown by `--help-all` and not
by `-h`. Use it to label a group that contains only hidden
options, which would otherwise show an empty header under `-h`.

`OPT_BOOL(short, long, &int_var, description)`::
Introduce a boolean option. `int_var` is set to one with
`--option` and set to zero with `--no-option`.

`OPT_HIDDEN_BOOL(short, long, &int_var, description)`::
Like `OPT_BOOL()`, but the option carries `PARSE_OPT_HIDDEN`,
so it is hidden from `-h` while still being shown by
`--help-all`.

`OPT_COUNTUP(short, long, &int_var, description)`::
Introduce a count-up option.
Each use of `--option` increments `int_var`, starting from zero