search

golang / go

The Go programming language
https://go.dev
BSD 3-Clause "New" or "Revised" License
123.85k stars 17.65k forks source link

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

Closed gertcuykens closed 6 years ago

gertcuykens commented 6 years ago

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

dsnet commented 6 years ago

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

jimmyfrasche commented 6 years ago

Would #20131 help?

gertcuykens commented 6 years ago

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 commented 6 years ago

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

rsc commented 6 years ago

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 https://github.com/golang/go/issues/18342#issuecomment-333658778, let's keep focusing on that as the answer and leave the index an index.