-
Notifications
You must be signed in to change notification settings - Fork 17.6k
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: enable links to fields of structs #16753
Comments
/cc @odeke-em too |
The |
Yes. Perhaps. There is also #16728 open for a very similar case. |
Since you didn't mention it, are you aware of the existing related behavior of godoc.org (gddo project)? https://godoc.org/net/http#Request.Cancel This looks like a request to backport that, plus tweaks to where on the page the anchors position you. |
That's a very good question and one I've been pondering about for some months now. I'd love to know some insight on that from anyone familiar, but it might be outside of scope of this issue. |
Is anyone already working on this issue/feat? |
Nobody has said so here. Feel free to work on it. |
Hi @luigi-riefolo. I looked into this briefly last week, but have no
Hope this is helpful. |
Hi @appleby, thank you for the info, very useful! Have a look at I'll have a look at x/tools/godoc/linkify.go and identify a strategy to automatically add the id. Please let me know if you guys have any comments or questions. |
If you've figured out a way to add the id to the comment span, you should probably just go that route and ignore what I said about LinkifyText. LinkifyText is currently only responsible for adding links that anchor directly to an identifier. For example, when you link to https://golang.org/pkg/net/http/#ErrContentLength, it's anchored at the identifier, not the associated comment block. I agree that adding the anchor at the top of the comment block is nicer from the user's perspective, but it wasn't clear to me how to get the context required to generate the id at the time the comments are rendered. One problem with the approach of adding an
In a case like this, if you go the route of adding an Another edge-case to keep in mind is fields without an associated doc comment. For example, see the first few fields of the godoc.Presentation struct. |
@appleby great examples. I'll keep them in mind. |
Here's the proposal only for the adding bookmarks to IDENTs (i.e. structs, vars, etc.):
Here's its signature:
If there isn't a comment block above the IDENT, or the comment is on the right-side of the IDENT, then the IDENT line number is used as key.
each time a token is processed a call to: Here's a test page: Try:
Note: the test page has each main comment above the its relative node as pointed in #16728. To achieve this changes have been made in
Each Please let me know if I need to file a formal proposal or this is sufficient. |
That page had a I've uploaded it here for easier viewing: http://instantshare.virtivia.com:27080/1h5htyea6hnw4.html I've only looked briefly, but what I can see so far, this looks very reasonable to me. |
This is my latest test page before uploading the code for review. Please have a look at some of these examples:
and let me know if I missed something or there's any error. Thanks. |
I don't see any issues. At first I thought It's not needed for structs, because you can't do: type Some struct {
io.Reader
foo.Reader
}
// Build error: duplicate field Reader However, it's valid for interfaces, as long as the embedded interfaces contain non-repeating methods. So, this is possible: type Some interface {
io.Reader
foo.Reader
}
// No build error (as long as there are no duplicate methods in those 2 interfaces) So, unfortunately, it seems that it's needed to keep the package name |
I also noticed a minor thing about the #File example. In the current docs, both the package and the type are linked separately. For example, the io.Reader in
"io" links to pkg io and "Reader" links to io.Reader. https://golang.org/pkg/net/http/#File In your example, the link to the package has been dropped, though honestly I'm not sure how useful it is to have that link to the package when you most likely to want to go straight to io.Reader anyway... The case of nested structs is something I considered when I looked into this as well. My conclusion was that I would punt and only add links for the first-level fields of a named type. My reasoning was that nested structs are probably rare (didn't verify this), and you can get into nasty edge cases (admittedly contrived) like the following:
Would X in the above example get labeled as both Nested.Nest1.X and Nested.Nest2.X? What about (god forbid):
How is X labeled in this case? To be clear, I'm not advocating that you actually need to handle such unlikely cases. Just throwing it out there for consideration. |
Thinking about this a bit more, I guess you can safely ignore my nested structs examples from my last comment. The point I was trying to make was that nested struct fields don't really have a canonical name and therefore it might not make sense to link to them, but I guess there is no real problem with a field having multiple ways to link to it. Especially since you are unlikely to encounter multiple levels of nesting in any real example. |
@appleby, @shurcooL thank you for the feedback, it was very helpful.
That's because I did not import all the requested packages in my source example. In this case the In this new test page, a struct or interface like:
will have two bookmarks respectively for We limit the nesting up to 2 levels, as higher levels would be a very bad practice, thus the struct:
will only have bookmarks up to Please let me know what you think or if you want to make any changes. |
For what it's worth, the latest test page LGTM. However, I am not a maintainer and not someone you need to convince. Sorry if that was not clear from my previous comments. Nice work getting the links to point to the associated comment blocks. Seems like a usability win for const/var declarations as well. |
I guess the decision here is whether to the godoc changes in the file mock are OK? That's probably up to @alandonovan or @griesemer. |
In @luigi-riefolo's file mock from Sep 25, the empty spans with ids preceding each struct field doc comment look good to me. However, the page seems to lack all the functions and methods of the HTTP package. Were these removed for expedience? |
@alandonovan that is just a test page that includes non-existing data structures and part of the HTTP Request. I've tried to include as many examples as possible. Let me know if you have any additional ones. |
Thanks Luigi. All of the fragment IDs look good, with the following exception. I disagree with Dmitri about the need for links such as #File.io.Closer. Despite their similar syntaxes, there's a crucial difference between embedding in structs and in interfaces. In a struct, an embedded field |
Thank you Alan for the feedback. If you have any additional comments/questions, then please let me know. Note: the code for bookmarking IDENTs is ready and I'm just polishing it for the peer review, but I need some more time as I'm very busy job hunting. |
I agree with what Alan said above. That rationale is very good.
My comment was not about the need for that link, it was about the need for |
CL https://golang.org/cl/32153 mentions this issue. |
CL https://golang.org/cl/32154 mentions this issue. |
I've just committed the changes (5 mod files, 1 new file) and don't why got two different revision number 32153 and 32154. Does anyone know why?
Any ideas? |
CL https://golang.org/cl/33690 mentions this issue. |
CL https://golang.org/cl/33755 mentions this issue. |
Now without regexps and allocations. And also match comments like: // Foo, if non-nil, ... The comma confused the old pattern. Updates golang/go#16753 Change-Id: I9016ee7b5933ea343950a39989952804c74a598b Reviewed-on: https://go-review.googlesource.com/33755 Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Chris Broadfoot <cbro@golang.org>
This adds <span id="StructName.FieldName"> elements around field names, starting at the comment if present, so people can link to /pkg/somepkg/#SomeStruct.SomeField. Fixes golang/go#16753 Change-Id: I4a8b30605d18e9e33e3d42f273a95067ac491438 Reviewed-on: https://go-review.googlesource.com/33690 Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Robert Griesemer <gri@golang.org>
I would like to be able to link to:
https://golang.org/pkg/net/http/#Request.Cancel
And have the link go to the top of the comment immediately before the "Cancel" field in the Request struct.
Similarly, I would like to link the English docs at the bottom of Transport, after the fields:
https://golang.org/pkg/net/http/#Transport.doc
And have it go to...
"Transport is an implementation of RoundTripper ..."
Currently my only alternative links for both are quite some distance from the text I'd like people to read.
/cc @broady @adg @shurcooL
The text was updated successfully, but these errors were encountered: