These were written some time ago. Verify if they are still a problem and if yes provide an example.
may_return_null() is a bit useless because it's in many cases wrong.
As a result documentation can't say if something may return None.
In some cases function docs are more specific about it, but
it would be nice to not have to rely on that.
Maybe default to may-return-null instead and add a new no-return-null
annotation?
There is no may_return_null() equivalent for out arguments for when it
writes NULL to the passed address. There should be one defaulting to may
return null.
Another thing that might be good to add is only-null-on-error.
:meth:Gio.File.read for example only returns NULL on error and with
PyGObject the return value never reaches the user since an exception gets
thrown. So from the user POV it's never NULL. The same applies to out args.
Remove C-isms from the argument docs or mark them as such. Things like
"Returns a NULL-terminated array" / "Free the returned object" might
confuse people and make them think they have to tread the value special
somehow. C examples on the other hand are fine imo. It's obvious that
they are in another language and in the worst case add no useful
information.
Out argument descriptions include info about what can be passed
to the function. In Python we only care what gets written out. Everything
else is confusing (:meth:Gtk.Alignment.get_padding: "location to store
the padding for the top of the widget, or NULL").
Out / InOut should have two descriptions ideally. One for what can be passed in
and one for what gets written out. (See :func:Gtk.init_check
where the description is used two times for argv, but better than
nothing atm..)
There is no way to detect private class structs (afaik),
which are useless for the docs. I currently hide structs if they are
disguised and have no members which works 99% of the time. Any reason why
they are in the gir/typelib at all?
Many libs use the SECTION comment block to describe classes/interfaces
("The "Description" part in devhelp") and g-ir-scanner has special
handling for section comments where ID is equal to the class name
lowercased and replaces the struct description by it.
This is undocumented, so in case class docs for your lib are missing in
the gir, check out the following commit for an example fix:
All the basics are in place, now the most annoying issues are with the docs/annotations themselves.
https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations
These were written some time ago. Verify if they are still a problem and if yes provide an example.
may_return_null()is a bit useless because it's in many cases wrong. As a result documentation can't say if something may return None. In some cases function docs are more specific about it, but it would be nice to not have to rely on that.Maybe default to may-return-null instead and add a new no-return-null annotation?
may_return_null()equivalent for out arguments for when it writes NULL to the passed address. There should be one defaulting to may return null.only-null-on-error. :meth:Gio.File.readfor example only returns NULL on error and with PyGObject the return value never reaches the user since an exception gets thrown. So from the user POV it's never NULL. The same applies to out args.Gtk.Alignment.get_padding: "location to store the padding for the top of the widget, or NULL").Gtk.init_checkwhere the description is used two times forargv, but better than nothing atm..)Many libs use the SECTION comment block to describe classes/interfaces ("The "Description" part in devhelp") and g-ir-scanner has special handling for section comments where ID is equal to the class name lowercased and replaces the struct description by it.
This is undocumented, so in case class docs for your lib are missing in the gir, check out the following commit for an example fix:
http://cgit.freedesktop.org/gstreamer/gst-editing-services/commit/?id=a66e6746493a644cd005f873770ca53525edfc51
Maybe it would be possible to include the section structure + docs in the gir?