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
Comments
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 |
Given quite a few new functions ( |
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. |
@arvenil, yes, that's what this bug is about. |
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:
|
No need for any special tags. The information is stored in the
api/go1.x.txt files.
…On Wed, Dec 20, 2017, 4:13 PM dhobsd ***@***.***> wrote:
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?
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
<#5778 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/AABhlvQTPWPdCtIKoAt13Yn7l89D4jIxks5tCXhlgaJpZM4Hg0EO>
.
|
@dhobsd, I'd start with anything for now and avoid worrying about corner cases:
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: |
Change https://golang.org/cl/85396 mentions this issue: |
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: |
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>
Change https://golang.org/cl/139557 mentions this issue: |
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>
Change https://golang.org/cl/150683 mentions this issue: |
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
The text was updated successfully, but these errors were encountered: