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

[rogeryk]

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

Vscode

What did you see instead?

unimportant

Editor and settings

No response

Logs

No response

[gophun]

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]

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.

[rogeryk]

@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]

@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]

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

[gopherbot]

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

[mvdan]

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]

@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]

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]

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]

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

[findleyr]

Just used this for the first time, and it's so great!