Skip to content
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.

Sign up for GitHub

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

Jump to bottom

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

Closed
hyangah opened this issue Oct 30, 2023 · 3 comments
Closed

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

hyangah opened this issue Oct 30, 2023 · 3 comments
Assignees
@adonovan
Labels
gopls Issues related to the Go language server, gopls. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone
gopls/v0.15.0

Comments

@hyangah
Copy link
Contributor

hyangah commented Oct 30, 2023

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
@gopherbot gopherbot added Tools This label describes issues relating to any tools in the x/tools repository. gopls Issues related to the Go language server, gopls. labels Oct 30, 2023
@gopherbot gopherbot added this to the Unreleased milestone Oct 30, 2023
@findleyr
Copy link
Contributor

findleyr commented Nov 2, 2023

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
Copy link
Contributor Author

hyangah commented Nov 3, 2023

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.

@findleyr findleyr modified the milestones: Unreleased, gopls/v0.15.0 Nov 7, 2023
@gopherbot
Copy link

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

@adonovan adonovan self-assigned this Dec 7, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@adonovan adonovan

Labels
gopls Issues related to the Go language server, gopls. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Milestone
gopls/v0.15.0
Development

No branches or pull requests
4 participants
@hyangah @adonovan @gopherbot @findleyr