Skip to content
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

proposal: godoc: distinguish type interfaces from other types #23256

Closed
gertcuykens opened this issue Dec 27, 2017 · 5 comments
Closed

proposal: godoc: distinguish type interfaces from other types #23256

gertcuykens opened this issue Dec 27, 2017 · 5 comments

Comments

@gertcuykens
Copy link
Contributor

gertcuykens commented Dec 27, 2017

When your package contains lots of interfaces a user will have a hard time figuring out how to use your package based on the generated godoc's index

Example: https://godoc.org/github.com/nats-io/go-nats-streaming

Golang standard library solves this by including examples on each interface but without a example good luck figuring out how to use instances of the interface

Example: https://golang.org/pkg/net/http/#Hijacker

Proposal:

  1. Distinguish interface types from the other types, color, bold, blinking :P, symbols, extra text,... Anything is fine as long it's more clear what types are interfaces and which one are not

  2. Add the interface function declarations in the index so you have a quick hint what the interface instance is suppose to be doing

@gertcuykens gertcuykens changed the title godoc: distinguish type interface from other types godoc: distinguish type interfaces from other types Dec 27, 2017
@dsnet
Copy link
Member

dsnet commented Dec 27, 2017

Rather than more segregation on types based on some heuristics which are valid sometimes and not valid othertimes, perhaps support for user-defined sections is a better approach (#18342)?

(The "hot-linking" feature that is being implemented as part of that issue will help here as well).

@dsnet dsnet changed the title godoc: distinguish type interfaces from other types proposal: godoc: distinguish type interfaces from other types Dec 27, 2017
@gopherbot gopherbot added this to the Proposal milestone Dec 27, 2017
@jimmyfrasche
Copy link
Member

Would #20131 help?

@gertcuykens
Copy link
Contributor Author

Both suggestion would help but I am aiming directly at the index

image
For example a simple comma separated list would be fine by me
...
type Conn: Publish, PublishAsync, Subscribe, QueueSubscribe, Close, NatsConn
....
And in case it refers to a other interface, just the name of the other interface to keep it simple. Later we can maybe hyper link the words to a specific part.

@jimmyfrasche
Copy link
Member

That sounds similar to #5860 as well, though I'm not sure if that included the index.

@rsc
Copy link
Contributor

rsc commented Jan 22, 2018

The struct heading does not list all the fields in the struct.
Why should the interface heading list all the methods in the interface?
The index is an index. Really the answer here is the encourage proper package overviews.

Per #18342 (comment), let's keep focusing on that as the answer and leave the index an index.

@rsc rsc closed this as completed Jan 22, 2018
@golang golang locked and limited conversation to collaborators Jan 22, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

5 participants