Skip to content

x/tools/godoc: may show Go version when an identifier was modified rather than originally added #44081

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.

Sign up for GitHub

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

Jump to bottom
Closed
dmitshur opened this issue Feb 3, 2021 · 3 comments
Closed

x/tools/godoc: may show Go version when an identifier was modified rather than originally added #44081

dmitshur opened this issue Feb 3, 2021 · 3 comments
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone
Unreleased

Comments

@dmitshur
Copy link
Member

dmitshur commented Feb 3, 2021 •
edited
Loading

godoc (and in turn, https://golang.org/pkg/) displays next to identifiers the version of Go when said identifier was added. This was #5778.

As reported by @benhoyt in a golang-dev thread, godoc may sometimes show that an identifier was added in a Go version too new.

This happens when a signature is modified in a later Go version. For example, the os.Chmod function was added in Go 1 and appears in api/go1.txt as:

pkg os, func Chmod(string, FileMode) error

In Go 1.16, the os.FileMode type was modified (in an API compatible way: it became a type alias to fs.FileMode), causing os.Chmod to show up in api/go1.16.txt:

pkg os, func Chmod(string, fs.FileMode) error

(As far as I can tell from aliasReplacer and its comment, added to cmd/api by @rsc in CL 243906, the api file content is working as intended; please comment otherwise.)

The fix in godoc is to look for the earliest api/go*.txt file where an identifier was mentioned. I'll send a CL.

CC @ianlancetaylor, @julieqiu.
@dmitshur dmitshur added the NeedsFix The path to resolution is known, but the work has not been done. label Feb 3, 2021
@dmitshur dmitshur added this to the Unreleased milestone Feb 3, 2021
@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Feb 3, 2021
@dmitshur dmitshur self-assigned this Feb 3, 2021
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/289089 mentions this issue: godoc: show earliest version when identifier was added

@julieqiu
Copy link
Member

julieqiu commented Feb 3, 2021 •
edited
Loading

This is related to #37102 for pkgsite. We are planning to add this information for all packages.

@dmitshur dmitshur mentioned this issue Feb 9, 2021
Closed
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/290609 mentions this issue: website: update to golang.org/x/[email protected]

gopherbot pushed a commit to golang/website that referenced this issue Feb 10, 2021
@dmitshur
website: update to golang.org/x/[email protected]
a9012f5 
Bring in the godoc fix made in CL 289089 with:

	go get golang.org/x/tools/godoc@61406578735f11efca21e2be93800cf530d25ecb
	go mod tidy

Fixes golang/go#44178.
Updates golang/go#44081.

Change-Id: Icaee037626e93e6fc5939b163760ad11873a3f0b
Reviewed-on: https://go-review.googlesource.com/c/website/+/290609
TryBot-Result: Go Bot <[email protected]>
Trust: Dmitri Shuralyov <[email protected]>
Run-TryBot: Dmitri Shuralyov <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>
@golang golang locked and limited conversation to collaborators Feb 9, 2022
henderjon pushed a commit to oggodoc/godoc that referenced this issue Jun 13, 2024
@dmitshur
godoc: show earliest version when identifier was added
a183da6 
CL 85396 implemented parsePackageAPIInfo with the idea that each
identifier shows up in exactly one of api/go*.txt files, when it
was added. We now know that it may show up more than once, when
the signature changes (generally in a compatible way, such as
when existing types are replaced with aliases to an equivalent
type).

Modify the algorithm to parse the api/go*.txt files in reverse
order, in order to find and display the earliest Go version when
each identifier was first added.

Fixes golang/go#44081.
Updates golang/go#5778.

Change-Id: I83171fd8c161d703f284011375d74b824c279d41
Reviewed-on: https://go-review.googlesource.com/c/tools/+/289089
Run-TryBot: Dmitri Shuralyov <[email protected]>
gopls-CI: kokoro <[email protected]>
TryBot-Result: Go Bot <[email protected]>
Trust: Dmitri Shuralyov <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
3 participants
@dmitshur @julieqiu @gopherbot