gobject-introspection should have some notion of when a function like so:


gboolean foo_do_stuff (Foo          *self,
                       const gchar *stuff,
                       GError      **error);

is written in the "correct" way, ie:

 - if returns TRUE, error is never set
 - if returns FALSE, error is always set

Languages like Vala and Python would see this function as a function that always returns TRUE, unless an exception occurred, in which case you would never see the return value.  It's clear that it's more appropriate to bind that as a void return value.

An even better example:

gboolean foo_do_some_stuff (Foo          *self,
                            const gchar  *stuff,
                            gint         *amount_of_stuff_done,  /* out */
                            GError      **error);

In this case, it would be far better for the lone out parameter to be the return value than to have a tuple returned.



Deciding when to apply this new feature will not be easy.  There are all kinds of functions that would seemingly be a good fit for this, right off the bat, but it's all kinds of API-incompatibility, so we can't just turn it on.

I suggest we add two new annotations:

 - (broken gerror): for functions where the return value does not indicate
   the setting of the GError output (like GKeyFile functions)

 - (version 2): for functions where we want to always have the new version
   of the way of handling these functions (because the function with this
   tag was added after this functionality was available so there is no
   API compatibility concern)

Note: (version 2) (broken gerror), combined, would still do nothing special.  ie: in this case, the existence of (broken gerror) causes (version 2) to mean nothing.  We may have other things that we want to do for (version 2), though...

Then, we could have an API on gobject-introspection itself:

  GLib.Introspection.set_version (2);

that, if someone calls it from their program, all functions implicitly get treated as if they were tagged (version 2).  This way you could opt-in to the new nicer binding, even for older functions.


Instead of version '2' we may want to base it on GLib stable API version numbers, so that each minor cycle (2.38, 2.40, 2.42, ...) is a chance to introduce some new changes to how gobject-introspection works.