-
Notifications
You must be signed in to change notification settings - Fork 18k
proposal: x/tools/go/analysis: doc comment analyzer #63929
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
Checks that enforce comments to be correct "Doc Comments" seem plausible as a cmd/vet (or gopls) check IMO. If we have a strong reason to suspect that a comment is a doc comment and it is a 'buggy' comment, that will cause an incorrect rendering of the documentation for the package. I think this is on the right side of the vet correctness criteria. (In this case it is the execution of the documentation programs on the package.)
I do think there is sufficient context once this is the comment above a package declaration and the first word matches the package name:
I also think there is sufficient context to warn on that the word after "Package" does not match the package name:
From https://go.dev/doc/comment#links :
IIUC this correctly the links given are are style issues not correctness. That is not to say they are not valuable checks. Just not a fit for vet (IMO).
I am not really sure what other typos you have in mind. Regardless, it will need to be typos according to some dictionary (system dictionary, then personal dictionaries, etc.) I am not really sure this a good match for cmd/vet, which tends towards zero config. This may be okay for gopls. @findleyr ? |
Exactly! And this is true for links and other HTML.
E.g. the common error – do not change documentation after function name changing // WasClosed reports whether the connection was closed.
func (c *conn) Closed() bool Of course there is some analysis of
I'm not sure that |
This proposal overlaps with #57963, which is specifically about broken doc links. |
godoc
analyzer
I think we can just fold this into #57963 . |
Hello!
I need to know if the Go team is interested in having
Go Doc
checker inx/tools
or if we implement it in a third party module.Go Doc
comments is common place for issues (especially after recent HTML support) and I thought maybeGopls
interested in it.Example of checks:
https://go.dev/doc/comment#packages
Before:
// path implements utility routines for manipulating slash-separated paths.
After:
// Package path implements utility routines for manipulating slash-separated paths.
Or typo:
https://go.dev/doc/comment#links
Before:
After:
(+ check URL formatting)
And so on and so forth.
Related:
P.S. Based on golangci/golangci-lint#4147
(cc) @500poundbear
The text was updated successfully, but these errors were encountered: