docsym

Overview ¶

docsym reports the Go identifiers a module's README names that its code does not have.

docsym DIR...                      # each DIR a module checkout
docsym --goos linux,darwin DIR...  # the platforms to type-check under
docsym --fail DIR...               # exit 1 when anything is missing

A README rots in a few ways, and this catches the commonest one a program can: a NAME that was renamed or removed. It reads inline code spans (`toolkit.NewButton`, `LoadGTKTheme(css)`, `Entry.Text`) and ```go fences, and type-checks the module -- and the packages it requires from its own organisation -- under each platform asked for, so a name that exists only in window's linux build is found.

What it does NOT catch, and was found by reading on 2026-10-10 in go-widgets: a wrong count ("a 5-primitive interface" over seven methods), a wrong signature (`wg.Draw(surface, width, theme)` after the toolkit moved to a Painter), a claim about the import graph ("toolkit never imports mvvm"). Those need a person. This is the part that does not.

Each reference ends as found, MISSING (no build of the package has it), not ours (the qualifier is a variable or another organisation's package -- skipped, and counted), or unreadable (the package failed to type-check somewhere, so a miss there would be a guess -- counted, never reported as missing). A module that cannot be loaded at all fails the run: a scan that read nothing must not look like a clean one.