Re: [PATCH v3 1/5] doc: add documentation for OPT_STRING_LIST

Jacob Keller [off-list ref] writes:

I do not know if it is clear enough that 'option' in the last
sentence is a placeholder.  I then wondered if spelling it as
`--no-<long>` would make it a bit clearer, but that is ugly.

The "Reset the list" is an instruction to the end-users who interact
with a program written by readers of this document using
OPT_STRING_LIST(), and it feels a bit out of place.  Perhaps

	End users can reset the list by negating the option,
	i.e. passing "--no-<long>", on the command line.

I dunno.

Anyway, thanks for adding a missing doc here.

 `OPT_INTEGER(short, long, &int_var, description)`::
 	Introduce an option with integer argument.
 	The integer is put into `int_var`.

From: "Junio C Hamano" <redacted>
v3 1/5] doc: add documentation for OPT_STRING_LIST

Jacob Keller [off-list ref] writes:

quoted

From: Jacob Keller <redacted>

Commit c8ba16391655 ("parse-options: add OPT_STRING_LIST helper",
2011-06-09) added the OPT_STRING_LIST as a way to accumulate a repeated
list of strings. However, this was not documented in the
api-parse-options documentation. Add documentation now so that future
developers may learn of its existence.

Signed-off-by: Jacob Keller <redacted>
---
 Documentation/technical/api-parse-options.txt | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/technical/api-parse-options.txt 

b/Documentation/technical/api-parse-options.txt
index 27bd701c0d68..6914f54f5f44 100644

--- a/Documentation/technical/api-parse-options.txt
+++ b/Documentation/technical/api-parse-options.txt

@@ -168,6 +168,11 @@ There are some macros to easily define options:
 Introduce an option with string argument.
 The string argument is put into `str_var`.

+`OPT_STRING_LIST(short, long, &list, arg_str, description)`::
+ Introduce an option with string argument.
+ The string argument is stored as an element in `&list` which must be a
+ struct string_list. Reset the list using `--no-option`.
+

I do not know if it is clear enough that 'option' in the last
sentence is a placeholder.  I then wondered if spelling it as
`--no-<long>` would make it a bit clearer, but that is ugly.

Bikeshedding:: `--no-<option>` maybe, i.e. just surround the option word 
with the angle brackets to indicate it is to be replaced by the real 
option's name.

The "Reset the list" is an instruction to the end-users who interact
with a program written by readers of this document using
OPT_STRING_LIST(), and it feels a bit out of place.  Perhaps

End users can reset the list by negating the option,
i.e. passing "--no-<long>", on the command line.

I dunno.

Anyway, thanks for adding a missing doc here.

quoted

 `OPT_INTEGER(short, long, &int_var, description)`::
 Introduce an option with integer argument.
 The integer is put into `int_var`.

--

Philip 

On Wed, Jan 18, 2017 at 11:45 AM, Junio C Hamano [off-list ref] wrote:

I do not know if it is clear enough that 'option' in the last
sentence is a placeholder.  I then wondered if spelling it as
`--no-<long>` would make it a bit clearer, but that is ugly.

To be fair, this is exactly how the rest of the doc spells these
things, so I would rather be consistent with the doc as is, and a
future patch could clean this up. See OPT_SET_INT, for an example of
`--no-option`.

The "Reset the list" is an instruction to the end-users who interact
with a program written by readers of this document using
OPT_STRING_LIST(), and it feels a bit out of place.  Perhaps

        End users can reset the list by negating the option,
        i.e. passing "--no-<long>", on the command line.

I dunno.

Maybe we can rephrase this "The list is reset via `--no-option`"?

Thanks,
Jake