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/cmd/godoc: show which version of Go introduced symbols #5778

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

Comments

Projects
None yet
@ncw
Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor Author

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

This comment has been minimized.

Copy link
Contributor

commented Jun 25, 2013

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

This comment has been minimized.

Copy link
Contributor

commented Jul 2, 2013

Comment 4:

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

This comment has been minimized.

Copy link
Contributor

commented Jul 30, 2013

Comment 5:

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

@rsc

This comment has been minimized.

Copy link
Contributor

commented Sep 10, 2013

Comment 6:

Labels changed: added documentation.

@rsc

This comment has been minimized.

Copy link
Contributor

commented Oct 3, 2013

Comment 7:

Probably too big for now.

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

@rsc

This comment has been minimized.

Copy link
Contributor

commented Dec 4, 2013

Comment 8:

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

@rsc

This comment has been minimized.

Copy link
Contributor

commented Dec 4, 2013

Comment 9:

Labels changed: added repo-main.

@rsc

This comment has been minimized.

Copy link
Contributor

commented May 19, 2014

Comment 10:

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

@pierrre

This comment has been minimized.

Copy link

commented Jun 6, 2014

Comment 11:

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

This comment has been minimized.

Copy link
Contributor

commented Aug 4, 2014

Comment 12:

Issue #8468 has been merged into this issue.

@arvenil

This comment has been minimized.

Copy link

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 ;)

@kostya-sh

This comment has been minimized.

Copy link
Contributor

commented Apr 7, 2016

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

This comment has been minimized.

Copy link
Member

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

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link
Member

commented Apr 8, 2016

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

@bradfitz bradfitz modified the milestones: Go1.9Maybe, Unplanned Dec 16, 2016

@bradfitz

This comment has been minimized.

Copy link
Member

commented Dec 16, 2016

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

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Member

commented Dec 20, 2017

@bradfitz

This comment has been minimized.

Copy link
Member

commented Dec 20, 2017

@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

This comment has been minimized.

Copy link
Contributor

commented Dec 20, 2017

Sounds great; thanks, Brad!

@gopherbot

This comment has been minimized.

Copy link

commented Dec 22, 2017

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

@gopherbot

This comment has been minimized.

Copy link

commented Dec 23, 2017

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

@dhobsd

This comment has been minimized.

Copy link
Contributor

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

This comment has been minimized.

Copy link
Contributor

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.

@gopherbot

This comment has been minimized.

Copy link

commented Jul 17, 2018

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

godoc: add version info for struct fields
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

This comment has been minimized.

Copy link

commented Oct 4, 2018

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

cmd/godoc: add version info for golang.org
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

This comment has been minimized.

Copy link

commented Nov 20, 2018

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

[release-branch.go1.11] cmd/godoc: add version info for golang.org
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.