go-source-documentation

Start each doc comment with the symbol name, place it immediately before the declaration with no blank line, and use // line comments rather than block comments. Every package needs exactly one Package comment, typically in doc.go.

Document each test with four elements: what behavior is tested, how the test is set up such as mock configuration, the expected assertions, and why the test protects a business rule or edge case. Table-driven tests should also list every covered scenario.

No. Documentation work must never modify function bodies, signatures, or variable names. After adding comments, verify with go build, go test, and golangci-lint that only comments changed and everything still compiles and passes.

A blank line between the comment and the declaration breaks the association, rendering it a regular comment. Also ensure the comment starts with the symbol name and that doc links only reference exported symbols, since unexported links do not resolve.

Use the standard // Deprecated: directive on its own paragraph for any symbol being phased out, and always name the replacement. This convention is recognized by Go 1.19+ tooling and surfaces the notice in godoc and IDEs.