docs: show optional command arguments as optional in usage
What does this MR do and why?
Seven commands mark an argument as required in their Use string while
Args accepts zero arguments, and their own Long text documents what happens
when the argument is omitted. The usage line contradicts the description
printed directly above it.
glab ssh-key delete --help shows it most clearly:
USAGE
glab ssh-key delete <key-id> [--flags]
Pass the key ID as an argument, or run the command without arguments
to select a key interactively.The commands and what each actually does with no argument:
| Command | Behavior with no argument |
|---|---|
ssh-key delete |
selects a key interactively |
ssh-key get |
selects a key interactively |
release download |
downloads from the latest release |
release view |
shows the latest release |
repo fork |
forks the current repository |
repo delete |
targets the current repository |
repo archive |
archives the current repository |
This MR moves them to the [<arg>] form the project already uses in
repo clone (clone [<repo> | -g <group>] [<dir>]), milestone get,
todo done and ci config compile.
repo archive needed two further corrections. Its usage advertised a
<command> argument that does not exist: args[0] is a repository and
args[1] is the download directory, which its own examples already show. And
its Long text read "Clone supports these shorthand references", describing a
different command. That string appears nowhere else in the tree, so it was not
shared with repo clone.
repo delete gained one line in its description, since running it with no
argument targets the current repository and nothing in the help said so.
docs/source/ is regenerated with make gen-docs in the same commit, per
AGENTS.md.
Test coverage
internal/commands/ssh-key/ssh-key_test.go asserts on the subcommand Use
strings, so its expectations are updated in the same commit. It fails without
that change, which is what caught the two ssh-key entries.
go test ./internal/commands/ssh-key/... ./internal/commands/release/... ./internal/commands/project/...
passes. release/create fails both with and without this change on Windows,
so it is unrelated.
Note on one choice
repo delete becomes delete [[<NAMESPACE>/]<NAME>]. The nested brackets are
precise, since the namespace is optional within an argument that is itself
optional, but they are not pretty. If you would rather read
delete [<NAMESPACE>/<NAME>], say so and I will change it.
Related issues
Closes #8412 (closed)