A mechanism for supplementing inherited interface documentation

[Richard Wall]

It is often useful to document the unique features of an interface
implementation eg
 * incompatibilities
 * side effects
 * extra arguments which are not defined in the interface

The current work around is to write implementation specific
documentation and include an @see link to the interface.

But it would be more convenient to be able to view the full interface
documentation directly (including parameter and return type) --
without having to navigate away to the interface API.

How hard would it be to take the implementation docstring and merge it
with the interface docstring.

<implementation docstring body>

<interface docstring body>

<interface epydoc>

<implementation epydoc>

One problem is that there are many cases in Twisted, where the
interface documentation has simply been duplicated (often
inaccurately) in the implementation.

Could we identify such cases by the fact that the implementation
contained epydoc parameter names that match the interface epydoc.

And in this case, discard the implementation docstring in favour of
the interface docstring.

This all stems from the following #twisted-dev conversation about a proposed
change to twistedchecker:
 * https://code.launchpad.net/~richardw/twistedchecker/inherited-interface-documentation-1132540/+merge/150702/comments/419577

[Michael Hudson-Doyle (mwhudson)]

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.

[Michael Hudson-Doyle (mwhudson)]

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 :)

[Richard Wall (richardw)]

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.

[Michael Hudson-Doyle (mwhudson)]

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 (mwhudson)]

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.