search

twisted / pydoctor

This is pydoctor, an API documentation generator that works by static analysis.
https://pydoctor.readthedocs.io
Other
185 stars 49 forks source link

A mechanism for supplementing inherited interface documentation #64

Open mwhudson opened 9 years ago

mwhudson commented 9 years ago

It is often useful to document the unique features of an interface implementation eg

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.

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 --- Imported from Launchpad using lp2gh. - date created: 2013-09-10T08:11:37Z - owner: richardw - the launchpad url was https://bugs.launchpad.net/bugs/1223227
mwhudson commented 9 years ago

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

mwhudson commented 9 years ago

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

mwhudson commented 9 years ago

(by 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

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:

ZipPath.child looks better. Here the source code only contains an explanatory note which has been merged with the documentation from IFilePath

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.

mwhudson commented 9 years ago

(by mwhudson) Richard Wall

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

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

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

mwhudson commented 9 years ago

(by mwhudson) Michael Hudson-Doyle

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.