Documentation
¶
Overview ¶
Package docsdrift holds parsing helpers for the documentation drift tests.
The docs under docs/*.md are hand-written prose and stay that way: nothing here generates markdown. These helpers only extract the *keys* a table documents (tool names, flag names, config keys, …) so a test can compare them against the keys the code actually exposes. Descriptions are never compared — only membership.
Several of the code-side key sets live in unexported identifiers (the CLI flag set is built inline in main(), modelAliases is package private). Rather than exporting them just to be testable, the helpers below read the source with go/ast. That keeps production code untouched and the coupling confined to this package.
Index ¶
- func BacktickToken(cell string) string
- func Diff(want, got map[string]bool) (missing, extra []string)
- func GoFlagNames(path, receiver string) ([]string, error)
- func GoStringMap(path, name string) (map[string]string, error)
- func ReadDoc(root, rel string) (string, error)
- func RepoRoot() (string, error)
- func SetOf(items []string) map[string]bool
- func SplitTableRow(line string) []string
- func TableAfter(content, anchor string) ([][]string, error)
- func TablesInSection(content, heading string) ([][]string, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BacktickToken ¶
BacktickToken returns the text inside the first pair of backticks in cell, or "" when the cell has no code span.
func GoFlagNames ¶
GoFlagNames extracts flag names declared in a Go file through calls like flag.String("p", …), fs.Bool("check", …) or flag.StringVar(&x, "p", …). receiver is the identifier the calls hang off ("flag" for the default flag set, "fs" for a sub-command's FlagSet).
Any call on that receiver whose method is neither a known registrar nor a known non-registrar is an error: an extractor that no longer understands the code must say so rather than report a green test over a partial view of it.
func GoStringMap ¶
GoStringMap extracts a package-level `var name = map[string]string{…}` literal with constant keys and values. An entry that is not a literal-to-literal pair is an error rather than a skip: silently dropping it would hide exactly the entry the docs may be missing.
func RepoRoot ¶
RepoRoot walks up from the working directory until it finds go.mod, so the tests work from any package directory without absolute paths.
func SplitTableRow ¶
SplitTableRow splits a markdown table row into trimmed cells. Pipes escaped as `\|` (used by cells like `/path [list\|add\|rm]`) are part of the cell text, not separators.
func TableAfter ¶
TableAfter returns the data rows of the first markdown table that starts after the line equal to anchor (a heading, or a lead-in line such as "Always registered:"). Header and separator rows are dropped.
func TablesInSection ¶
TablesInSection returns the data rows of every markdown table between the given heading and the next heading of the same or higher level. Used for sections whose keys are spread over several sub-tables (config fields).
Types ¶
This section is empty.
Source Files