godoc-lint checks Go documentation comments for consistency, with a basic set of rules enabled by default. It is aimed especially at reusable Go modules—such as SDKs, API clients, and libraries—whose public documentation appears in IDEs and on pkg.go.dev. You can run it as a standalone command-line tool or use its integration with golangci-lint.
What godoc-lint checks
Go documentation comments are comments placed immediately before top-level package, constant, function, type, and variable declarations, with no blank line between the comment and declaration. The Go Authors’ guide says, “Every exported (capitalized) name should have a doc comment,” and recommends complete sentences that identify the documented symbol. It also describes links such as [io.EOF] and [encoding/json.Decoder]. See the Go Doc Comments guide.
godoc-lint’s default basic rules focus on consistent wording and placement; stricter presence requirements and additional checks are opt-in.
| Rule group | Rules | What it checks |
|---|---|---|
| Basic, enabled by default | pkg-doc, single-pkg-doc, start-with-name, deprecated |
Package-comment wording; duplicate package comments; whether symbol comments begin with the documented name; and deprecation markers. |
| Stricter, opt-in | require-doc, require-pkg-doc |
Whether documentation is present for the relevant declarations and package. |
| Extra, opt-in | max-len, no-unused-link, require-stdlib-doclink |
Comment length, unused link definitions, and links to standard-library documentation. |
The project README notes that test files are skipped by default for several rules and describes options for including them. When using the golangci-lint integration, consider whether test-file exclusions are appropriate for your repository. Rule behavior and configuration details are documented in the godoc-lint README.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
Choose standalone use or golangci-lint
The project README says godoc-lint has been included in golangci-lint since v2.5.0. If your repository already runs golangci-lint, integrating the checks there may fit your existing lint workflow. Standalone use is a direct option when you want godoc-lint’s own command and flags. Configuration formats differ between the standalone tool and golangci-lint, so use the documentation for the mode you choose.
| Consideration | Standalone godoc-lint | golangci-lint integration |
|---|---|---|
| Best fit | You want to run the dedicated godoclint command or use its standalone CLI options. |
Your project already manages linting through golangci-lint. |
| Configuration | Standalone configuration files are .godoc-lint.yaml or .godoclint.yaml; an alternate file can be selected with -config. |
Uses golangci-lint’s configuration; consult its current documentation rather than copying standalone settings. |
| Test files and exclusions | The README describes rule options for including tests and configuration exclusions for paths. | The project recommends considering test-file exclusions; configure them using golangci-lint’s own settings. |
Install and run the standalone command
-
From the Go source root, install the command with
go install github.com/godoc-lint/godoc-lint/cmd/godoclint@latest, following the project’s README. -
Run it across the repository with
godoclint ./.... -
Alternatively, run the tool without first installing its command using
go run github.com/godoc-lint/godoc-lint/cmd/godoclint@latest ./..., as documented by the project.
These are the installation and invocation forms documented in the README; check it for current release and usage details before relying on version-specific behavior. The README also says executable binaries have not been included in releases since v0.11.3, so do not assume a release download provides one.
Start with defaults, then tighten rules deliberately
For a first run, the basic default rules provide checks without requiring you to enforce documentation presence everywhere. Once those checks fit your codebase, consider enabling the stricter requirements or extra checks that match your API and style goals. The README documents rule-set choices of basic, all, or none, as well as options to enable or disable individual rules and include or exclude paths.
The standalone command searches for .godoc-lint.yaml or .godoclint.yaml in the working directory. Configuration may also be placed in subdirectories; while walking from the invocation root, the linter uses the closest applicable configuration file. Use -config to choose another configuration file. Keep this standalone behavior distinct from golangci-lint’s configuration system.
Rank #4
Handle exceptions, tests, and files you should not edit
For a localized exception, the documented inline directive form is //godoclint:disable [[RULE] ...]. There must be no space between // and godoclint:disable. Naming rules disables those rules in the applicable context; omitting rule names disables all rules for the declaration or file context described in the README. Check the project documentation for the scope of a directive before applying it broadly.
For generated or legacy files that should not be edited, use configuration exclusions rather than rewriting their comments solely to satisfy the linter. For test files, decide whether the checks belong in your policy: the README says several rules skip tests by default and provides options to include them. In a golangci-lint workflow, apply exclusions through golangci-lint’s configuration.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsBest Value
When godoc-lint is useful
It is most directly relevant when a Go repository wants consistent documentation across a public API, particularly for reusable modules whose users encounter comments in IDEs or on pkg.go.dev. The basic rules offer a starting point; opt-in rules let maintainers choose whether missing comments, length, links, or test-file coverage should be enforced. For a small project without a need for these consistency checks, adopting a dedicated lint step may add little value.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
