Skip to content

Commit 06f52a4

Browse files
authored
Document option no option pattern better (#3103)
2 parents 8533c96 + 9c2f183 commit 06f52a4

File tree

1 file changed

+7
-2
lines changed

1 file changed

+7
-2
lines changed

docs/options.md

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -257,8 +257,7 @@ Boolean options (boolean flags) take the value True or False. The simplest case
257257
258258
```
259259

260-
To implement this more explicitly, pass in on-option `/` off-option. Click will automatically set `is_flag=True`. Click always wants you to provide an enable
261-
and disable flag so that you can change the default later.
260+
To implement this more explicitly, pass in on-option `/` off-option. Click will automatically set `is_flag=True`.
262261

263262
```{eval-rst}
264263
.. click:example::
@@ -280,6 +279,12 @@ and disable flag so that you can change the default later.
280279
invoke(info, args=['--no-shout'])
281280
```
282281

282+
Use cases for this more explicit pattern include:
283+
284+
* The default can be dynamic so the user can explicitly specify the option with either on or off option, or pass in no option to use the dynamic default.
285+
* Shell scripts sometimes want to be explicit even when it's the default
286+
* Shell aliases can set a flag, then an invocation can add a negation of the flag
287+
283288
If a forward slash(`/`) is contained in your option name already, you can split the parameters using `;`. In Windows `/` is commonly used as the prefix character.
284289

285290
```{eval-rst}

0 commit comments

Comments
 (0)