x/tools/gopls: feature request - render example tests as part of hover documentation

[SKalt]

gopls version

v0.17.1

Build info
----------
golang.org/x/tools/gopls v0.17.1
    golang.org/x/tools/gopls@v0.17.1 h1:Mt/DSfnnSe3dyf6MH/dZZ0iww+viHNhAFc4rEYDiOAw=
    github.com/BurntSushi/toml@v1.4.1-0.20240526193622-a339e1f7089c h1:pxW6RcqyfI9/kWtOwnv/G+AzdKuy2ZrqINhenH4HyNs=
    github.com/google/go-cmp@v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
    golang.org/x/exp/typeparams@v0.0.0-20231108232855-2478ac86f678 h1:1P7xPZEwZMoBoz0Yze5Nx2/4pxj6nw9ZqHWXqP0iRgQ=
    golang.org/x/mod@v0.22.0 h1:D4nJWe9zXqHOmWqj4VMOJhvzj7bEZg4wEYa759z1pH4=
    golang.org/x/sync@v0.9.0 h1:fEo0HyrW1GIgZdpbhCRO0PkJajUS5H9IFUztCgEo2jQ=
    golang.org/x/telemetry@v0.0.0-20241106142447-58a1122356f5 h1:TCDqnvbBsFapViksHcHySl/sW4+rTGNIAoJJesHRuMM=
    golang.org/x/text@v0.20.0 h1:gK/Kv2otX8gz+wn7Rmb3vT96ZwuoxnQlY+HlJVj7Qug=
    golang.org/x/tools@v0.27.1-0.20241219162658-575221bfbda3 h1:kgwdasJRsdDWYgWcEgMF424DiXwwXHSb3V8xVTi//i8=
    golang.org/x/vuln@v1.0.4 h1:SP0mPeg2PmGCu03V+61EcQiOjmpri2XijexKdzv8Z1I=
    honnef.co/go/tools@v0.5.1 h1:4bH5o3b5ZULQ4UrBmP+63W9r7qIkqJClEA9ko5YKx+I=
    mvdan.cc/gofumpt@v0.7.0 h1:bg91ttqXmi9y2xawvkuMXyvAA/1ZGJqYAEGjXuP0JXU=
    mvdan.cc/xurls/v2@v2.5.0 h1:lyBNOm8Wo71UknhUs4QTFUNNMyxy2JEIaKKo0RWOh+8=
go: go1.24.0

go env

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

What did you do?

I wanted to provide document usage for a public function, and I wanted its documentation to stay up-to-date. Luckily for me, Go's testing package supports testing examples associated with public functions: see https://pkg.go.dev/testing#hdr-Examples.

I tried it out:

package mypkg

// MyFunc docs
//
//	demoCode() { /* never tested, not necessarily go */ }
func MyFunc() int {
	return 1
}

package mypkg_test

import (
	"fmt"

	"github.com/skalt/temp.go/mypkg"
)

func ExampleMyFunc() { // ExampleX should be associated with function X or type X 
	fmt.Println(mypkg.MyFunc())
	// Output:
	// 1
}

(the full code can be found at https://github.com/SKalt/temp.go/tree/25e36e5)

Finally, I hovered over my function expecting to see some reference to my example.

What did you see happen?

In VSCode, I couldn't see any reference to the example I associated with my function:

However, GoLand displayed footers in its on-hover doucumentation tooltip. The footer included a link to my example, the body of my example function, and the expected output.

What did you expect to see?

I'd like gopls to provide tested examples in on-hover docs like GoLand does. I think easier access to tested examples would be well worth the extra screen space!

I'd be happy to implement this and submit a CL if I get buy-in. My plan is to write some sort of findExamples() call inside hover() in gopls/internal/golang/hover.go.

Editor and settings

VScode:

{
    "gopls": {
        "ui.documentation.hoverKind": "FullDocumentation" // default value
    }
}

Logs

No response

[gabyhelp]

Related Issues

• x/tools/gopls: add method documentation & jump to page source to hovered type. #66721 (closed)
• x/tools/gopls: render doc links properly in hover #58352 (closed)
• x/tools/gopls: gopls doc viewer failed with "package not found" error #70453 (closed)
• x/tools/gopls: broken hovering in the builtin file #68026 (closed)
• x/tools/gopls: snippets do not replace triggering preamble #59508 (closed)
• x/tools/gopls: Autocompletion implementation should contain comments for the interface. #65543 (closed)
• x/tools/gopls: missing function name in signature when hovering over built-in function #51811 (closed)
• x/tools/gopls: reconsider placement of pkg.go.dev link in hover #36992 (closed)
• x/tools/gopls: empty hover response should be null, not a zero struct #37570 (closed)
• x/tools/gopls: hover stops working #64778 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[SKalt]

Unlike any of the above issues, I'm interested in displaying examples library authors explicitly provided as documentation. GoLand renders examples in full, but I'd also be open to providing links to the examples to minimize the amount of text included in hover boxes.