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: autogenerate documentation for supported configurations #33544

Closed
stamblerre opened this issue Aug 8, 2019 · 12 comments
Closed

x/tools/gopls: autogenerate documentation for supported configurations #33544

stamblerre opened this issue Aug 8, 2019 · 12 comments
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge gopls Issues related to the Go language server, gopls. help wanted NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone
gopls/v0.5.2

Comments

@stamblerre
Copy link
Contributor

stamblerre commented Aug 8, 2019 •
edited
Loading

gopls has a number of configurations, some of which are meant for users to set manually. The rest are used primarily to "hide" experimental features and are only meant for use by gopls developers and testers.

We should formalize the set of gopls configurations that we want to make public for users, and we should consolidate these configurations with the settings of gopls's clients, such as VSCode-Go, vim-go, govim, etc.

Current settings include:

"gopls": {
    // user-facing
    "env": {}, // the environment to use when loading packages
    "buildFlags": [], // the build flags to use when loading packages
    "usePlaceholders": true, // if the user wants placeholders when they complete an item
    "hoverKind": "FullDocumentation", // the amount of documentation to show on hover, one of NoDocumentation, Synopsis, SingleLine, FullDocumentation
    
    // experimental configurations
    "wantCompletionDocumentation": true, // if the user wants to see documentation in completion items
    "wantSuggestedFixes": true, // offer fixes to apply along with diagnostics
    "experimentalDisabledAnalyses": [], // list of analyses to disable in diagnostics
    "useDeepCompletions": true, // show completions for symbols in imported packages
}

We should add the settings used by clients to this issue to get a better understanding of how we can provide a more unified experience.

We should autogenerate this documentation from the comments in the internal/lsp/source/options.go.
@stamblerre stamblerre added NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. gopls Issues related to the Go language server, gopls. labels Aug 8, 2019
@gopherbot gopherbot added this to the Unreleased milestone Aug 8, 2019
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Aug 8, 2019
This was referenced Aug 8, 2019
Closed
Closed
@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Sep 12, 2019
@ermik
Copy link

ermik commented Oct 4, 2019 •
edited
Loading

Just checking if any of these can help with choosing the inferred package root as that would be a workaround for a subset of #32394 where project directory is a step above package root folder (one that has go.mod in it).

gopls seems to ignore:

"go.toolsEnvVars": {
    "GOMOD": "${workspaceFolder}/src/go.mod"
},

as well as the same variable setting but passed via env configuration.

@stamblerre
Copy link
Contributor Author

@ermik: That is something that will have to be implemented through VS Code Go, so I would recommend filing that issue in that repository.

@stamblerre stamblerre changed the title x/tools/gopls: document supported configurations x/tools/gopls: autogenerate documentation for supported configurations Dec 4, 2019
@stamblerre stamblerre modified the milestones: Unreleased, gopls unplanned Dec 4, 2019
@stamblerre stamblerre modified the milestones: gopls unplanned, gopls/v1.0.0 Jan 29, 2020
@stamblerre stamblerre modified the milestones: gopls/v1.0.0, gopls/v0.6.0 Mar 12, 2020
@stamblerre stamblerre modified the milestones: gopls/v0.6.0, gopls/v0.7.0 Apr 2, 2020
@stamblerre stamblerre modified the milestones: gopls/v0.7.0, gopls/v0.5.0 Jun 26, 2020
@stamblerre stamblerre modified the milestones: gopls/v0.5.0, gopls/v1.0.0 Jul 22, 2020
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/252322 mentions this issue: gopls/doc: generate settings docs

@heschi heschi self-assigned this Sep 2, 2020
@stamblerre
Copy link
Contributor Author

We should also auto-generate documentation for the commands and code lenses available in gopls.
This command documentation could also be used to generate package.json contents for commands, making it possible to easily expose commands from gopls in VS Code without a code lens.

@heschi
Copy link
Contributor

heschi commented Sep 9, 2020

I guess this is not actually fixed given the above.

@heschi heschi reopened this Sep 9, 2020
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/256358 mentions this issue: gopls/doc: improve enum value documentation

gopherbot pushed a commit to golang/tools that referenced this issue Sep 22, 2020
@heschi
gopls/doc: improve enum value documentation
82fe25c 
Add a new field to the options JSON, EnumValues. Use it to automatically
generate the documentation for enums. Fix the displayed type to be
"enum" rather than the full-qualified Go type name.

To make this easy, I changed the various enum constants to be strings,
with values matching their configuration values. It may be possible to
automatically parse them in the future, but we can get to that later.

The documentation for hoverKind's private values is a little janky. I
didn't want to build a way to hide them. We can hardcode it if we really
care.

Updates golang/go#33544.

Change-Id: Ia5cc958e347d5ff041068c57726d530809bb0f70
Reviewed-on: https://go-review.googlesource.com/c/tools/+/256358
Trust: Heschi Kreinick <heschi@google.com>
Run-TryBot: Heschi Kreinick <heschi@google.com>
gopls-CI: kokoro <noreply+kokoro@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Rebecca Stambler <rstambler@golang.org>
@heschi
Copy link
Contributor

heschi commented Sep 23, 2020

I'm still unclear on what extra documentation we want. I believe the result of discussion was that we don't want to automatically connect commands to the extension. @stamblerre, you said that we should document code lenses, but I don't understand where or why. Just so that users can disable them in the codelens setting?

@heschi
Copy link
Contributor

heschi commented Sep 23, 2020

Also, should we enable documentation of the debugging options?

@stamblerre
Copy link
Contributor Author

I'm still unclear on what extra documentation we want. I believe the result of discussion was that we don't want to automatically connect commands to the extension. @stamblerre, you said that we should document code lenses, but I don't understand where or why. Just so that users can disable them in the codelens setting?

I had thought that https://github.com/golang/tools/blob/master/internal/lsp/source/command.go was structured in such a way that we could easily generate documentation from it. I think it would be nice to have a page describing our code lenses to make them more discoverable and so that users can understand how to enable/disable them.

Since we've agreed not to expose commands through the VS Code Go command palette, I think this issue is resolved in that there are no more blockers for VS Code Go. I will mention the above in a general issue about documentation.

Also, should we enable documentation of the debugging options?

Yeah, that sounds good.

@stamblerre stamblerre mentioned this issue Sep 23, 2020
Closed
@heschi
Copy link
Contributor

heschi commented Sep 23, 2020

command.go would indeed be easy to generate documentation from. I think you're saying you want it? So I'll add them to the json and write a documentation page, separate from the settings page since there are no settings that refer to commands.

@stamblerre
Copy link
Contributor Author

That would be awesome--thanks! I mentioned it on #41591 in case you wanted to close this issue.

@stamblerre stamblerre added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Sep 25, 2020
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/257737 mentions this issue: internal/lsp/source: add additional generated docs

@stamblerre stamblerre modified the milestones: gopls/v1.0.0, gopls/v0.5.2 Oct 5, 2020
@golang golang locked and limited conversation to collaborators Oct 5, 2021
@rsc rsc unassigned heschi Jun 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. FrozenDueToAge gopls Issues related to the Go language server, gopls. help wanted NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Milestone
gopls/v0.5.2
Development

No branches or pull requests
4 participants
@ermik @stamblerre @gopherbot @heschi