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
_______________________________________________
PySide mailing list
[email protected]
http://lists.qt-project.org/mailman/listinfo/pyside
