x/pkgsite: show interface methods more prominently

[gopherbot]

by szopa@google.com:

Right now, the whole interface has one link, and its code is included in its entirety.
This is not very clear, as many interfaces are the main public entry point for many
libraries. What I would like to see:

1. The index should contain links to interface methods.

2. Interface methods doccomments should be displayed in a way similar to normal
method/function doccomments.

[rsc]

Comment 1:

Labels changed: added priority-later, go1.2maybe, suggested, removed priority-triage.

Status changed to Accepted.

[rsc]

Comment 2:

Labels changed: added feature.

[robpike]

Comment 3:

Not for 1.2.

[robpike]

Comment 4:

Not for 1.2.

[robpike]

Comment 5:

Not for 1.2.

[robpike]

Comment 6:

Labels changed: removed go1.2maybe.

[gopherbot]

Comment 7 by dtcaciuc:

Relevant CL at https://golang.org/cl/12723043/ pending further discussion after
1.2 release.

[rsc]

Comment 8:

Labels changed: added go1.3maybe.

[rsc]

Comment 9:

Labels changed: removed feature.

[rsc]

Comment 10:

Labels changed: added release-none, removed go1.3maybe.

[rsc]

Comment 11:

Labels changed: added repo-tools.

[rsc]

Comment 12:

Brad G, can you please own both this issue and the CL 12723043? It can go into Go 1.3 if
there is a consensus in the next week or so.
Thanks.

Owner changed to bgarcia@golang.org.

[gopherbot]

Comment 13:

CL https://golang.org/cl/12723043 references this issue.

[gopherbot]

Comment 14:

CL https://golang.org/cl/12723043 references this issue.

[jimmyfrasche]

Comment 15:

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

[gopherbot]

Comment 16 by samsalisbury:

I think this would be a great addition to godoc! Have there been any opposition to
implementing this?

[gopherbot]

Comment 17 by thomas.bruyelle:

It's important because every library should expose an interface, in order to facilitate
testing/mocking.

[icedream]

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.

[ianlancetaylor]

I don't think anybody is currently working on this.

[savinov]

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

[gopherbot]

Change https://golang.org/cl/77750 mentions this issue: godoc: show interface method documentation

[DusanKasan]

I submitted a patch for this at https://go-review.googlesource.com/c/go/+/77750

See comments/description there for details.

[seebs]

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.

[gonzojive]

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.

[tredfield]

It is 2021. This seems like a huge miss in godoc. Hoping to see an update

[zigo101]

FYI, Golds (https://github.com/go101/golds) shows them all.

[orsinium]

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.

[ianlancetaylor]

godoc is now legacy code, repurposing this to pkgsite.

CC @golang/pkgsite

[orsinium]

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).

[pkazmier]

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.

[sirkon]

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.