godoc "comment formatting is not canonical" error

TL;DR: Run gofmt -w on the file. Since Go 1.19, gofmt normalizes doc comments (list indentation, code block indentation, link formatting), and linters flag comments that are not in that canonical form. One gofmt pass rewrites them; then re-run the linter.

comment formatting is not canonical

1. List the affected files:

   gofmt -l .

Expected: the file with the bad comment is listed.

1. Preview what gofmt will change in the comments:

   gofmt -d path/to/file.go

Expected: a diff showing only comment reformatting (indentation, list markers).

1. Apply it:

   gofmt -w path/to/file.go

1. Verify:

   gofmt -l .

Expected: empty output, meaning every file is now canonical.

1. Re-run the linter that reported the finding. Expected: the canonical-formatting findings are gone.

Use this when

• A linter reports "comment formatting is not canonical"
• gofmt -l lists files you thought were formatted
• Doc comment lists or code examples render oddly on pkg.go.dev

Not for this skill when

• The complaint is about comment content (missing docs, bad grammar) - gofmt only fixes formatting
• The file has a syntax error gofmt cannot parse - fix the syntax error first
• You are on Go older than 1.19 - doc comment reformatting did not exist yet

Variant phrasings

• "gofmt comment formatting is not canonical"
• "go vet doc comment formatting"
• "golangci-lint gofmt canonical comment"

Why it happens

Go 1.19 taught gofmt to reformat doc comments into a canonical shape: indented code blocks, consistent list markers, and standard link syntax. Comments written before that, or by editors that do not run gofmt, keep the old shape and get flagged.

Edge cases

• gofmt only reformats; it never changes the words, so content lints need separate fixes.
• Run gofmt on the whole repo in CI so one canonical pass prevents repeat findings.
• Doc links use the bracket-text plus link-definition style; gofmt normalizes the definitions to the bottom of the comment.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_bwMPeLglBbs9wM1oScMkTg