Documentation
¶
Overview ¶
Command doccheck enforces bide's documentation policy over every module in the repository: every exported type, func, method, package-level const and var has a doc comment that starts with its name, and every package has a package comment ("Package name ..." outside package main). Exported identifiers in package main, test files and generated files are not checked. It also checks the release notes in docs/releases: each becomes a GitHub Release body, so every link and image there must be absolute (see CheckReleaseNotes).
It also checks that every relative link in README.md, examples/README.md and docs/ resolves, to a file and to a heading when it has a #fragment (see CheckLinks).
Findings listed in the allowlist (.doccheck-allow by default) are tolerated. The list may only shrink: an entry whose identifier is now documented, or no longer exists, fails the check until the entry is deleted. New code never gets an entry; document it instead.
Usage, from the repository root:
go run ./internal/tools/doccheck [-root dir] [-allow file] [-links]
With -links only the links in the documentation are checked, which is what CI runs on a pull request that changes nothing but documentation.
The exit status is 0 when clean, 1 on findings or stale entries, and 2 when the check could not run.
Source Files