x/tools/gopls/doc: provide links to the analyzer source code or more details

[hyangah]

Looking into what infertypeargs analyzer does for
#63821
I visited the gopls documentation (https://github.com/golang/tools/blob/master/gopls/doc/analyzers.md#infertypeargs).
and found a short description about it (admittedly, not much more than what I could guess from the analyzer's name).

I wanted to learn more about how this works, but this analyzer is gopls private package.
The package doc or source code is not easily searchable from pkg.go.dev. Some options I could think of:

1. make the analyzer public and provide detailed documentation as package doc.
2. enhance x/tools/gopls/doc/analyzers.md to add the link to the source location or the internal package doc page in pkg.go.dev

[findleyr]

When you say make the analyzer public, what to you mean exactly? The documentation can be viewed at
https://pkg.go.dev/golang.org/x/tools/gopls/internal/lsp/analysis/infertypeargs
Is the problem that it doesn't appear in pkgsite search results?

For other analysis passes, we've been enforcing (via //go:embed doc.go and analysisutil.MustExtractDoc).

Since we already embed the analyzer doc in x/tools/gopls/doc/analyzers.md, it seems we could just do the following:

1. Move the documentation for infertypeargs to doc.go, and use MustExtractDoc to keep package doc and Analyzer doc in sync.
2. Improve the documentation.

Though I'll note that in this case infertypeargs is a "convenience" analyzer, which is an entire concept that is going away (https://go.dev/issue/61559). Soon it will just be a code action, and we don't have a good way to modularize and document code actions (https://go.dev/issue/54115).

[hyangah]

When you say make the analyzer public, what to you mean exactly? The documentation can be viewed at https://pkg.go.dev/golang.org/x/tools/gopls/internal/lsp/analysis/infertypeargs Is the problem that it doesn't appear in pkgsite search results?

Yes, exactly. I tried to search it with "infertypeargs" in pkgsite and it didn't appear since it's internal. Other forked versions appeared instead.

For other analysis passes, we've been enforcing (via //go:embed doc.go and analysisutil.MustExtractDoc).

Since we already embed the analyzer doc in x/tools/gopls/doc/analyzers.md, it seems we could just do the following:

1. Move the documentation for infertypeargs to doc.go, and use MustExtractDoc to keep package doc and Analyzer doc in sync.
2. Improve the documentation.

Yes, this was the motivation of #61315 originally. :-) I am skeptical about the proposal being accepted. We can move this MustExtractDoc to golang.org/x/tools/internal instead if this is a path forward to document other (non-convenience) analyzers under x/tools/gopls/internal/lsp/analysis.

[gopherbot]

Change https://go.dev/cl/547877 mentions this issue: gopls/internal/analysis: improve analyzer docs