Comment 4 for bug 1223227

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