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.

Closes #8412 (closed)

Merge request reports

Loading
Loading