golang/go

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

ncw opened this issue · 34 comments

ncw commented
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 commented

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 commented

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!

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 commented

Comment 4:

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

Comment 5:

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

rsc commented

Comment 6:

Labels changed: added documentation.

rsc commented

Comment 7:

Probably too big for now.

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

rsc commented

Comment 8:

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

rsc commented

Comment 9:

Labels changed: added repo-main.

rsc commented

Comment 10:

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

Comment 11:

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

Comment 12:

Issue #8468 has been merged into this issue.

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

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.

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

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?

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

I'd like to highlight some benefits of having version information in the source code as part of doc comment:

  • none of the tools that display Go documentation need to be updated (I know at least three: godoc, go doc and github.com/zmb3/gogetdoc)
  • the version information is available when browsing the source code
  • a convention that other project might follow can be established (api/*.txt files cannot be used for 3-rd party packages)

The drawback is that the documentation can easily get out of sync. A validation tool that checks documentation against api/*.txt files might help.

@kostya-sh, there are other drawbacks too. It's new maintenance, it's a lot of clutter, etc. I think we're only interested in doing this automatically in godoc, not with manual annotations.

crazy idea: parse api/*.txt and update doc comments in source code, commit, push? :)

adg commented

To expand on Brad's "no," the downside with putting this data in doc comments, automatically or otherwise, is that it's duplicated data that needs to be maintained somehow. That maintenance has a cost.

We're much better off finding a way to do this at the presentation layer, rather than at the doc comment layer.

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

/cc @FiloSottile

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?

@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! 🎅

Sounds great; thanks, Brad!

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

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

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

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.

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

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

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