x/tools/gopls: render doc links properly in hover #58352
Comments
gopherbot
added
Tools
suzmue
added
the
NeedsInvestigation
|
CC @pjweinb Thank you for the report. I agree we should fix those links. |
|
There are several different things going on in the example, some of which we can fix.
I don't think it matters, but vscode does not implement the same version of markdown as GitHub. |
|
Change https://go.dev/cl/469715 mentions this issue: |
Is this expected behavior? I would think it should be possible to link to another anchor on the same page in the generated docs for https://pkg.go.dev (for example, something in
This is a good point — in the context of the editor, "go to definition" would be convenient, but linking to https://pkg.go.dev for the current package would probably also work for packages that have docs published there. I would expect that https://pkg.go.dev normally generates these as URL fragments like mentioned above, but in the editor that wouldn't work as expected. I looked into how another language server I use implemented "go to definition" for this particular use case, and it looks like they use a nonstandard LSP extension to provide the client with a clickable "go to definition" command 😞. So I guess short of implementing something like that, just using https://pkg.go.dev is probably the most reasonable option. |
|
It is expected behavior. from
https://tip.golang.org/doc/comment
A span of unindented non-blank lines defines link targets when every line
is of the form “[Text]: URL”.
…On Tue, Feb 21, 2023 at 9:59 AM Ian Chamberlain ***@***.***> wrote:
1. The reason [absolute markdown links] doesn't work is that the block
containing its definition is not recognized as a link definition block,
because #Example is not recognized as a URL. Removing that line produces
links for [absolute markdown links]
Is this expected behavior? I would think it should be possible to link to
another anchor on the same page in the generated docs for
https://pkg.go.dev (for example, something in fmt might link to
#hdr-Printing or #example-Stringer)? I guess maybe this deserves a
separate issue for go doc and/or pkgsite, since that behavior would
determine how gopls should behave?
1. go doc does not seem to generate any kind of link for [Block]. What
link might be generated, remembering that links are to URLs? ('go to
definition' isn't implemented by a URL)
This is a good point — in the context of the editor, "go to definition"
would be convenient, but linking to https://pkg.go.dev for the current
package would probably also work for packages that have docs published
there. I would expect that https://pkg.go.dev normally generates these as
URL fragments like mentioned above, but in the editor that wouldn't work as
expected.
I looked into how another language server I use implemented "go to
definition" for this particular use case, and it looks like they use a
nonstandard LSP extension to provide the client with a clickable "go to
definition" command 😞. So I guess short of implementing something like
that, just using https://pkg.go.dev is probably the most reasonable
option.
—
Reply to this email directly, view it on GitHub
<#58352 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/ABJIAI4IV6MKVUZJOVV4J23WYTJ53ANCNFSM6AAAAAAUS4GCMM>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
Hmm, I guess more precisely what I meant was: is it expected that I guess technically it is a URI but not a URL (according to RFCs 3986 and 1738), but I think common usage would indicate that fragments can be considered as URLs (in fact, in the docs you linked the All that to say — if fragments like this are never intended to be supported, then perhaps the documentation should be updated to explicitly indicate this (something like Or, if these kinds of links should be supported, then perhaps the behavior of |
gopls version
go env
What did you do?
The new go1.19 doc comments are rendered to markdown, as mentioned in #54260, but the implementation seems to be incomplete to me. Mostly, linking to anything (package-local or otherwise) seems broken, and markdown links don't render as expected.
I believe all of these formats should be supported per https://go.dev/doc/comment#links
Sample program:
What did you expect to see?
I would expect a hover comment to render something like this (using GitHub to render the expected markdown):
Whether
fmt.Printlnshould link topkg.go.devor be a "go to definition" link is up for debate, but maybe making it configurable would be nice?For local links like
StructI think the same question applies but I would lean towards "go to definition", it seems there has been some tangentially related discussion in #44890.What did you see instead?
Clicking the
fmtlinks leads to this:Editor and settings
Relevant config:
{ "go.buildOnSave": "off", "go.formatTool": "gofumpt", "go.lintOnSave": "file", "go.terminal.activateEnvironment": false, "go.toolsManagement.autoUpdate": true, "go.vetOnSave": "off", "go.testExplorer.enable": true, "go.useLanguageServer": true, "go.inlayHints.assignVariableTypes": false, "go.inlayHints.compositeLiteralFields": true, "go.inlayHints.compositeLiteralTypes": true, "go.inlayHints.constantValues": true, "go.inlayHints.functionTypeParameters": true, "go.inlayHints.parameterNames": true, "go.inlayHints.rangeVariableTypes": false, "gopls": { "ui.completion.usePlaceholders": true, "ui.navigation.importShortcut": "Definition", "ui.semanticTokens": true, "noSemanticString": true, "noSemanticNumber": true, }, }Logs
N/A, I think — but I can capture some if necessary.
The text was updated successfully, but these errors were encountered: