implemented interfaces are not shown in subclasses about pydoctor

[mwhudson]

(by glyph)
Just bumped into this again. I think it's quite confusing for users to be tossed into private parts of the hierarchy in order to see what interfaces are available.

[glyph]

@mwhudson @hawkowl FYI: in a couple of recent interactions with users I have noticed that this is definitely the source of a lot of confusion.

[mthuurne]

What would the desired output look like?

Should the documentation page for a class just list all (directly or via inheritance) implemented interfaces in a simple list? For example:

Implements interfaces: IBoxSender, IProtocol, IResponderLocator, IBoxReceiver.

Or should methods be grouped by which interface defines them? And if so, should they be moved there from the implementation class, possibly dropping some implementation classes from the class page altogether if they have 0 methods left after the moves?

For example, the current documentation reads:

Inherited from _DescriptorExchanger (via BinaryBoxProtocol):
Method fileDescriptorReceived: Collect received file descriptors to be claimed later by Descriptor.

But it could be presented like this instead:

From IFileDescriptorReceiver:
Method fileDescriptorReceived: Called when a file descriptor is received over the connection.

As shown here, the implementation docstring is not the same as the interface docstring, so which should be shown?

Also, should there be a mention of where the implementation resides? I imagine that for people using Twisted that doesn't matter much, but for developers or people tracking down a bug it can be useful to have a source link to the implementation.