GNOME Bugzilla – Bug 69243
doc strings
Last modified: 2008-07-16 10:12:30 UTC
code generator should do doc strings for functions, methods and maybe even classes. This makes the builtin help() system in python useful. Skip provided a patch to do this a while back (that produced simple doc strings listing the argument names and return type), but it may need reworking for current versions. We could probably create a special descriptor for GObject.__doc__ that would expand to some class documentation, possibly including inheritance, signal docs and property docs. This would make help('classname') particularly useful. (maybe this second bit should be a separate bug?)
Hmm. Looks like setting __doc__ in the type's __dict__ doesn't do anything. Getting class.__doc__ goes through the type.__doc__ property which looks in tp_doc only. Getting instance.__doc__ works fine though, going through the descriptor. Maybe this should be a python bug?
__doc__ descriptor implemented. __gdoc__ as a synonym (due to problems listed previously). The __doc__ descriptor bug has been reported at: http://sourceforge.net/tracker/index.php?func=detail&aid=507394&group_id=5470&atid=105470
I wrote a patch for python that fixes the above problem at: http://www.daa.com.au/~james/files/type-doc.patch It is appended to this Python bug report on SF: http://sourceforge.net/tracker/index.php?func=detail&aid=504343&group_id=5470&atid=105470 PyGTK has been patched to work with this patch, which means that help('gtk.Widget') will give signal and property documentation!
The PyTypeType __doc__ property patch got committed to both the head and the 2.2 maintenance branch, so the nice doc descriptor feature will work with Python 2.2.1 and 2.3. woo hoo!
Looks like 2.2.1 doesn't handle eg. gtk.Widget.__doc__ correctly. Filed a bug, and a patch has now been applied. So it should be fixed for 2.2.2 and 2.3 :) Still need to look at function doc strings. Wonder if we could use descriptors to load their doc strings from an external source (I don't really feel like loading the complete gtk reference documentation into core on the off chance that someone will use help()). If not possible, simple doc strings giving argument names should be included.
mass reassign of open pygtk and gnome-python bugs.
James, if you plan on working on this, please reassign back to yourself? Thanks.
I think this is fixed already.