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: add method documentation & jump to page source to hovered type. #66721

Closed
tobigiwa opened this issue Apr 8, 2024 · 15 comments · May be fixed by golang/tools#487
Closed

x/tools/gopls: add method documentation & jump to page source to hovered type. #66721

tobigiwa opened this issue Apr 8, 2024 · 15 comments · May be fixed by golang/tools#487
Labels
Documentation 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

@tobigiwa
Copy link

tobigiwa commented Apr 8, 2024

gopls version

Build info ---------- golang.org/x/tools/gopls v0.15.2 golang.org/x/tools/[email protected] h1:4JKt4inO8JaFW3l/Fh9X1k/5JQn+iUOpdc4/Lpi0mOs= github.com/BurntSushi/[email protected] h1:9F2/+DoOYIOksmaJFPw1tGFy1eDnIJXg+UHjuD8lTak= github.com/google/[email protected] h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI= golang.org/x/exp/[email protected] h1:2O2DON6y3XMJiQRAS1UWU+54aec2uopH3x7MAiqGW6Y= golang.org/x/[email protected] h1:SernR4v+D55NyBH2QiEQrlBAnj1ECL6AGrA5+dPaMY8= golang.org/x/[email protected] h1:5BMeUDZ7vkXGfEr1x9B4bRcTH4lpkTkpdh0T/J+qjbQ= golang.org/x/[email protected] h1:vcVnuftN4J4UKLRcgetjzfU9FjjgXUUYUc3JhFplgV4= golang.org/x/[email protected] h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= golang.org/x/[email protected] h1:No0LMXYFkp3j4oEsPdtY8LUQz33gu79Rm9DE+izMeGQ= golang.org/x/[email protected] h1:KUas02EjQK5LTuIx1OylBQdKKZ9jeugs+HiqO5HormU= honnef.co/go/[email protected] h1:oFEHCKeID7to/3autwsWfnuv69j3NsfcXbvJKuIcep8= mvdan.cc/[email protected] h1:G3QvahNDmpD+Aek/bNOLrFR2XC6ZAdo62dZu65gmwGo= mvdan.cc/xurls/[email protected] h1:lyBNOm8Wo71UknhUs4QTFUNNMyxy2JEIaKKo0RWOh+8= go: go1.22.1

go env

GO111MODULE=''
GOARCH='amd64'
GOBIN=''
GOCACHE='/home/tobigiwa/.cache/go-build'
GOENV='/home/tobigiwa/.config/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFLAGS=''
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMODCACHE='/home/tobigiwa/go/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='linux'
GOPATH='/home/tobigiwa/go'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/usr/local/go'
GOSUMDB='sum.golang.org'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/usr/local/go/pkg/tool/linux_amd64'
GOVCS=''
GOVERSION='go1.22.1'
GCCGO='gccgo'
GOAMD64='v1'
AR='ar'
CC='gcc'
CXX='g++'
CGO_ENABLED='1'
GOMOD='/home/tobigiwa/mod/tools/gopls/go.mod'
GOWORK=''
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
PKG_CONFIG='pkg-config'
GOGCCFLAGS='-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=/tmp/go-build2583342046=/tmp/go-build -gno-record-gcc-switches'

What did you do?

No error, just feature request.

What did you see happen?

Hover on user defined type, or any type with method just shows method signature only. Most of the time, I'll like to know what these method do and be able to jump into them easily.

What did you expect to see?

Method docs and jump to page source in hover popup.

Editor and settings

Nothing extra.

Logs

No response

@tobigiwa tobigiwa 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 Apr 8, 2024
@gopherbot gopherbot added this to the Unreleased milestone Apr 8, 2024
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/577235 mentions this issue: gopls: added method docs to hover info

tobigiwa added a commit to tobigiwa/tools that referenced this issue Apr 8, 2024
The change also includes a jump to definition feature for all methods.The
change is quite fail-safe, such that if it fails in any way, it will still
display the hover info without the method docs(as before). The change is
localised to the the gopls/internal/golang/hover.go file, in function
hover and formatHover.
I should also mention that it does not alter the method displayed or it
order, it just add the method docs (if any) and a jump to page source
url to the hover info.

Fixes golang/go#66721
Fixes golang/go#66721

Signed-off-by: tobigiwa <[email protected]>
@tobigiwa
Copy link
Author

tobigiwa commented Apr 8, 2024

from
Screenshot from 2024-04-08 11-17-45

