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 interface methods more prominently #5860

Open
gopherbot opened this Issue Jul 10, 2013 · 22 comments

Comments

Projects
None yet
8 participants
@gopherbot

gopherbot commented Jul 10, 2013

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

This comment has been minimized.

Contributor

rsc commented Jul 25, 2013

Comment 1:

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

Status changed to Accepted.

@rsc

This comment has been minimized.

Contributor

rsc commented Jul 30, 2013

Comment 2:

Labels changed: added feature.

@robpike

This comment has been minimized.

Contributor

robpike commented Aug 29, 2013

Comment 3:

Not for 1.2.
@robpike

This comment has been minimized.

Contributor

robpike commented Aug 29, 2013

Comment 4:

Not for 1.2.
@robpike

This comment has been minimized.

Contributor

robpike commented Aug 29, 2013

Comment 5:

Not for 1.2.
@robpike

This comment has been minimized.

Contributor

robpike commented Aug 29, 2013

Comment 6:

Labels changed: removed go1.2maybe.

@gopherbot

This comment has been minimized.

gopherbot commented Sep 6, 2013

Comment 7 by dtcaciuc:

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

This comment has been minimized.

Contributor

rsc commented Nov 27, 2013

Comment 8:

Labels changed: added go1.3maybe.

@rsc

This comment has been minimized.

Contributor

rsc commented Nov 27, 2013

Comment 9:

Labels changed: removed feature.

@rsc

This comment has been minimized.

Contributor

rsc commented Dec 4, 2013

Comment 10:

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

@rsc

This comment has been minimized.

Contributor

rsc commented Dec 4, 2013

Comment 11:

Labels changed: added repo-tools.

@rsc

This comment has been minimized.

Contributor

rsc commented Mar 5, 2014

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

This comment has been minimized.

gopherbot commented Apr 9, 2014

Comment 13:

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

This comment has been minimized.

gopherbot commented Apr 9, 2014

Comment 14:

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

This comment has been minimized.

Member

jimmyfrasche commented Apr 19, 2014

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

This comment has been minimized.

gopherbot commented Jul 10, 2014

Comment 16 by samsalisbury:

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

This comment has been minimized.

gopherbot commented Jul 11, 2014

Comment 17 by thomas.bruyelle:

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

@rsc rsc added this to the Unplanned milestone Apr 10, 2015

@rsc rsc changed the title from cmd/godoc: show interface methods more prominently to x/tools/cmd/godoc: show interface methods more prominently Apr 14, 2015

@rsc rsc removed the repo-tools label Apr 14, 2015

@icedream

This comment has been minimized.

icedream commented Jun 26, 2016

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

This comment has been minimized.

Contributor

ianlancetaylor commented Jun 26, 2016

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

@savinov

This comment has been minimized.

savinov commented Sep 5, 2016

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

This comment has been minimized.

gopherbot commented Nov 14, 2017

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

@DusanKasan

This comment has been minimized.

DusanKasan commented Nov 15, 2017

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

See comments/description there for details.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment