{"id":36445682,"url":"https://github.com/godoc-lint/godoc-lint","last_synced_at":"2026-01-11T22:42:54.433Z","repository":{"id":281148468,"uuid":"932761312","full_name":"godoc-lint/godoc-lint","owner":"godoc-lint","description":"A linter for Go documentation practice (godoc)","archived":false,"fork":false,"pushed_at":"2025-12-30T00:36:28.000Z","size":378,"stargazers_count":9,"open_issues_count":7,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-02T07:51:31.413Z","etag":null,"topics":["documentation","godoc","golang","golangci-lint","linter","static-analysis"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/godoc-lint.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-14T13:25:41.000Z","updated_at":"2025-12-30T00:36:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"b0818f78-792b-457f-8ac1-985f10b7bac9","html_url":"https://github.com/godoc-lint/godoc-lint","commit_stats":null,"previous_names":["godoc-lint/godoc-lint"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/godoc-lint/godoc-lint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godoc-lint%2Fgodoc-lint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godoc-lint%2Fgodoc-lint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godoc-lint%2Fgodoc-lint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godoc-lint%2Fgodoc-lint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/godoc-lint","download_url":"https://codeload.github.com/godoc-lint/godoc-lint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/godoc-lint%2Fgodoc-lint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28326144,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T22:11:01.104Z","status":"ssl_error","status_checked_at":"2026-01-11T22:10:58.990Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","godoc","golang","golangci-lint","linter","static-analysis"],"created_at":"2026-01-11T22:42:53.839Z","updated_at":"2026-01-11T22:42:54.419Z","avatar_url":"https://github.com/godoc-lint.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# What's Godoc-Lint?\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/godoc-lint/godoc-lint.svg)](https://pkg.go.dev/github.com/godoc-lint/godoc-lint)\n[![Release](https://img.shields.io/github/v/release/godoc-lint/godoc-lint)](https://github.com/godoc-lint/godoc-lint/releases)\n[![License](https://img.shields.io/github/license/godoc-lint/godoc-lint)](/LICENSE)\n[![CI](https://github.com/godoc-lint/godoc-lint/actions/workflows/ci.yaml/badge.svg)](https://github.com/godoc-lint/godoc-lint/actions/workflows/ci.yaml)\n\n*Godoc-Lint* is a fast, *little* opinionated linter for Go documentation practice, also known as *Go Doc* or *godoc* (See [*Go Doc Comments*][godoc-ref]), ready to be used **out of the box** without further configuration. It is highly recommended to be used when developing **reusable Go modules, like SDKs, API clients, or special-purpose libraries,** which need consistent/standard developer experience in IDEs, as well as on [pkg.go.dev](https://pkg.go.dev) docs.\n\n[godoc-ref]: https://go.dev/doc/comment\n\n## Using via Golangci-lint\n\nGodoc-Lint is now available as part of [Golangci-lint][golangci-lint] suite of linters (since `v2.5.0`). To enable the linter, it should be added to the `.golangci.yml` file:\n\n```yaml\nversion: \"2\"\nlinters:\n  enable:\n    - godoclint\n```\n\nWhen used via Golangci-lint, the linter's configuration will be different from what is covered in this document. Users should consult Golangci-lint [docs][golangci-lint-config] for more details.\n\n\u003e [!TIP]\n\u003e In most cases, it is best to exclude Go test files (i.e., `*_test.go`) from the analysis. This can be done by adding the following lines to `.golangci.yml`:\n\u003e\n\u003e ```yaml\n\u003e linters:\n\u003e   exclusions:\n\u003e     rules:\n\u003e       - path: _test\\.go$\n\u003e         linters:\n\u003e           - godoclint\n\u003e ```\n\u003e\n\u003e More about exclusion methods is available [here][golangci-lint-fp].\n\n\n[golangci-lint]: https://golangci-lint.run\n[golangci-lint-config]: https://golangci-lint.run/docs/linters/configuration/#godoclint\n[golangci-lint-fp]: https://golangci-lint.run/docs/linters/false-positives/\n\n## Installation\n\nGodoc-Lint binaries are available in the repository's [Releases][releases] page.\n\nUsers can also install Godoc-Lint binary from source code by using any of these commands:\n\n```sh\n# Latest version\ngo install github.com/godoc-lint/godoc-lint/cmd/godoclint@latest\n\n# Specific version\ngo install github.com/godoc-lint/godoc-lint/cmd/godoclint@v0.10.0\n```\n\nAdditionally, the linter can be run from source code via the following command:\n\n```sh\n# Latest version\ngo run github.com/godoc-lint/godoc-lint/cmd/godoclint@latest ./...\n\n# Specific version\ngo run github.com/godoc-lint/godoc-lint/cmd/godoclint@v0.10.0 ./...\n```\n\n[releases]: https://github.com/godoc-lint/godoc-lint/releases\n\n## Usage\n\nUsers can simply run the `godoclint` CLI at the root directory of their Go source code:\n\n```sh\ngodoclint ./...\n```\n\nThis will run the linter with its default configuration on all Go packages. It is also possible to narrow the search path:\n\n```sh\ngodoclint ./internal/foo/bar # Exact package, no sub-packages\ngodoclint ./internal/...     # All sub-packages\n```\n\nGodoc-Lint looks for `.godoc-lint.yaml` file in the working directory for configuration (Check the [Configuration](#Configuration) section for more details). If not found, the linter will use sensible defaults.\n\nAlthough it is best to set the configuration parameters in a file, there are a number of CLI options to modify linter parameters:\n\n| Option       | Description                                                               |\n| ------------ | ------------------------------------------------------------------------- |\n| `-default`   | Default set of rules to enable, one of `basic` (default), `all` or `none` |\n| `-enable`    | Comma-separated list of rules to *also* enable (multiple usage allowed)   |\n| `-disable`   | Comma-separated list of rules to disable (multiple usage allowed)         |\n| `-include`\\* | Regexp pattern of relative paths to include (multiple usage allowed)      |\n| `-exclude`\\* | Regexp pattern of relative paths to exclude (multiple usage allowed)      |\n\n\u003e [!WARNING]\n\u003e **(\\*)** The path patterns supplied via `-include` or `-exclude` options should assume Unix-like paths (i.e., separated by forward slashes, `/`). This is to ensure a consistent behavior across different platforms.\n\n## Rules\n\nThe linter provides a number of rules that can be categorized as in this table:\n\n| Category          | Rules                                                                                  | Notes                                                              |\n| ----------------- |----------------------------------------------------------------------------------------| ------------------------------------------------------------------ |\n| Basic *(default)* | `pkg-doc` \u003c/br\u003e `single-pkg-doc` \u003c/br\u003e `start-with-name` \u003c/br\u003e `deprecated`            | Recommended by [*Go Doc Comments*][godoc-ref], and **low-effort**  |\n| Strict            | `require-doc` \u003c/br\u003e `require-pkg-doc`                                                  | Recommended by [*Go Doc Comments*][godoc-ref], and **high-effort** |\n| Extra             | `max-len` \u003c/br\u003e `no-unused-link` \u003c/br\u003e `require-stdlib-doclink`                        | Extra but compatible with [*Go Doc Comments*][godoc-ref]           |\n\n**Rules under the *Basic* category are enabled by default** and do not need further configuration, unless, of course, one wants to tune their parameters. The rest has to be explicitly enabled via configuration.\n\nBelow is a brief description of the linter's rules. Some rules are configurable via the `options` key in the configuration file (See [Configuration](#Configuration) for more details).\n\n### `pkg-doc`\n\n\u003e Since `v0.1.0`, Golangci-lint `v2.5.0`.\n\nEnsures all package godocs start with \"Package \\\u003cNAME\\\u003e\":\n\n```go\n// This is an example package.  // (Bad)\npackage foo\n\n// Package foo is an example.   // (Good)\npackage foo\n```\n\nTest files are skipped by default. To enable the rule for them, the `pkg-doc/include-tests` option should be set to `true`.\n\n\u003e [!NOTE]\n\u003e As of [*Go Doc Comments*][godoc-cmd-ref], command packages (i.e., packages named `main`) are exceptions to this rule. So, Godoc-Lint ignores them and their test packages (i.e., `main_test`) by default.\n\n[godoc-cmd-ref]: https://go.dev/doc/comment#cmd\n\n### `single-pkg-doc`\n\n\u003e Since `v0.1.0`, Golangci-lint `v2.5.0`.\n\nTechnically, every Go file in a package can have a godoc above the `package` statement. This rule enforces only one godoc, if any, for any package. Test files are skipped by default. To enable the rule for them, the `single-pkg-doc/include-tests` option should be set to `true`.\n\n### `require-pkg-doc`\n\n\u003e Since `v0.1.0`, Golangci-lint `v2.5.0`.\n\nEnsures that every Go package has godoc(s). By default, test files (i.e., `*_test.go`) and therefore test packages (i.e., `*_test`) are ignored. To include them in the check, the `require-pkg-doc/include-tests` should be set to `true`.\n\n### `start-with-name`\n\n\u003e Since `v0.1.0`, Golangci-lint `v2.5.0`.\n\nChecks godocs start with the corresponding symbol name:\n\n```go\n// This is a constant.  // (Bad)\nconst Foo = 0\n\n// Foo is a constant.   // (Good)\nconst Foo = 0\n```\n\nIt allows English articles (i.e., *a*, *an*, and *the*) at the beginning of godocs.\n\nBy default, unexported symbols are skipped. To include them the `start-with-name/include-unexported` option should be set to `true`. Test files are also skipped. To enable the rule for test files, the `start-with-name/include-tests` option should be set to `true`.\n\n### `require-doc`\n\n\u003e Since `v0.1.0`, Golangci-lint `v2.5.0`.\n\nEnsures all exported and/or (optionally) unexported symbols have godocs. By default, symbols declared in test files, together with any unexported symbols are ignored. To include test files, the `require-doc/include-tests` option should be set to `true`. Unexported symbols can be included in the check if the `require-doc/ignore-unexported` options is set to `false`. Although it is a rare scenario but one may want to ignore exported symbols, for which the `require-doc/ignore-exported` should be set to `true`.\n\n### `deprecated`\n\n\u003e Since `v0.9.0`, Golangci-lint `v2.5.0`.\n\nChecks if deprecation notes are formatted correctly. This rule only applies to exported symbols.\n\n```go\n// Foo is a symbol.\n//\n// DEPRECATED: do not use  // (Bad)\nconst Foo = 0\n\n// Foo is a symbol.\n//\n// Deprecated: do not use  // (Good)\nconst Foo = 0\n```\n\n### `max-len`\n\n\u003e Since `v0.1.0`, Golangci-lint `v2.5.0`.\n\nLimits maximum line length for godocs. The default length is 77 characters (not including the `// `, `/*`, or `*/` tokens):\n\n```go\n// Foo has a super loooooooooooooooooooooooooooooooooooooooooooooooooooong godoc.  // (Bad)\nconst Foo = 0\n\n// Foo has a reasonably long godoc.  // (Good)\nconst Foo = 0\n```\n\nThe pre-formatted sections (e.g., codes), or link definitions are ignored.\n\nThe maximum line length can be configured via the `max-len/length` option. The rule skips test files by default. To enable it the `max-len/include-tests` option should be set to `true`.\n\nSpecific long lines (for example, ones matching known patterns) can be excluded from this rule by listing regexp patterns under the `max-len/ignore-patterns` option; any rendered godoc line matching at least one of these patterns is not checked for length. Note that, when using Golangci-lint, pattern-based exclusions are available via [`source` text matching](https://golangci-lint.run/docs/linters/false-positives/#exclude-issue-by-text).\n\n\u003e [!TIP]\n\u003e A long hyperlink in the godoc text can break this rule. In such cases, it is best to define the link at the end of the godoc and use the reference in the text:\n\u003e\n\u003e ```go\n\u003e // Foo is a const. Check this [link].\n\u003e //\n\u003e // [link]: https://foo.com/super/loooooooooooooooooooooooooooooooooooooooong/link\n\u003e const Foo = 0\n\u003e ```\n\n### `no-unused-link`\n\n\u003e Since `v0.2.0`, Golangci-lint `v2.5.0`.\n\nChecks for unused links in the godoc text:\n\n```go\n// Foo godoc has an unused link.     // (Bad)\n//\n// [link]: https://foo.com/docs\nconst Foo = 0\n\n// Foo godoc uses a defined [link].  // (Good)\n//\n// [link]: https://foo.com/docs\nconst Foo = 0\n```\n\nThe rule skips test files by default. To include them, the `no-unused-link/include-tests` option should be set to `true`.\n\n### `require-stdlib-doclink`\n\n\u003e Since `v0.11.0`, Golangci-lint `v2.8.0`.\n\nSuggests turning plain-text mentions of standard-library identifiers into [*doc links*](https://go.dev/doc/comment#doclinks), when possible. For example, the text `encoding/json.Encoder` in a godoc can be turned into a doc link like `[encoding/json.Encoder]` so that it links to the corresponding stdlib symbol on [`pkg.go.dev`](https://pkg.go.dev/encoding/json#Encoder). To avoid false positives, the linter only detects potential doc links of longer forms like `pkg.name` or `pkg.recv.name`.\n\n```go\n// Println is the same as fmt.Println.    // (Bad)\nfunc Println(a ...any) (n int, err error) {}\n\n// Println is the same as [fmt.Println].  // (Good)\nfunc Println(a ...any) (n int, err error) {}\n```\n\nThe rule skips test files by default. To include them, the `require-stdlib-doclink/include-tests` option should be set to `true`.\n\n## Disabling rules\n\n\u003e [!TIP]\n\u003e Users who run the linter via Golangci-lint can also use the `//nolint:godoclint` directive to disable the linter. The `//nolint` directive usage is explained in the Golangci-lint's official [docs][golangci-nolint].\n\n[golangci-nolint]: https://golangci-lint.run/docs/linters/false-positives/#nolint-directive\n\nGodoc-Lint supports inline directives to temporarily skip enforcing given set of rules. The directive must be formatted as:\n\n```go\n//godoclint:disable [[RULE] ...]\n```\n\n\u003e [!NOTE]\n\u003e There must be no whitespace between `//` and `godoclint:disable`.\n\nFor example, this will temporarily disable the `start-with-name` rule for the `Foo` symbol's godoc:\n\n```go\n// This is a constant.\n//\n//godoclint:disable start-with-name\nconst Foo = 0\n```\n\nAny number of rules can be listed, separated with whitespaces. If no rule is provided, all rules will be disabled. For example, this will disable `start-with-name` and `max-len` rules for the `Foo` symbol's godoc:\n\n```go\n// This is a function.\n//\n//godoclint:disable start-with-name max-len\nfunc Foo() {}\n```\n\nIt is also possible to use multiple `//godoclint:disable` directives:\n\n```go\n// This is a function.\n//\n//godoclint:disable start-with-name\n//godoclint:disable max-len\nfunc Foo() {}\n```\n\nThere are cases where one would want to disable all linter rules for a specific declaration. This can be done by just omitting the rule names in the directive:\n\n```go\n// This is a function.\n//\n//godoclint:disable\nfunc Foo() {}\n```\n\nRules can be disabled for an entire file. To do this, the `//godoclint:disable` comment should be added at any position at the top level, in a *non-godoc* comment group. For instance, this will disable all rules for the entire file:\n\n```go\npackage foo\n\n//godoclint:disable\n```\n\nSometimes, it is not possible/preferred to add the inline `//godoclint:disable` directives to a file (e.g., an auto-generated file, or a legacy file that should not be altered). In such cases, the configuration file is the right place to instruct the linter. All one needs to do is to add the files under the `exclude` key. More about this in the [Configuration](#Configuration) file section.\n\n## Configuration\n\nTo have a customized experience, users can define their configuration in a file named `.godoc-lint.yaml` (or `.godoclint.yaml`). The linter looks for this file in the working directory where it is invoked. However, users can specify a different file name via the `-config` option:\n\n```sh\ngodoclint -config the-config-file.yaml ./...\n```\n\nGodoc-Lint comes with a sensible default configuration that will be used when there is no configuration file. Check out [`.godoc-lint.default.yaml`](./.godoc-lint.default.yaml) for more details.\n\n### Overriding configuration\n\n\u003e [!WARNING]\n\u003e When used via Golangci-lint, the linter's configuration will be different from what is covered here. Users should consult Golangci-lint [docs][golangci-lint-config] for more details.\n\nIn addition to the root directory, Godoc-Lint allows configuration files in sub-directories. When a package is being processed, the configuration file in the package's directory, if any, will be used by the linter. If there is no such file, the linter looks for it in the directory's parents, up until the root where the linter was invoked.\n\nFor example, in the file tree below package `foo` gets processed with the configuration expressed in `foo/.godoc-lint.yaml`.\n\n```text\n├─ foo\n│  ├─ .godoc-lint.yaml\n|  ├─ foo.go\n├─ .godoc-lint.yaml\n├─ main.go\n```\n\n## Contributing\n\nGodoc-Lint loves to see developers contributing to it. So, please feel free to submit a [new issue](https://github.com/godoc-lint/godoc-lint/issues/new) for bug report, feature request, or any kind of discussion.\n\n## Links\n\n- [Go Doc Comments](https://go.dev/doc/comment)\n- [Golangci-lint configuration](https://golangci-lint.run/docs/linters/configuration/#godoclint)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodoc-lint%2Fgodoc-lint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgodoc-lint%2Fgodoc-lint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgodoc-lint%2Fgodoc-lint/lists"}