Re: [PATCH v3] api-parse-options: add missing flags and macros

[Junio C Hamano <gitster@pobox.com>]

Karthik Nayak <karthik.188@gmail.com> writes:

> The 'Documentation/technical/api-parse-options.adoc' contains
> documentation around the parse-options API. The document is missing some
> of the macros and flags provided by the API.
>
> Add the missing flags 'PARSE_OPT_ONE_SHOT' and 'PARSE_OPT_SHELL_EVAL' to
> the documentation. While 'PARSE_OPT_ONE_SHOT' was introduced in
> 202fbb3315 (parse-options: add one-shot mode, 2019-01-27) as a temporary
> flag, it is now 7 years and still exists. So let's document it, as when
> the time comes, it is always easy to remove the same.
>
> Also add the following missing macros:
>   - OPT__SUPER_PREFIX
>   - OPT__VERBOSITY
>   - OPT_BITOP
>   - OPT_STRVEC
>   - OPT_UYN
>   - OPT_NOOP_ARG
>   - OPT_COLUMN
>   - OPT_CONTAINS
>   - OPT_NO_CONTAINS
>   - OPT_WITH
>   - OPT_WITHOUT
>   - OPT_CLEANUP
>   - OPT_PATHSPEC_FROM_FILE
>   - OPT_PATHSPEC_FILE_NUL
>   - OPT_AUTOSTASH
>   - OPT_DIFF_UNIFIED
>   - OPT_DIFF_INTERHUNK_CONTEXT
>   - OPT_IPVERSION
>   - OPT_ALIAS
>
> This brings the technical documentation in line with the code in
> 'parse-options.h'.
>
> While here, add the missing `flags` argument to `OPT__FORCE`.
>
> Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
> ---
> I was reading the docs while reviewing another series and ended
> up finding some missing documentation. This patch tries to cover
> that. Some of these might be options/flags we rarely use, but I
> strongly feel its easier to make choices when there is adequate
> documentation.
> ---
> Changes in v3:
> - Fix typo and rename the variable

OK.  Matching the parameters of OPT_ALIAS() the documentation uses
to what is actually used in parse-options.h header makes sense.

Have we reached the point of diminishing returns now?

Thanks.