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.

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

x/tools/cmd/godoc: show which version of Go introduced symbols #5778

Closed
ncw opened this issue Jun 25, 2013 · 34 comments
Closed

x/tools/cmd/godoc: show which version of Go introduced symbols #5778

ncw opened this issue Jun 25, 2013 · 34 comments
Labels
Documentation FeatureRequest FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Unplanned

Comments

@ncw
Copy link
Contributor

ncw commented Jun 25, 2013 

Go documentation is very good, but it doesn't clearly label which go version features
are available in.

For instance I was caught out by http://golang.org/pkg/time/#Timer.Reset being a go 1.1
feature which meant my code would no longer compile with go 1.0.

Other examples are 

  * http://golang.org/pkg/net/http/#Transport.CancelRequest
  * ResponseHeaderTimeout in http://golang.org/pkg/net/http/#Transport
@adg
Copy link
Contributor

adg commented Jun 25, 2013

Comment 1:

How did it catch you out? Why can't you just update the 1.0-based systems to 1.1?

Status changed to Thinking.

@ncw
Copy link
Contributor Author

ncw commented Jun 25, 2013

Comment 2:

I was updating a public library and I don't want to break 1.0 compatibility for my users
just yet, but I managed to do that by accident!

@ianlancetaylor
Copy link
Member

Comment 3:

The additions are noted at http://golang.org/doc/go1.1 , but it's true that it might be
useful to also note them in the individual docs.  Or perhaps we can have go api check
status of code.

@rsc
Copy link
Contributor

rsc commented Jul 2, 2013

Comment 4:

Maybe godoc should read $GOROOT/api/go1.1.txt.

@rsc
Copy link
Contributor

rsc commented Jul 30, 2013

Comment 5:

Labels changed: added priority-later, go1.2maybe, removed priority-triage.

@rsc
Copy link
Contributor

rsc commented Sep 10, 2013

Comment 6:

Labels changed: added documentation.

@rsc
Copy link
Contributor

rsc commented Oct 3, 2013

Comment 7:

Probably too big for now.

Labels changed: added go1.3, removed go1.2maybe.

@rsc
Copy link
Contributor

rsc commented Dec 4, 2013

Comment 8:

Labels changed: added release-go1.3, removed go1.3.

@rsc
Copy link
Contributor

rsc commented Dec 4, 2013

Comment 9:

Labels changed: added repo-main.

@rsc
Copy link
Contributor

rsc commented May 19, 2014

Comment 10:

Labels changed: added release-none, removed release-go1.3.

@pierrre
Copy link

pierrre commented Jun 6, 2014

Comment 11:

In Android doc: http://developer.android.com/reference/packages.html
you can filter by API level.

@ianlancetaylor
Copy link
Member

Comment 12:

Issue #8468 has been merged into this issue.

@ianlancetaylor ianlancetaylor mentioned this issue Dec 8, 2014
Closed
@rsc rsc added this to the Unplanned milestone Apr 10, 2015
@hirochachacha hirochachacha mentioned this issue Jan 9, 2016
Closed
@arvenil arvenil mentioned this issue Feb 23, 2016
Closed
@arvenil
Copy link

arvenil commented Feb 23, 2016

Like I've mentioned in other issue I wasted a lot of time trying to figure out why some network error was not catch by err.(net.Error) even though docs clearly stated it should. Turned out url.Error implements net.Error since go 1.6. Since the issue is old, just a kind reminder that this issued didn't disappeared ;)

@minux minux mentioned this issue Feb 24, 2016
Closed
@kostya-sh
Copy link
Contributor

Given quite a few new functions (user.LookupGroup, etc), interfaces (io.ReadAtSizer, etc), constants (io.SeekStart, etc) and even a new package (context) that are planned for Go 1.7 would it make sense to start providing information about version the new functionality is available in in the docs? Even a manually added Added in 1.7 line would be quite useful. I think a convention similar to Deprecated: .... could be established.

@bradfitz
Copy link
Contributor

bradfitz commented Apr 7, 2016

In 99% of the cases, we don't need to hand edit the documentation text to say when it was added. We know from api/*.txt files already: https://github.com/golang/go/tree/master/api

@arvenil
Copy link

arvenil commented Apr 8, 2016

The problem is when you look at documentation you don't look at the same time at api/.txt.
Wouldn't make sense to programmatically export data from api/.txt and apply it to the docs during dock building process?

@bradfitz
Copy link
Contributor

bradfitz commented Apr 8, 2016

@arvenil, yes, that's what this bug is about.

@bradfitz bradfitz added NeedsFix The path to resolution is known, but the work has not been done. help wanted labels Dec 16, 2016
@bradfitz
Copy link
Contributor

Targeting this for Go 1.9Maybe, especially if somebody wants to implement it.

/cc @FiloSottile

@bradfitz bradfitz changed the title doc: show additions between major versions x/tools/cmd/godoc: show additions between major versions Dec 16, 2016
@bradfitz bradfitz changed the title x/tools/cmd/godoc: show additions between major versions x/tools/cmd/godoc: show which version of Go introduced symbols Dec 16, 2016
@bradfitz bradfitz modified the milestones: Go1.10, Go1.9Maybe Jun 7, 2017
@bradfitz bradfitz modified the milestones: Go1.10, Unplanned Dec 8, 2017
@dhobsd
Copy link
Contributor

dhobsd commented Dec 20, 2017

