search

golang / go

The Go programming language
https://go.dev
BSD 3-Clause "New" or "Revised" License
124.39k stars 17.71k forks source link

x/tools/gopls: render code blocks in hover differently if they are not used for Go code #47286

Open jeffreyyjp opened 3 years ago

jeffreyyjp commented 3 years ago

For asking questions, see:

Before filing an issue, please review our troubleshooting guides

Please answer these questions before submitting your issue. Thanks!

What version of Go, VS Code & VS Code Go extension are you using?

go env Workspace Folder (gopl.io): /home/jeffrey/Coding/Myself/opensource/gopl.io GO111MODULE="" GOARCH="amd64" GOBIN="" GOCACHE="/home/jeffrey/.cache/go-build" GOENV="/home/jeffrey/.config/go/env" GOEXE="" GOFLAGS="" GOHOSTARCH="amd64" GOHOSTOS="linux" GOINSECURE="" GOMODCACHE="/home/jeffrey/go/pkg/mod" GONOPROXY="" GONOSUMDB="" GOOS="linux" GOPATH="/home/jeffrey/go" GOPRIVATE="" GOPROXY="https://proxy.golang.org,direct" GOROOT="/usr/local/go" GOSUMDB="sum.golang.org" GOTMPDIR="" GOTOOLDIR="/usr/local/go/pkg/tool/linux_amd64" GOVCS="" GOVERSION="go1.16.4" GCCGO="gccgo" AR="ar" CC="gcc" CXX="g++" CGO_ENABLED="1" GOMOD="/dev/null" CGO_CFLAGS="-g -O2" CGO_CPPFLAGS="" CGO_CXXFLAGS="-g -O2" CGO_FFLAGS="-g -O2" CGO_LDFLAGS="-g -O2" PKG_CONFIG="pkg-config" GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build296281853=/tmp/go-build -gno-record-gcc-switches"

Share the Go related settings you have added/edited

Run Preferences: Open Settings (JSON) command to open your settings.json file. Share all the settings with the go. or ["go"] or gopls prefixes.

Describe the bug

A clear and concise description of what the bug. Some function linting doesn't have a consistent style, for example: text color. The below are an screenshot that show this

A clear and concise description of what you expected to happen.

A consistent style for function linting display.

Steps to reproduce the behavior:

  1. hover cursor on function, look at the linting
  2. See the display.

Screenshots or recordings

If applicable, add screenshots or recordings to help explain your problem. image

findleyr commented 3 years ago

Thanks. We seem not to be applying the correct markdown formatting in this case.

findleyr commented 3 years ago

Ok, it looks like we're not specifying go syntax for the preformatted text here, it is being auto-applied by VS Code. Other clients (for example coc.nvim) do not have this problem.

findleyr commented 3 years ago

Hah, we can get the correct behavior by formatting our pre-block like this, i.e. chosing a non-existent syntax:

```blahblahblah
Documentation


It's unclear to me what's correct here. https://blog.golang.org/godoc says simply that indented blocks should be pre-formatted (meaning no syntax highlighting).  Markdown says fenced (or indented) blocks are 'code blocks', with varying implementations.

We could use embedded html `<pre>` blocks (though some clients might not support this), or the hacky fix above, but I'm inclined to say this is simply a VS Code bug. It's also true that indented documentation blocks often _are_ go code, so fixing this bug would remove appropriate highlighting in those cases, though as mentioned this is not specified by godoc.
hyangah commented 3 years ago 
[Trace - 12:36:07.328 PM] Received response 'textDocument/hover - (10)' in 3ms.
Result: {"contents":{"kind":"markdown","value":"```go\nfunc(t Type, size ...IntegerType) Type\n```\n\n
[`make` on pkg.go.dev](https://pkg.go.dev/builtin?utm_source=gopls#make)\n\n
The make built\\-in function allocates and initializes an object of type\nslice, map, or chan \\(only\\)\\. Like new, the first argument is a type, not a\nvalue\\. Unlike new, make\\'s return type is the same as the type of its\nargument, not a pointer to it\\. The specification of the result depends on\nthe type\\:\n\n
    Slice: The size specifies the length. The capacity of the slice is\n
    equal to its length. A second integer argument may be provided to\n
    specify a different capacity; it must be no smaller than the\n
    length. For example, make([]int, 0, 10) allocates an underlying array\n
    of size 10 and returns a slice of length 0 and capacity 10 that is\n
    backed by this underlying array.\n
    Map: An empty map is allocated with enough space to hold the\n
    specified number of elements. The size may be omitted, in which case\n
    a small starting size is allocated.\n
    Channel: The channel's buffer is initialized with the specified\n
    buffer capacity. If zero, or the size is omitted, the channel is\n
    unbuffered.\n"},"range":{"start":{"line":19,"character":11},"end":{"line":19,"character":15}}}

I am not sure about all the scaping logic here. What will happen if the ' in The channel's buffer is escaped?

hyangah commented 3 years ago

As @findleyr analyzed, the root cause is that vscode assumes the code blocks in hover are go code, which is untrue in this specific case. We think the code blocks are used often to show how to use the APIs and present code examples, so we decided not to add a workaround for vscode yet.

If this becomes common issues, we can consider using workarounds like

I am transferring to the gopls issue tracker.