Re: [PATCH] api-parse-options.txt: document OPT_CMDMODE()

> Pranit Bauva <pranit.bauva@gmail.com> writes:
>
>> OPT_CMDMODE() was introduced in the release of 1.8.5 which makes the use
>> of subcommands in the form of arguments a lot cleaner and easier.
>> ---
>
> Sign-off?

>>  Documentation/technical/api-parse-options.txt | 6 ++++++
>>  1 file changed, 6 insertions(+)
>>
>> diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt
>> index 5f0757d..8130d26 100644
>> --- a/Documentation/technical/api-parse-options.txt
>> +++ b/Documentation/technical/api-parse-options.txt
>> @@ -231,6 +231,12 @@ There are some macros to easily define options:
>>       pass the command-line option, which can be specified multiple times,
>>       to another command.
>>
>> +`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
>> +     Introduce an option for subcommands. It is useful when you want to use
>> +     the command with a particular sub command only and ignore other sub
>> +     commands it has. It will set `int_var` to enum_val if the argument is
>> +     invoked.
>> +
>
> Sorry, but I do not get what "when you want to... ignore other sub
> command it has" wants to say.

> CMDMODE is a mechanism to actively notice when multiple "operation
> mode" options that specify mutually incompatible operation modes are
> given and error out without the user of parse_options() to implement
> that mutual exclusion herself.  That is, if you have 'add', 'remove'
> and 'edit' operation modes, with OPT_BOOL(), you would have to say:
>
>         options[] = {
>                 OPT_BOOL('a', "add", &add, ...),
>                 OPT_BOOL('r', "remove", &remove, ...),
>                 OPT_BOOL('e', "edit", &edit, ...),
>                 ...
>         };
>         parse_options(ac, av, prefix, options, ...);
>
>         if (!!add + !!remove + !!edit > 1)
>                 die("at most one add/remove/edit can be used at a time");
>
>         if (add)
>                 do_add();
>         if (remove)
>                 do_remove();
>         if (edit)
>                 do_edit();
>
> but with CMDMODE, you can do:
>
>         options[] = {
>                 OPT_BOOL('a', "add", &mode, ...),
>                 OPT_BOOL('r', "remove", &mode, ...),
>                 OPT_BOOL('e', "edit", &mode, ...),
>                 ...
>         };
>         parse_options(ac, av, prefix, options, ...);
>
>         switch (mode) {
>         case 'a': do_add(); break;
>         case 'r': do_remove(); break;
>         case 'e': do_edit(); break;
>                 ...
>         }
>
> and parse_options notices that "mode" is shared across these three
> options, and implements the mutual-exclusion itself.