GNOME Bugzilla – Bug 681967
Automatically add doc/signatures to introspection generated methods
Last modified: 2012-11-12 07:04:19 UTC
Currently introspection functions and methods do not have documentation or any clues about what parameters they take. This is problematic as it doesn't allow for standard python development work flows. While online introspection based documentation specific to python will be helpful, actual embedded doc strings would be the best, and at minimal argument names should be available dynamically. Currently we can add __doc__ to all methods based off of introspection information currently available. These doc strings should follow the standard signature style for python builtins: "function(a, b) -> list" It seems this would be easy enough by adding a __doc__ attribute to the closures dynamically created in gi/types.py which wrap invoke. As an added bonus in Python 3.3 we can fill out a Signature object as well, see: http://www.python.org/dev/peps/pep-0362/ A minor caveat is the extra arguments flagged as out also need to show up as part of a return value tuple.
Created attachment 226357 [details] [review] Add doc strings showing method signatures for gi methods. This adds signature based doc string to all methods pulled in from introspection. For example: Gtk.SpinButton.get_icon_area.__doc__ get_icon_area(self, icon_pos:Gtk.EntryIconPosition) -> icon_area:cairo.RectangleInt
Some examples from the patch and ipython: In [2]: Gtk.SpinButton.get_icon_area? Type: function String Form:<function Function.<locals>.function at 0x7fe1d34a3050> File: /home/simon/src/gnome3/pygobject/gi/types.py Definition: Gtk.SpinButton.get_icon_area(*args, **kwargs) Docstring: get_icon_area(self, icon_pos:Gtk.EntryIconPosition) -> icon_area:cairo.RectangleInt In [3]: Gtk.Spinner.get_size_request? Type: function String Form:<function Function.<locals>.function at 0x7f916c0b10e0> File: /home/simon/src/gnome3/pygobject/gi/types.py Definition: Gtk.Spinner.get_size_request(*args, **kwargs) Docstring: get_size_request(self) -> width:int, height:int Previously we only had (*args, **kwargs) which isn't very helpful. These doc strings could also be added in a format like reStructuredText.
Created attachment 226393 [details] [review] Add doc strings showing method signatures for gi methods. This adds signature based doc string to all methods pulled in from introspection. For example: Gtk.SpinButton.get_icon_area.__doc__ get_icon_area(self, icon_pos:Gtk.EntryIconPosition) -> icon_area:cairo.RectangleInt
Thanks for working on this! Adding proper docstrings is indeed a great improvement, I've heard quite a lot of complaints about that. In pygi_get_py_type_hint(), shouldn't it return Py_None for GI_TYPE_TAG_VOID, instead of a long? + """Split a functions args into a tuple of two lists: (in_args, out_args) + Note that args marked as DIRECTION_INOUT will be in both lists.""" Please leave a blank line between short and long description. + if direction != DIRECTION_OUT: + in_args.append(arg) + if direction != DIRECTION_IN: + out_args.append(arg) Wouldn't it be clearer to compare against "== DIRECTION_IN", and _OUT in the second case respectively? + """Builds a signature string which can be used for documentation.""" "Build" Could you add a test which actually checks __doc__ from an introspected method (GIMarshallingTests or so) to ensure that this works all the way through, and also add a test case to ensure that this doesn't clobber a manually added docstring from an overridden method? Thanks!
(In reply to comment #4) > + if direction != DIRECTION_OUT: > + in_args.append(arg) > + if direction != DIRECTION_IN: > + out_args.append(arg) > > Wouldn't it be clearer to compare against "== DIRECTION_IN", and _OUT in the > second case respectively? It's written that way to handle the DIRECTION_INOUT case implicitly but that isn't clear. A more readable way is perhaps: if direction in (DIRECITON_OUT, DIRECTION_INOUT): out_args.append(arg) > Could you add a test which actually checks __doc__ from an introspected method > (GIMarshallingTests or so) to ensure that this works all the way through, and > also add a test case to ensure that this doesn't clobber a manually added > docstring from an overridden method? Yes will do. Thanks for reviewing.
Created attachment 228596 [details] [review] Add doc strings showing method signatures for gi methods Fixes based on review.
Comment on attachment 228596 [details] [review] Add doc strings showing method signatures for gi methods Nice, thanks! Assuming this works with 2.7 as well, please go ahead.
Pushed with C warning fixes. Attachment 228596 [details] pushed as 13629f5 - Add doc strings showing method signatures for gi methods