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: render code blocks in hover differently if they are not used for Go code #47286

Open
jeffreyyjp opened this issue Jul 9, 2021 · 5 comments

Comments

@jeffreyyjp
Copy link

@jeffreyyjp jeffreyyjp commented Jul 9, 2021

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?

  • Run go version to get version of Go from the VS Code integrated terminal.
    • go version go1.16.4 linux/amd64
  • Run gopls -v version to get version of Gopls from the VS Code integrated terminal.
    • Build info

golang.org/x/tools/gopls v0.7.0
golang.org/x/tools/gopls@v0.7.0 h1:JQBHW81Gsyim6iDjUwGoPeSpXrSqwen3isPJLfDfaYU=
github.com/BurntSushi/toml@v0.3.1 h1:WXkYYl6Yr3qBf1K79EBnL4mak0OimBfB0XUf9Vl28OQ=
github.com/google/go-cmp@v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
github.com/sergi/go-diff@v1.1.0 h1:we8PVUC3FE2uYfodKH/nBHMSetSfHDR6scGdBi+erh0=
golang.org/x/mod@v0.4.2 h1:Gz96sIWK3OalVv/I/qNygP42zyoKp3xptRVCWRFEBvo=
golang.org/x/sync@v0.0.0-20210220032951-036812b2e83c h1:5KslGYwFpkhGh+Q16bwMP3cOontH8FOep7tGV86Y7SQ=
golang.org/x/sys@v0.0.0-20210510120138-977fb7262007 h1:gG67DSER+11cZvqIMb8S8bt0vZtiN6xWYARwirrOSfE=
golang.org/x/tools@v0.1.3-0.20210608163600-9ed039809d4c h1:Pv9gNyJFYVdpUAVZYJ1BDSU4eGgXQ+0f3DIGAdolO5s=
golang.org/x/xerrors@v0.0.0-20200804184101-5ec99f83aff1 h1:go1bK/D/BFZV2I8cIQd1NKEZ+0owSTG1fDTci4IqFcE=
honnef.co/go/tools@v0.2.0 h1:ws8AfbgTX3oIczLPNPCu5166oBg9ST2vNs0rcht+mDE=
mvdan.cc/gofumpt@v0.1.1 h1:bi/1aS/5W00E2ny5q65w9SnKpWEF/UIOqDYBILpo9rA=
mvdan.cc/xurls/v2@v2.2.0 h1:NSZPykBXJFCetGZykLAxaL6SIpvbVy/UFEniIfHAa8A=

  • Run code -v or code-insiders -v to get version of VS Code or VS Code Insiders.

    • 1.58.0
      2d23c42a936db1c7b3b06f918cde29561cc47cd6
      x64
  • Check your installed extensions to get the version of the VS Code Go extension

    • 0.26.0
  • Run Ctrl+Shift+P (Cmd+Shift+P on Mac OS) > Go: Locate Configured Go Tools command.

    • Checking configured tools....
      GOBIN: undefined
      toolsGopath:
      gopath: /home/jeffrey/go
      GOROOT: /usr/local/go
      PATH: /usr/local/go/bin:/home/jeffrey/.vscode-server/bin/2d23c42a936db1c7b3b06f918cde29561cc47cd6/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/mnt/c/WINDOWS/system32:/mnt/c/WINDOWS:/mnt/c/WINDOWS/System32/Wbem:/mnt/c/WINDOWS/System32/WindowsPowerShell/v1.0/:/mnt/c/WINDOWS/System32/OpenSSH/:/mnt/d/programs/Git/cmd:/mnt/d/programs/Minikube:/mnt/c/Program Files/Docker/Docker/resources/bin:/mnt/c/ProgramData/DockerDesktop/version-bin:/mnt/c/Users/yangjianpeng/AppData/Local/Microsoft/WindowsApps:/mnt/d/programs/Microsoft VS Code/bin

    gopkgs: /home/jeffrey/go/bin/gopkgs installed
    go-outline: /home/jeffrey/go/bin/go-outline installed
    gotests: /home/jeffrey/go/bin/gotests installed
    gomodifytags: /home/jeffrey/go/bin/gomodifytags installed
    impl: /home/jeffrey/go/bin/impl installed
    goplay: /home/jeffrey/go/bin/goplay installed
    dlv: /home/jeffrey/go/bin/dlv installed
    dlv-dap: /home/jeffrey/go/bin/dlv-dap installed
    staticcheck: /home/jeffrey/go/bin/staticcheck installed
    gopls: /home/jeffrey/go/bin/gopls installed

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
Copy link
Contributor

@findleyr findleyr commented Jul 9, 2021

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

@findleyr findleyr self-assigned this Jul 9, 2021
@findleyr
Copy link
Contributor

@findleyr findleyr commented Jul 9, 2021

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
Copy link
Contributor

@findleyr findleyr commented Jul 9, 2021

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.

@findleyr findleyr removed their assignment Jul 9, 2021
@hyangah
Copy link
Contributor

@hyangah hyangah commented Jul 12, 2021

[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
Copy link
Contributor

@hyangah hyangah commented Jul 19, 2021

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

  • mark all code blocks to be code for a non-existing language, or
  • make gopls guess whether the code blocks are used to for Go code (e.g. try to parse as a go code) or a pre-formatted paragraph and render it differently (e.g. non-existing language for non-code, or use <pre>

I am transferring to the gopls issue tracker.

@hyangah hyangah changed the title function linting display issue x/tools/gopls: render code blocks in hover differently if they are not used for Go code Jul 19, 2021
@hyangah hyangah transferred this issue from golang/vscode-go Jul 19, 2021
@gopherbot gopherbot added this to the Unreleased milestone Jul 19, 2021
@hyangah hyangah removed this from the Unreleased milestone Jul 19, 2021
@hyangah hyangah added this to the gopls/unplanned milestone Jul 19, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants