(allow-none) is dead. long live (nullable)!

This is a public service announcement.

Writers of introspected libraries have long been familiar with (allow-none) as an annotation on the arguments of functions.

This annotation had a few shortcomings:

• it had a strange name with an implied direction
• it was not supported for return values
• for (out) parameters it does not mean “null may be returned” but rather “you may pass NULL to the C API if you wish to ignore this optional output”; there was no way to say that an (out) parameter may return null
• many people were confused about the last point

As such, (allow-none) is deprecated. We now have two new annotations: (nullable) and (optional).

(nullable) always means “the range of this value includes the possibility of the null value”. This applies for in parameters, out parameters, inout parameters and return values (with plans to expand it to properties and struct fields). For Vala, this translates more or less directly to the ? found in type names.

(optional) always means “it is possible to ignore this optional output by passing NULL“. It is only meaningful for (out) parameters.