Comment 3 for bug 1223227

Sorry for not responding sooner.

Annoyingly, my original twistedchecker comment describing the problem and the
IRC conversation has disappeared since I cancelled the merge request.

So I can't actually remember which interface and implementation I was thinking
about when I raised this ticket.

Maybe it was IFilePath.

FilePath.child doesn't look good -- like you said in your comment, there
are now two sets of very similar documentation in this case
 * http://michael.hudsondoyle.geek.nz/api/cii/twisted.python.filepath.FilePath.html#child

It does highlight that the implementation and interface have different argument
names. One of the Twisted dev tools should warn about that. I created a
twistedchecker ticket:
 * https://bugs.launchpad.net/twistedchecker/+bug/1242341

ZipPath.child looks better. Here the source code only contains an explanatory
note which has been merged with the documentation from IFilePath
 * http://michael.hudsondoyle.geek.nz/api/cii/twisted.python.zippath.ZipPath.html#child
 * https://twistedmatrix.com/trac/browser/trunk/twisted/python/zippath.py#L84

So maybe pydoctor should only try and fill in missing parameter, return and
raises documentation. That might be a good start.

Or didn't you suggest doing something with DHTML -- eg tabs to show the
implementation and the interface documentation. That might be nice.