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
go/doc: comments dropped from interior of interface definition #10858
Comments
go/doc doesn't capture this information, so it's not easy to present. Should be easier when the new go/* packages appear. Assigning to gri and deferring. |
This is an issue of heuristics: How do we know that such interior comments should be collected in the first place? There's probably cases of structs/interfaces that contain such comments which are for internal use only. Should they always be shown? |
If it's an exported type and they precede an exported field/method, then I think yes it is reasonable to collect them. People will adjust. |
There's currently no way to represent/attach blocks of non-contiguous comments (w/o empty lines between them) to fields (which is what go doc, godoc, etc. are relying on for this). At cheap solution would be to make such comments contiguous by "connecting them" via an empty line comment, but that would change the original source in undesirable ways (it would require some nasty context-sensitive hackery in the go/parser). This could be improved upon by allowing ast.Comments to represent empty lines. However, a lot of code makes the assumption that ast.Comment.Text is never empty, so that's probably not an easy change to make. Overall, too late for Go 1.9. Should make this higher priority for Go 1.10. |
Too late for 1.12. To try for 1.13: Collect all comments (even if there's empty lines) preceeding a field/method if inside a struct/interface. That should be easy to do; but we should do it early in the cycle to see what the consequences are. |
Please also consider showing exported interface comments when they are not preceeding any exported method. For example ( // IStorageDriver is the raw interface provided by ZODB storage drivers.
type IStorageDriver interface {
// URL returns URL of how the storage was opened
URL() string
// Close closes storage
Close() error
// LastTid returns the id of the last committed transaction.
//
// If no transactions have been committed yet, LastTid returns 0.
LastTid(ctx context.Context) (Tid, error)
Loader
Iterator
**
// A storage driver also delivers database change events to watchq
// channel, which is passed to it when the driver is created.
**
} Thanks beforehand, |
Looking into this. This seems to work if I change param to // consume successor comments, if any
endline = -1
for p.tok == token.COMMENT {
comment, endline = p.consumeCommentGroup(2)
} This changes the no. of lines to skip while looking for the next comment line. But to add additional logic to check if the parser is currently inside a struct/interface, we need to add additional state inside the parser. Or do we want to pass this through params (may be cumbersome ?). |
I have a CL which takes the approach of an additional field inside the parser struct. Let's discuss further on the CL. |
Change https://golang.org/cl/161177 mentions this issue: |
Change https://golang.org/cl/185040 mentions this issue: |
This reverts commit https://golang.org/cl/161177/. Reason for revert: this led to non-contiguous comments spaced by an empty line to be grouped into a single CommentGroup Fixes #32944 Updates #10858 Change-Id: I5e16663b308c3b560496da8e66c33befdf9ed9dd Reviewed-on: https://go-review.googlesource.com/c/go/+/185040 Reviewed-by: Robert Griesemer <gri@golang.org>
Re-opened since we decided to revert https://golang.org/cl/161177. |
This comment has been minimized.
This comment has been minimized.
It is different. I think this is happening because |
The go doc output is missing some important comments from the definition of reflect.Type (so is godoc, but maybe go doc can do better). I've added the missing comments, bracketed by **, below. It's dropping anything that doesn't immediately precede a method definition.
The text was updated successfully, but these errors were encountered: