While solving https://github.com/golang/go/issues/46136 by adding a new analyzers, stdversion, we created an internal helper package https://pkg.go.dev/golang.org/x/tools/internal/stdlib that contains a manifest of all std symbols and their versions. We should use this information in Completions, to ensure that only version-appropriate completions are offered; and in Hover, to report the initial Go version for each std symbol. And perhaps other places as well.

Comment From: adonovan

On closer inspection, apparently I already added version support to completion. So that leaves just Hover.

Comment From: findleyr

A few rough ideas for how this could be implemented:

  • I think we should add an asOfVersion string field to hoverJSON. hoverJSON separates the data underlying hover from its presentation. The presentation format varies depending on client capabilities.
  • At the bottom of ./gopls/internal/golang.hover, where we have a non-nil obj (the types.Object describing the declaration), look up when the object was added to the standard library in ./internal/stdlib. Not sure exactly the best way to do this -- left as an exercise for the reader, but see existing usage of stdlib.PackageSymbols. In particular, Symbol.SplitField and Symbol.SplitMethod may be helpful for looking up fields and methods. We should perhaps have a helper to look up a types.Object.
  • If found, format the asOfVersion version as go1.X.
  • In at least the markdown presentation, insert an added in go1.X note somewhere. pkgsite provides an example for how users are accustomed to seeing this, e.g. https://pkg.go.dev/errors#As.
  • Add a new test file in ./gopls/internal/test/marker/testdata/hover exercising various standard library hover examples. In this file, we should exercise hover for at least (1) a symbol that has always existed in the standard library, (2) a symbol that was added to an existing package in a go version (such as errors.As), and (3) a symbol that was in the first version of a new package, such as slices.Contains.

CC @h9jiang @hyangah

Comment From: adonovan

We should perhaps have a helper to look up a types.Object.

While we're at it, we should use the same helper in the internal doc viewer (gopls/internal/golang/pkgdoc.go). This can be a separate CL.

Comment From: h9jiang

Please assign to me to take a look. :D Thanks.

I will comment again for further questions.

Comment From: gopherbot

Change https://go.dev/cl/594875 mentions this issue: gopls/internal/server/hover: provide available version for std lib

Comment From: gopherbot

Change https://go.dev/cl/595135 mentions this issue: gopls/internal/golang: provide version info for stdlib methods

Comment From: gopherbot

Change https://go.dev/cl/595336 mentions this issue: gopls/internal/golang: provide version info for stdlib fields

Comment From: gopherbot

Change https://go.dev/cl/595855 mentions this issue: gopls/internal/golang: provide version info for stdlib in pkgdoc