A mechanism for supplementing inherited interface documentation

That all sounds perfectly possible, although I expect some things will come out looking a little odd. I'll try to have a play and see what it looks like.

So I've cobbled something together at http://michael.hudsondoyle.geek.nz/api/cii/ and in the linked branch. Take a look? There definitely needs to be a heuristic to avoid showing "too similar" docstrings together, not sure if the one you propose is the right one but it's better than none at all, that's for sure :)

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.

Richard Wall <email address hidden> writes:

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

This reminds me that pydoctor should check the documented parameters
against the parameters the the function takes...

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

That should be fairly easily doable, and the failure modes are
significantly less offensive than my current branch.

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

No, that wasn't me, but it's not a bad idea :-)

Cheers,
mwh

Michael Hudson-Doyle <email address hidden> writes:

>> Or didn't you suggest doing something with DHTML -- eg tabs to show the
>> implementation and the interface documentation. That might be nice.
>
> No, that wasn't me, but it's not a bad idea :-)

I had a very very quick hack at this:

http://michael.hudsondoyle.geek.nz/api/id2/twisted.python.zippath.ZipPath.html#child

Comments welcome! I think this could possibly be made into something decent.