apidocwidth

Overview ¶

Command apidocwidth checks that every line of an API doc comment fits in 76 characters after the "// " prefix.

A type or field doc comment under api/ becomes a CRD description, which is the text an operator reads in `kubectl explain`. kubectl keeps the comment's line breaks and wraps each line again at 76 characters of text, so a longer line leaves its last words on a line of their own. The measurements are in docs/facts/crd-descriptions-in-kubectl-explain.md.

It reads the Go source rather than config/crd/bases. The CRDs also carry the descriptions controller-gen copies from upstream types (metav1.Condition, LabelSelector, Flux's object references, apiVersion and kind), which this repository cannot rewrap: about 150 of their lines are wider than 76. The source holds exactly the descriptions written here, and a finding in it names the file and line to fix rather than a schema path.

Only the doc comments of type declarations and struct fields are measured, because those are the only comments controller-gen turns into descriptions. Marker lines (`+kubebuilder:...`, `+optional`) never reach the CRD, so they are skipped. A rationale block needs no special case: it is separated from the doc comment by a blank line, so Go does not attach it as the doc comment at all.

Usage:

apidocwidth [-width N] [dir ...]

The directories default to api. Exits non-zero and prints file:line for every line that is too wide.