godocreflow

Overview ¶

Command godocreflow reflows the text of Go doc-comment blocks -- file-level header comments, package doc comments, and comments immediately preceding an exported declaration -- to semantic line breaks (one sentence per line, plus a break at an internal independent-clause boundary), per the golang-comments skill's "Line-wrap style" section.

It is a pure mechanical transform: only re-breaks existing comment text onto different lines, never adds, drops, or reorders a word. Comment discovery uses go/parser and go/ast (not regex over raw text), so a "//" inside a string literal can never be mistaken for a comment. The sentence/clause-splitting heuristics (abbreviations, backtick/paren-span guards, the Oxford-comma "first eligible comma" rule) are ported from millhouse's plugins/mill/scripts/tools/pydocreflow/pydocreflow.py; see split.go.

A semantic line that still exceeds -max-width after sentence/clause splitting -- and has no further semicolon/conjunction boundary left to break at -- gets one last-resort greedy word-wrap. This is a targeted exception for the rare over-wide outlier (uncomfortable in side-by-side diff view), not a return to general fixed-column wrapping; see wrapLongLine in split.go. -max-width is a flag rather than a compiled-in constant specifically so the column budget can be tuned per run with no rebuild.

Left untouched: single-line comments that already fit on one line, end-of-line inline comments, build/tool directive comments (//go:generate, //go:build, //nolint, struct-tag-adjacent comments a linter parses), any comment block containing indented example code or a Go 1.19 doc-comment heading/list, struct-field and interface-method doc comments, and generated files ("Code generated ... DO NOT EDIT" header).

go run ./tools/godocreflow [-check] [-max-width N] <file_or_dir> ...

-check		print before/after blocks instead of writing files (dry run)
-max-width	last-resort word-wrap column budget, 0 disables it (default 100)

Last run: 2026-08-06, repo-wide sweep (golang-comments-linebreak-sweep task).