doccheck

Overview ¶

Command doccheck type-checks the Go code blocks in the repository's Markdown against the current module, so a doc example cannot drift from the API it shows.

Every ```go block must be preceded by a marker comment that says how it is checked:

<!-- doccheck: decls -->            top-level declarations; common imports are supplied
<!-- doccheck: file -->             a whole file with its own imports (package clause optional)
<!-- doccheck: body(PARAMS) -->     statements; checked as func _(PARAMS) error { ... }
<!-- doccheck: skip REASON -->      not checked, for the reason given (an excerpt, say)

decls and body accept a trailing "with DECLS", Go declarations the block assumes exist, for example "with type myHarness = echoagent.Harness". Unused variables, imports and labels are not errors, since a block is a fragment of a program; every other type error is.

Usage: go run ./hack/doccheck [file.md ...] (default: every tracked *.md file)