General GI docs issues

[lazka]

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?

• 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:

  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?