This seems like a fun and easyish holiday project. I think there are a few bits that would require some consensus:

  1. How do we display "since: X" for consts? In e.g. crypto, BLAKE2b variants are added as new Hash values in Go 1.9, but we show these consts directly from source with really no formatting. Another example would be various constants in time. Should we add a comment with "since: X" when none is present, and append otherwise?

  2. For packages like syscall, do we bother doing this at all? For example, some syscalls may not be present on all operating systems, and we do not document the SYS_FOO values. It looks like we only document syscalls that are available on all systems (f.ex. Fchflags is not present in godoc). I remember from past work on FreeBSD syscalls that things like Nanosleep were implemented on some systems before others, in which case we'd potentially have to say "Since X: Linux, Darwin; Since Y: ...". This seems like UI clutter for very little benefit for this package, so I'd be tempted to ignore it. That said, if this issue crops up for other packages, I'd love to hear thoughts.

  3. Display: for types, functions, and methods, I was thinking it'd be sufficient to have like a <h4>Since: X</h4> immediately after the h3. Does this seem reasonable, or would we want to do something more clever?

  4. Am I missing anything obvious?

@broady
Copy link
Contributor

broady commented Dec 20, 2017 via email

@bradfitz
Copy link
Contributor

bradfitz commented Dec 20, 2017 •
edited
Loading

@dhobsd, I'd start with anything for now and avoid worrying about corner cases:

  • ignore consts. start with just funcs and types. later add struct fields. later do vars & consts.
  • ignore syscall

For display, this shouldn't be too loud or take up much (if any) vertical space. See how Android and other languages/projects do it. But don't stress that bit much. Get something working, run a public instance or post screenshots, and we can iterate on the CSS/etc.

Happy Holidays! 🎅

@dhobsd
Copy link
Contributor

dhobsd commented Dec 20, 2017

Sounds great; thanks, Brad!

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/85317 mentions this issue: go/doc, cmd/doc: record/display some version info

@gopherbot
Copy link
Contributor

Change https://golang.org/cl/85396 mentions this issue: x/tools/godoc: show version information for stdlib

@dhobsd
Copy link
Contributor

dhobsd commented Dec 23, 2017

Sorry for the multiple CLs, I just read through the comments and realized my first approach wasn't what was desired.

@dhobsd
Copy link
Contributor

dhobsd commented Dec 23, 2017

I have an implementation of this running temporarily at http://66.175.217.58:6060/pkg/. Please let me know if you see any issues, or if it stops working.

@mvdan mvdan mentioned this issue Jan 6, 2018
Closed
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/124495 mentions this issue: godoc: add version info for struct fields

gopherbot pushed a commit to golang/tools that referenced this issue Jul 17, 2018
@bradfitz
godoc: add version info for struct fields
32950ab 
Follow-up to CL 85396, which only did types, funcs, and methods.

This adds version info to struct fields (in the form of small
comments) if the struct field's version is different from the struct
itself, to minimize how often this fires.

Updates golang/go#5778

Change-Id: I34d60326cbef88c108d5c4ca487eeb98b039b16e
Reviewed-on: https://go-review.googlesource.com/124495
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Devon O'Dell <dhobsd@google.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/139557 mentions this issue: cmd/godoc: add version info for golang.org

gopherbot pushed a commit to golang/tools that referenced this issue Oct 6, 2018
@broady
cmd/godoc: add version info for golang.org
f60d963 
Adds version information for package docs for the production version of
godoc running on golang.org.

Updates golang/go#5778.

Change-Id: I8b56e8152b20b34104f274263a6c0b5a0180093b
Reviewed-on: https://go-review.googlesource.com/c/139557
Reviewed-by: Devon H. O'Dell <devon.odell@gmail.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/150683 mentions this issue: [release-branch.go1.11] cmd/godoc: add version info for golang.org

gopherbot pushed a commit to golang/tools that referenced this issue Nov 21, 2018
@broady @dmitshur
[release-branch.go1.11] cmd/godoc: add version info for golang.org
d297d4d 
Adds version information for package docs for the production version of
godoc running on golang.org.

Updates golang/go#28893
Updates golang/go#5778

Change-Id: I8b56e8152b20b34104f274263a6c0b5a0180093b
Reviewed-on: https://go-review.googlesource.com/c/139557
Reviewed-by: Devon H. O'Dell <devon.odell@gmail.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-on: https://go-review.googlesource.com/c/150683
@FiloSottile FiloSottile mentioned this issue Dec 12, 2018
Open
@golang golang locked and limited conversation to collaborators Nov 20, 2019
henderjon pushed a commit to oggodoc/godoc that referenced this issue Jun 13, 2024
@dhobsd @bradfitz
godoc: show version information for stdlib
bf9b1d3 
This change reads $GOROOT/api/go1.*.txt when godoc starts and caches
information about which versions of Go introduce functions, types, and
methods. This information is displayed currently only in HTML output.
Functions, types, and methods introduced as part of Go 1 are not
annotated, as their presence at that version is implied.

This change does not address constants or variables, and completely
ignores the syscall package. The former are future work, the latter is
likely an exercise in futility. In all cases, this is because the story
around displaying the version information is not well developed.

Fixes golang/go#5778

Change-Id: Ieb3cc0da7b18e195bc9c443f14fd8a82e8b2bbf8
Reviewed-on: https://go-review.googlesource.com/85396
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Devon O'Dell <dhobsd@google.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FeatureRequest FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests