From: "Junio C Hamano" <gitster@xxxxxxxxx>
v3 1/5] doc: add documentation for OPT_STRING_LIST
Jacob Keller <jacob.e.keller@xxxxxxxxx> writes:
From: Jacob Keller <jacob.keller@xxxxxxxxx>
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 <jacob.keller@xxxxxxxxx>
---
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.
`OPT_INTEGER(short, long, &int_var, description)`::
Introduce an option with integer argument.
The integer is put into `int_var`.
--
Philip