Open gopherbot opened 11 years ago
Relevant CL at https://golang.org/cl/12723043/ pending further discussion after 1.2 release.
CL https://golang.org/cl/12723043 references this issue.
CL https://golang.org/cl/12723043 references this issue.
This would be a good change. Currently you can do this: type hiddenInterface interface { A() } type Interface interface { hiddenInterface B() } and godoc hides the fact that A is a required method while the equivalent for structs: type hiddenStruct struct{} func (h hiddenStruct) A() {} type Struct struct { hiddenStruct } func (s Struct) B() {} will show that s has methods A and B. Given type Interface interface { //A long docstring A() } I'd like to see something like the below in godoc: type Interface interface { A() } func (Interface) A() A long docstring
I would like to ask what's the progress on this issue since apparently the current state requires deciding between good code practices and proper documentation.
I don't think anybody is currently working on this.
Moreover: every interface method implementation has to duplicate almost same docs. IMHO, a method docs should be placed in interface, implementations should comment only specific details about some method and contain a link to the interface method docs to get the main method idea. In Java it works this way and that's very useful for both: developer and user. stdlib contains an example of this idea, but godoc doesn't handle it: https://golang.org/pkg/crypto/cipher/#AEAD
Change https://golang.org/cl/77750 mentions this issue: godoc: show interface method documentation
I submitted a patch for this at https://go-review.googlesource.com/c/go/+/77750
See comments/description there for details.
I just noticed this same thing. I got bitten by this looking at the pkg/reflect docs:
https://golang.org/pkg/reflect/
From reading the Index, you could reasonably infer that there's a Method
method on type.Value, but that there isn't one on type.Type. In fact, there is, but because it's an interface method rather than a concrete type method, it doesn't get shown in the index.
Would the godoc authors like to see this behavior? @DusanKasan's patch seems to resolve the issue, though I haven't reviewed the code myself.
It is 2021. This seems like a huge miss in godoc. Hoping to see an update
FYI, Golds (https://github.com/go101/golds) shows them all.
The patch above has been ignored for 4 years and already has merge conflicts. Would it make sense to close the PR and open a new one with the same changes, to draw some attention to it? That would be a great and much-needed feature. It's not clear to me why interfaces aren't parsed when structs are. What's the difference? Both have methods with signatures and documentation.
godoc is now legacy code, repurposing this to pkgsite.
CC @golang/pkgsite
If I understand correctly, the patch above should work for both. Both godoc and pkdsite should use the same go/doc package. Also, I think it fits 1.19 very well since it brings some major changes to the package (lists, headings, and other almost-markdown syntax).
As a new user of Go, I was surprised that I was unable to find the Context.Err
method in the documentation. I knew it existed as the Cause
function referred to it, but I could not understand why it was not in the table of contents:
It is not intuitive that I should have then gone to each type definition to read the code block to find, what arguably is, the most important documentation of the package.
Example: https://pkg.go.dev/crypto/cipher#AEAD
I have stuck into this with my WIP library where I have an interface with 5-6 methods and I actually have to be very explicit about the context methods are meant to be used within. This is a shame users can't see nice splitted per-method doc and need to read source code instead.
by szopa@google.com: