Re: [PATCH] parse-options: document automatic PARSE_OPT_LITERAL_ARGHELP

["René Scharfe" <l.s.r@web.de>]

Am 20.01.22 um 19:25 schrieb Junio C Hamano:
> René Scharfe <l.s.r@web.de> writes:
>
>> Now that I read the whole comment, I think the right place to introduce
>> the automatic brackets is the description of argh some lines up.
>>
>> --- >8 ---
>> Subject: [PATCH 5/5] parse-options: document bracketing of argh
>>
>> Signed-off-by: René Scharfe <l.s.r@web.de>
>> ---
>>  parse-options.h | 5 +++++
>>  1 file changed, 5 insertions(+)
>>
>> diff --git a/parse-options.h b/parse-options.h
>> index e22846d3b7..88d589d159 100644
>> --- a/parse-options.h
>> +++ b/parse-options.h
>> @@ -85,6 +85,11 @@ typedef enum parse_opt_result parse_opt_ll_cb(struct parse_opt_ctx_t *ctx,
>>   *   token to explain the kind of argument this option wants. Does not
>>   *   begin in capital letter, and does not end with a full stop.
>>   *   Should be wrapped by N_() for translation.
>> + *   Is automatically enclosed in brackets when printed, unless it
>> + *   contains any of the following characters: ()<>[]|
>> + *   E.g. "name" is shown as "<name>" to indicate that a name value
>> + *   needs to be supplied, not the literal string "name", but
>> + *   "<start>,<end>" and "(this|that)" are printed verbatim.
>>   *
>>   * `help`::
>>   *   the short help associated to what the option does.
>
> Very nice.
>
> This version gives the necessary information in (almost) one place.
>
> I said (almost) because "it contains any of ..." is not the only way
> to decline the <automatic angle brackets>, and am wondering if it is
> more helpful to say something like
>
> 	... when printed, unless PARSE_OPT_LITERAL_ARGHELP is set in
> 	the flags, or it contains any of the following characters: ...
>
> and then shrink the description of the flag bit to
>
>     PARSE_OPT_LITERAL_ARGHELP: controls if `argh` is enclosed in in
>     brackets when shown (see the description on `argh` above).
>

The idea was to document the base behavior at the top and the effects of
flags at the bottom.  Blurring this distinction and cross-referencing
gives a better whole, though, I agree.  It would have helped me find the
right place to put the list of special chars, for one thing.  So how
about this?

--- >8 ---
Subject: [PATCH v2] parse-options: document bracketing of argh

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: René Scharfe <l.s.r@web.de>
---
 parse-options.h | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/parse-options.h b/parse-options.h
index e22846d3b7..2e801b3c9a 100644
--- a/parse-options.h
+++ b/parse-options.h
@@ -85,6 +85,11 @@ typedef enum parse_opt_result parse_opt_ll_cb(struct parse_opt_ctx_t *ctx,
  *   token to explain the kind of argument this option wants. Does not
  *   begin in capital letter, and does not end with a full stop.
  *   Should be wrapped by N_() for translation.
+ *   Is enclosed in brackets when printed, unless PARSE_OPT_LITERAL_ARGHELP
+ *   is set in `flags` or it contains any of the following characters: ()<>[]|
+ *   E.g. "name" is shown as "<name>" to indicate that a name value
+ *   needs to be supplied, not the literal string "name", but
+ *   "<start>,<end>" and "(this|that)" are printed verbatim.
  *
  * `help`::
  *   the short help associated to what the option does.
@@ -105,9 +110,8 @@ typedef enum parse_opt_result parse_opt_ll_cb(struct parse_opt_ctx_t *ctx,
  *				not last it will require an argument.
  *				Should not be used with PARSE_OPT_OPTARG.
  *   PARSE_OPT_NODASH: this option doesn't start with a dash.
- *   PARSE_OPT_LITERAL_ARGHELP: says that argh shouldn't be enclosed in brackets
- *				(i.e. '<argh>') in the help message.
- *				Useful for options with multiple parameters.
+ *   PARSE_OPT_LITERAL_ARGHELP: says that `argh` shouldn't be enclosed in
+ *				brackets (see `argh` description above).
  *   PARSE_OPT_NOCOMPLETE: by default all visible options are completable
  *			   by git-completion.bash. This option suppresses that.
  *   PARSE_OPT_COMP_ARG: this option forces to git-completion.bash to
--
2.34.1