GNOME Bugzilla – Bug 697356
Docstrings: List length arguments visible and return values missing
Last modified: 2014-01-01 14:28:16 UTC
>>> from gi.repository import Gtk >>> Gtk.init_check.__doc__ 'init_check(argc:int, argv:list) -> argc:int, argv:list' >>> Gtk.rc_get_module_dir.__doc__ 'rc_get_module_dir()' should be: >>> from pgi.repository import Gtk >>> Gtk.init_check.__doc__ 'init_check(argv: list) -> (bool, argv: list)' >>> Gtk.rc_get_module_dir.__doc__ 'rc_get_module_dir() -> str'
Another nice thing to have (but not strictly necessary for docs creation) would be to include may_return_null and may_be_null: >>> Gtk.foo.__doc__ foo(argv: list or None) >> Gtk.foobar.__doc__ foobar() -> (bool, some_out: Gtk.Widget or None) And if it throws.. but I'm not sure about the syntax there.
..this is what I use now in pgi: accelerator_get_default_mod_mask() -> Gdk.ModifierType accelerator_get_label(accelerator_key: int, accelerator_mods: Gdk.ModifierType) -> str drag_finish(context: Gdk.DragContext, success: bool, del_: bool, time_: int) -> None init(argv: [str] or None) -> argv: [str] init_with_args(argv: [str] or None, parameter_string: str or None, entries: [GLib.OptionEntry], translation_domain: str) raises -> (bool, argv: [str]) rc_get_default_files() -> [str] targets_include_image(targets: [Gdk.Atom], writable: bool) -> bool target_table_new_from_list(list_: Gtk.TargetList) -> [Gtk.TargetEntry]
Array length argument skipping was pushed as: https://git.gnome.org/browse/pygobject/commit/?id=28a178e
Commits which fix this: https://git.gnome.org/browse/pygobject/commit/?id=cebf531 https://git.gnome.org/browse/pygobject/commit/?id=aeccdad https://git.gnome.org/browse/pygobject/commit/?id=826c0e6 (In reply to comment #1) > foobar() -> (bool, some_out: Gtk.Widget or None) I ended up only using may_return_null() because may_be_null() out arguments can give a funny result for functions which accept an optional int pointer, e.g: foobar() -> (bool, some_out:int or None) > And if it throws.. but I'm not sure about the syntax there. I think eventually we should move the syntax to reStructuredText formatting: :Parameters: context (None) : Gdk.DragContext :Raises GLib.GError: When context is invalid. :Returns: True on success
(In reply to comment #4) > Commits which fix this: > https://git.gnome.org/browse/pygobject/commit/?id=cebf531 > https://git.gnome.org/browse/pygobject/commit/?id=aeccdad > https://git.gnome.org/browse/pygobject/commit/?id=826c0e6 Nice! > (In reply to comment #1) > > foobar() -> (bool, some_out: Gtk.Widget or None) > > I ended up only using may_return_null() because may_be_null() out arguments can > give a funny result for functions which accept an optional int pointer, e.g: > foobar() -> (bool, some_out:int or None) I've also limited it to in/inout afair. > > And if it throws.. but I'm not sure about the syntax there. > > I think eventually we should move the syntax to reStructuredText formatting: The rationale behind the annotation like syntax was that it's faster to parse visually with help, ipython etc. and still can be converted to reST if needed.