docs(cli): say what each command does, not how it works - #62
Merged
Merged
Conversation
The create-if-missing behaviour of -c/--context is already spelled out on the flag itself, so the description repeated it. Drops to the two facts that aren't visible elsewhere: what the command runs, and where the config is read from.
Descriptions were explaining mechanism: which transport the admin subcommands use, that blobs are deduplicated by hash, that ping sends a Limit-1 subscription, the order config files are searched in. None of that helps anyone run the command. Stripped throughout. Four descriptions went away entirely once the mechanism was removed and only a restatement of the headline was left (blossom mirror, blossom report, blossom servers, relay). Headlines lost their internals too -- "daemon", "TUI", "worker status", "without restarting it". What stays is what a caller can't see elsewhere: what the output contains, what the exit code means, and which flags conflict.
A sweep across all 71 commands found the last of the mechanism wording (bunker still said "TUI" twice) and fourteen descriptions that mostly repeated the line above them. Four are gone entirely -- apply, miner, prefs, prefs relays -- and the rest keep only what the headline doesn't already say: that roles can't be deleted, that members add skips the invite flow, which flags conflict.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-on to #61. The descriptions still explained how things work; this makes them say what the command does.
What came out
Mechanism, across the board: the NIP-98 transport the admin subcommands use, "deduplicated by hash", ping's Limit-1 subscription, the config search order, "merged across all targets", "each server downloads it directly; no bytes pass through ncli", "wait for each relay's OK", and the last of the
TUI/daemonjargon.Eight descriptions disappeared entirely once the mechanism was gone and only a restatement of the headline remained:
blossom mirror,blossom report,blossom servers,relay,apply,miner,prefs,prefs relays.ncli relaywith no config — the case that started this — is now:The create-if-missing behaviour that appeared twice now lives only on the
--contextflag.Headlines
Coverage
Checked rather than eyeballed. Walked all 71 user-reachable commands out of the built binary (plus root and the hidden daemon = 73, matching the source count), then:
bunker), now zero;What stays is only what the rest of the help doesn't already show: what the output contains, what the exit code means, and which flags conflict.
Verification
gofmt,go build ./...,go vet ./...,go test -short ./...clean. No test asserts onShort/Longtext.