x/tools/cmd/godoc: show which version of Go introduced symbols
ncw opened this issue · 34 comments
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
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.
In Android doc: http://developer.android.com/reference/packages.html you can filter by API level.
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?
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? :)
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:
-
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?
-
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.
Fchflagsis not present in godoc). I remember from past work on FreeBSD syscalls that things likeNanosleepwere 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. -
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? -
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