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.

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

x/tools/gopls: Highlight the symbols in comments, and support jump to the definition of symbols #64648

Open
rogeryk opened this issue Dec 11, 2023 · 11 comments
Labels
FeatureRequest gopls Issues related to the Go language server, gopls. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone

Comments

@rogeryk
Copy link

rogeryk commented Dec 11, 2023

gopls version

v14.2

go env

unimportant

What did you do?

unimportant

What did you expect to see?

In Golang, documentation is maintained in code comments. The comment contain a lot of symbols, Highlighting these symbols will make reading clearer. When reading the documentation, you may want to look at the definition of the commit object, so improving the ability to jump would be great.

  • highlight symbols in comments
  • suport go to definition for symbols in comments

These feature are already implemented in Goland.
Goland
image

Vscode
image

What did you see instead?

unimportant

Editor and settings

No response

Logs

No response

@rogeryk rogeryk added gopls Issues related to the Go language server, gopls. Tools This label describes issues relating to any tools in the x/tools repository. labels Dec 11, 2023
@gopherbot gopherbot added this to the Unreleased milestone Dec 11, 2023
@gophun
Copy link

gophun commented Dec 11, 2023

I don't think that GoLand does the right thing either. Only [Context] should be rendered as a link, because the author explicitly marked it as one, cf. pkg.go.dev: https://pkg.go.dev/context#Background

@hyangah
Copy link
Contributor

hyangah commented Dec 11, 2023

I see this feature request is relevant to a couple of different functionalities gopls is offering.

  • textDocument/documentLink. Not sure though if editors themselves color differently the parts associated with links. (vscode doesn't seem to color linkified texts).

  • Semantic tokens - symbols in comments may be annotated with the documentation modifier. For example, "Background" and linkified symbols may be differently rendered.

  • textDocument/hover. Hover UI can use richer presentation (for symbol documentations), but gopls does not seem to handle [] notation yet.

Screenshot 2023-12-11 at 9 00 04 AM

@rogeryk
Copy link
Author

rogeryk commented Dec 11, 2023

@gophun Yes, I know that's the "[Name]" or "[pkg.Name]" are valid doc links (https://tip.golang.org/doc/comment#doclinks), because that's only way to accurately and quickly identify a link for package doucments.

Golang recommand simplie. Most comments do not use "[]" intentionally, but types or functions often appear in comments.
Maybe there will be some mistake, but I don't think it will have a big impact, or we can make it only effective for external functions and types. Believe me, if you are reading a complex package doc, it is very useful to identify the function and jump to it.

@rogeryk
Copy link
Author

rogeryk commented Dec 11, 2023

@hyangah

textDocument/documentLink. Not sure though if editors themselves color differently the parts associated with links. (vscode doesn't seem to color linkified texts).

I hope "textDocument/definition" is also supported, because I hope to use one shortcut key to jump to the corresponding definition In code and comments.

Semantic tokens - symbols in comments may be annotated with the documentation modifier. For example, "Background" and linkified symbols may be differently rendered.

The "doccumentation" modifier is suitable, bu it seems that many themes in vscode do not highlight this.

@gopherbot
Copy link

Change https://go.dev/cl/553836 mentions this issue: gopls/internal/server/semantic: highlight the pkg/type/func name in comments

@gopherbot
Copy link

Change https://go.dev/cl/554915 mentions this issue: gols/internal/lsp/source: support hover and definition request in comments

@mvdan
Copy link
Member

mvdan commented Jan 10, 2024

Just to double check: will this will work with any comment, or just with godoc comments? Even if non-godoc comments don't get rendered as godoc and don't strictly speaking have support for links, I still use this format in them for the sake of consistency and clarity when I refer to a Go identifier, particularly from another package.

@rogeryk
Copy link
Author

rogeryk commented Jan 11, 2024

@mvdan This decision is still open to discussion, although I might personally prefer not to work with any comments.
Think about it from a consistency perspective, It would be better to follow the godoc link rules, but I see many packages that don't go out of their way to follow the godoc link rules.

@rogeryk
Copy link
Author

rogeryk commented Jan 12, 2024

After some discussion, due to consistency and performance considerations, it only takes effect for doc links. More details can be found in CL https://go.dev/cl/553836

@mvdan
Copy link
Member

mvdan commented Jan 20, 2024

After some discussion, due to consistency and performance considerations, it only takes effect for doc links. More details can be found in CL https://go.dev/cl/553836

As long as [Foo] works in any comment, godoc or not, that's what I wanted :) I meant that I use this format in non-godoc comments too, such as those inside function bodies, and I'd like gopls to support them too. pkgsite doesn't have to, since it doesn't render those comments in any way.

@rogeryk
Copy link
Author

rogeryk commented Jan 21, 2024

@mvdan Ok, now it's exactly what you expected.

@findleyr findleyr modified the milestones: gopls/v0.15.0, gopls/v0.16.0 Feb 6, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
FeatureRequest 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
Development

No branches or pull requests

6 participants