[PySide] Automatic docstring generation

[John Cummings]

All,

Those following this list may have noticed emails from Yann Lanthony and myself 
regarding docstring support. Unless I have missed something in my review of 
Shiboken, it does not insert any docstrings into the generated bindings. 
Unfortunately, this means, for instance, that in a python shell typing 
"help(PySide.QtGui.QCheckbox.setChecked)" yields something useless like:

    Help on method_descriptor:

    setChecked(...)

That compares with PyQt with the semi-useful:

    Help on built-in function setChecked:

    setChecked(...)
         QAbstractButton.setChecked(bool)

It would be ideal to have it simply use the existing qtdoc format documentation. 
As such, I have looked through the code and identified how to add a docstring to 
a method. In fact, I hacked in the use of a DocParser to retrieve the 
documentation in a manner similar to QtDocGenerator. Basically, I have a proof 
of concept and can confirm Hugo's assertion that it would be easy to add.

So, why this email to the list? My approach is brittle and copies code. The 
functionality I want is in the QtDocGenerator class but hidden beneath some 
protected and private members. The question is, what would be the best approach? 
I see a few possibilities and I am open for suggestions:

1. Use the QtDocGenerator more or less as is since it already modifies the 
documentation value for each class when it calls DocParser::fillDocumentation(), 
which sets the documentation for the meta-class object. You would then just need 
to add a QtDocGenerator on the front of the list of generators in 
generator/main.cpp. This approach seems short-sighted and error prone in the 
long run.

2. Abstract the documentation functionality for methods, classes, enums, etc. 
out of QtDocGenerator and then make the existing QtDocGenerator as well as the 
CppGenerator users of the new class. The DocParser class is great but 
QtDocGenerator adds some decent default docstrings for those items that are not 
documented with qtdoc or doxygen. I like this approach the best.

3. Add yet another generator. In theory, I suppose you could write code to set 
the appropriate value in the Python structs. It sure seems easier to me to 
modify the CppGenerator and insert the documentation when you initialize the 
Python structs.

4. A callback system. That is, when the CppGenerator needs a docstring for a 
method, class, module, etc. it would ask the callback for it. This approach 
could be used in concert with number 2 above.

5. A visitor pattern. It appears that the the API extractor has a visitor 
pattern built into it. Perhaps we could create visitors that populated the 
documentation. I've explored this option the least.

I have a need for this docstring functionality, so I am motivated to get it done 
quickly. I'd appreciate feedback from the list as to the best approach.

As far as actually coding it, should I do work locally and then submit for 
review via Gerrit? Is a public git clone on gitorious the appropriate avenue for 
exploring these option? Do I need to submit a feature request? Am I getting 
ahead of myself?

Sorry for the long email
John Cummings
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/pyside/attachments/20120606/ee8b781b/attachment.html>