docs: name the 20 options the README never listed - #13
Merged
Merged
Conversation
Checked every option in the command registry against the README rather than reading the tables - which is how these stayed invisible: a table looks complete when you read it, and only a comparison shows what is missing from it. Some of them decide what a command returns. suggest-connections --min-shared (default 3) is the filter that determines whether a pair counts at all; without it documented there is no way to tell why a result is empty. Boolean options are listed in the form a caller types (--no-create, --multi-block, --no-preserve), not the default-on form nobody passes. --no-preserve is notably not the --no-preserve-formatting its positive form suggests. CONTRIBUTING said cli.py was "~4000 lines". It was 4771 when that was written and is over five thousand now. Replaced with a statement that cannot drift.
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
1 participant
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.
Closing documentation gaps found by a systematic check rather than by reading.
What was wrong
The CLI accepts 20 options the README never named. Not obscure ones either:
find-knowledge-gaps --min-refssuggest-connections --min-shared,--min-confidence,--max-suggestions,--focusanalyze-journal-patterns --timeframe,--mood,--topicsadd-journal-block --date,--upsert-heading,--no-preserveadd-journal-content --date,add-journal-entry --date,--multi-blockadd-note-content --no-create,--propertyget-page --no-backlinks,--headingget-block --no-childreninsert-block --after,--beforesmart-query --include-querySome of these decide what a command returns.
suggest-connections --min-shared(default 3) sets how many topics two pages must share before the pair is
considered at all — a reader who cannot see it has no way to tell why a result
came back empty.
How they stayed invisible
The README's command tables look complete when you read them. The gap only
shows when every option in the command registry is compared against the file,
which is what was done here. It predates this release:
--min-refswas alreadyundocumented in 0.9.0.
Two decisions worth naming
Boolean options are listed in the form a caller types —
--no-create,--multi-block,--no-preserve— not the default-on positive form nobodypasses. This caught one trap: the negative of
--preserve-formattingis--no-preserve, not the--no-preserve-formattingits positive form suggests.Defaults were read from the code, not recalled. Each documented default
(
--min-refs2,--min-shared3,--min-confidence0.3,--timeframe"last 30 days") was verified against the parameter definition.
Also here
CONTRIBUTING.mdclaimedcli.pywas "~4000 lines". It was 4771 when thatsentence was written, 4952 at 0.11.0 and is 5190 now — the number was never
right and drifted further with each release. Replaced with a statement that
names the consequence instead of a count. A figure maintained by hand is the
same defect this project documents elsewhere.
Verified
forms; the check that found the gap reports zero.