You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
I need to know if the Go team is interested in having Go Doc checker in x/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 maybe Gopls interested in it.
// Package json implements encoding and decoding of JSON as defined in// https://tools.ietf.org/html/rfc7159. The mapping between JSON and Go values is described// in the documentation for the Marshal and Unmarshal functions.//// For an introduction to this package, see the article// https://golang.org/doc/articles/json_and_go.htmlpackage json
// Package json implements encoding and decoding of JSON as defined in// [RFC 7159]. The mapping between JSON and Go values is described// in the documentation for the Marshal and Unmarshal functions.//// For an introduction to this package, see the article// “[JSON and Go].”//// [RFC 7159]: https://tools.ietf.org/html/rfc7159// [JSON and Go]: https://golang.org/doc/articles/json_and_go.htmlpackage json
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.)
cmd/vet should not be too opinionated about non-"Doc Comments". So I think a lot of these will hinge on having enough context to decide if something is intended to be a "Doc Comment". I don't think there is sufficient context from just this:
// path implements ...
I do think there is sufficient context once this is the comment above a package declaration and the first word matches the package name:
// path implements ...
package path // warning
I also think there is sufficient context to warn on that the word after "Package" does not match the package name:
Plain text that is recognized as a URL is automatically linked in HTML renderings.
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 ?