revise 'Options' documentation #3192
Conversation
|
I will have to take a closer look at this. At first glance you made some good grammatical fixes, but also made some changes that obscure what is meant. Sometimes it's best not to use the most technical terms available because people may not know what you mean. |
|
I appreciate the feedback, and after re-reading I definitely agree that some of the changes need more work (particularly the Option Decorator section). I have some ideas for improvements that might be a nicer middle ground, but I'll wait for your closer review before making any changes. |
|
|
||
| Click expects you to pass at least two positional arguments to the option decorator. They are option name and function argument name. | ||
| The {func}`option()` decorator accepts parameter declarations as positional arguments. Parameter declarations can consist of any number of option names and, optionally, a single identifier matching an argument name in the decorated callback function. | ||
|
|
There was a problem hiding this comment.
The {func}option() decorator is usually passed two positional arguments, the option name and the decorated function name.
|
|
||
| However, if you don't pass in the function argument name, then Click will try to infer it. A simple way to name your option is by taking the function argument, adding two dashes to the front and converting underscores to dashes. In this case, Click will infer the function argument name correctly so you can add only the option name. | ||
| If an identifier for the callback argument is not declared, then Click will try to infer it. A simple way to name an option is by prepending `--` to the callback argument name and converting underscores to `-`; this ensures that Click can correctly infer the callback argument name. Consequently, {func}`option()` only requires declarations for the option name(s). | ||
|
|
There was a problem hiding this comment.
However, if the decorated function name is not passed in, then Click will try to infer it. A simple way to name the option so that Click will infer it correctly is by taking the function argument, adding two dashes to the front and converting underscores to dashes
2 participants
#3175
If #3191 is approved I'd be happy to go back and handle any merge conflicts caused by this PR's changes.
Clarity improvements
The "Option Decorator" section refers to "positional arguments" of the
click.option()decorator and to the "function argument" of the decorated callback function. Using "positional arguments" as shorthand for "positional arguments passed to theoption()decorator" introduces ambiguity, because the decorated function can also accept positional arguments (and in fact does in every provided example). Using "function" as shorthand for "decorated function" is also ambiguous. References to the positional arguments forclick.option()are changed to "parameter declarations" (for consistency with the API docs), and "function argument" is replaced with the more specific "callback argument".When describing the steps to infer the callback argument name from the parameter declarations, the following is misleading (possibly outdated?):
The actual criteria is that the argument is a valid identifier, i.e.
str.isidentifier()returnsTrue(seeOption._parse_decls()). A string that is "prefixed" with_would therefore be chosen. The step is updated to reflect this and links to Python's "Lexical analysis" documentation.Several sections use "pass in" back-to-back when referencing
option()arguments and command line usage. This makes it unclear when the command line usage is being referenced. When referring tooption(), instead use "declare" for positional arguments or "set" for keyword arguments.Consistency improvements
All instances of "underlying function" are replaced with "decorated function".
References to "dash(es)" are replaced with
-or--. This establishes consistency with the "Other Prefix Characters" section and allows for several sentences to be reworded for concision.Miscellaneous
Minor grammar and concision edits throughout.