(out) (allow-none) is meant to capture the common idiom of

"pass a location to write foo, or %NULL if you are not interested in foo"

at least, that is how it is used throughout GLib and GTK

exactly.

I think it would be a lot more consistent if it meant "this out parameter may return NULL".

Either we should have a special tag for "we can ignore this out parameter" or we should mandate that all out parameters are able to have NULL passed to them to ignore them.

My issue is that (allow-none) is a rather high-level concept whereas passing C NULL pointer to a function is a rather low-level concept.  The two are not really related in this case.

I don't know. We also use allow-none for in parameters, so it is not as if it was a one-direction-only thing.

In any case, I don't buy the high vs low thing. Introspection needs to describe interfaces in enough detail to allow binding them, regardless how high or low the information is.

Wrt to your 'mandate' proposal: When I started working on introspection ages ago, the idea was to support only 'bindable' apis, but since then a lot of complication has been added to make introspection describe apis as-is, bindable or not. So, I don't know if we want to start mandating bindability requirements now...

It means the former.  Introspection has no annotation right now for NULL return values.  If we did, it'd probably be (nullable) or something.

Actually I'd like (out) to imply (allow-none) to make this more obvious.

*** Bug 584528 has been marked as a duplicate of this bug. ***

To create bindings where optional values have a different type to non-optional values, it is essential to know whether an exported out value can be null.  Here are my thoughts...

The issue extends to inout parameters.  There are two concepts here for out and inout parameters:
 A. whether a parameter is optional (may be no value imported or exported)
 B. whether an imported or exported value is null
(allow-none) currently gives A.

As mentioned e.g. (nullable) could give B for an out parameter.  Other ideas for names are (allow-null) or perhaps (not-null) to specify the opposite.  I'll stick with (nullable) for now.

For an inout parameter, there are two values: the in value and the out value.  For a general capability, an inout would need separate annotations e.g. (nullable-in) and (nullable-out), possibly (nullable) implying both.

I'm not sure that it makes sense for (inout) to imply (allow-none), even though it does for (out).

For in parameters, A and B are the same.  To me, it seems more natural to use the annotation for B for to capture nullability of in parameters, i.e. (nullable) rather than (allow-none) - different from what is currently done.

The A/B distinction is already made in GIRepository:
  gboolean g_arg_info_is_optional (GIArgInfo *info);
  gboolean g_arg_info_may_be_null (GIArgInfo *info);
However, for an out parameter (inout too?), may_be_null is providing what I would expect from is_optional - presumably there is some confusion in the interpretation of the GIR data?

I think this bug goes hand-in-hand with bug 660879.  The mechanism used to output a value (return value or exported out value) shouldn't affect whether we know whether the value can be null.  Consider gtk_icon_view_get_item_at_pos and gtk_icon_view_get_path_at_pos - they both output the same path but via different mechanisms.  It would seem inconsistent if we knew that the path could be null in one case only.  Also, nullability of return values should probably use the same annotation as for B.

Finally, what do (nullable) annotations mean for out values for functions that can raise an error?  It would make sense if the annotation applies only when an error is not raised, i.e. an annotation could indicate a non-null out value despite null occurring when an error is raised.  (For return values, presumably there is no such question as functions that can raise errors always return a success flag...?)

*** This bug has been marked as a duplicate of bug 660879 ***

[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]