@tobigiwa
Copy link
Author

tobigiwa commented Apr 8, 2024

To
Screenshot from 2024-04-08 11-18-57
Screenshot from 2024-04-08 11-19-09

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/577356 mentions this issue: gopls: added method docs to hover info

@adonovan
Copy link
Member

adonovan commented Apr 8, 2024

I suspect this change could make the hover popup very long indeed.

Also, one typically needs just a brief reminder of which methods are available on the type. If you need to study the methods more closely, you can jump to their definition, or (in the forthcoming release) open the documentation for the type.

@adonovan
Copy link
Member

P.S. thanks for sending a potential fix, but in the future it's really worth discussing the desired behavior before starting to write code.

@tobigiwa
Copy link
Author

@adonovan I was only looking at the slack channel for response on this, I sincerely did'nt notice you have said something here 4 days ago. Thanks for taking the time.

Regarding your earlier comment, I can summarize your concerns into 2: Performance and Utility, correct?.

Regarding performance, I did not notice any difference (from my computer here, which is entirely not enough 😆), but if there is a way to benchmark or show something tangible to convince you instead, please let me know.

In the case of it utility, I actually borrowed the feature from a popular Go IDE (you know which, refrainning from naming), which is quite helpful and useful for me (also not enough, lot of people use Gopls). If it utility, I cannot argue for much I'll suppose.

@tobigiwa
Copy link
Author

If it only performance, please let me know how to go about it.

P.S. thanks for sending a potential fix, but in the future it's really worth discussing the desired behavior before starting to write code.
I was just too excited I guess, digging into Go internals, for next time... I would have this in mind.

@adonovan
Copy link
Member

Regarding your earlier comment, I can summarize your concerns into 2: Performance and Utility, correct?.

My concern was only about the user experience; I don't expect performance to be a problem. The complete documentation for all the methods of a type seems like a lot of information to show in a popup. Perhaps you could attach a screenshot of the feature in the "popular IDE" that might demonstrate the desired effect.

You might also be interested in a new feature in the upcoming gopls/v0.16.0 release: an integrated viewer for Go package documentation; see https://cs.opensource.google/go/x/tools/+/master:gopls/doc/release/v0.16.0.md.

@tobigiwa
Copy link
Author

tobigiwa commented Apr 14, 2024

Just looked at the Integrated documentation viewer, that very cool. So, regarding the implementation of this feature in the "known IDE", it looks like this.;

Screenshot from 2024-04-14 14-58-05

The method names are actually url (obvious when you hover, shows the underline), when you click them...

Screenshot from 2024-04-14 14-58-36

The full type popup tears down then this 👆, to get back, you just press the type name in the receiver. Very neat, but this would require HTML, which is sanitized in vscode-go extension (I actually discovered so, I have not looked at the extension code, I actually did... did'nt figure much of it).

My plan was to use the details tag of markdown, but it still html, sanitized too. It looks like this;

func (b *Builder) copyCheck()

The docs then goes here.

@tobigiwa
Copy link
Author

I don't know why it showing the copy thing... guessing Github, like I mentioned, I could not test this out, since the html was sanitized.

@adonovan
Copy link
Member

Re-opening so we can discuss this in our triage meeting.

@adonovan adonovan reopened this Apr 16, 2024
@tobigiwa
Copy link
Author

tobigiwa commented Apr 18, 2024

Re-opening so we can discuss this in our triage meeting.

Oh...this is good, I did see the word "triage" in the contribution guide ( I did'nt keep in my head, I'll look it up again), I had another thought about implementing what the "popular IDE" has.

As the LSP specs dictates, the return from Hover can be a MarkString, []MarkString or MarkUpContent, MarkString is deprecated though. If we can an array of MarkString or MarkUpContent, the other items would be the docs, so the 0th item would be the popup has we have it before, each method having a url that point to ith item for it docs. The solution would involve touching both the lsp and each editor client.

I just want to mention this too.

@findleyr
Copy link
Contributor

I think we're very limited in what we can do in a hover popup, and the current content was chosen to be as dense as possible while retaining readability. A documentation viewer (forthcoming in [email protected]) is a better place to view documentation.

@findleyr findleyr closed this as not planned Won't fix, can't repro, duplicate, stale Apr 25, 2024
@tobigiwa
Copy link
Author

This is sad 😔🙁

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation 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

Successfully merging a pull request may close this issue.

4 participants