proposal: godoc: distinguish type interfaces from other types

[gertcuykens]

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]

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]

Would #20131 help?

[gertcuykens]

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

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]

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

[rsc]

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.