gtk-doc introspection annotations to support optional types

[Phil Clayton <phil clayton lineone net>]

I am working on GTK bindings for Standard ML (really) and, as any 
self-respecting functional programmer would, trying to ensure that 
conceptually optional values have option types.  (Then type checking 
prevents an optional value being erroneously treated as a non-optional 
value.)  This requires us to know where optional values can occur.

For reasons given in
https://bugzilla.gnome.org/show_bug.cgi?id=626395
https://bugzilla.gnome.org/show_bug.cgi?id=660879
annotations don't capture whether a return value or exported (out) 
parameter value can be null, so it isn't possible to determine 
automatically when an option type should be used for a scalar value.

I seem to recall reading recently that there was some plan to stabilize 
the annotations.  It would be nice to get all the 'nullability' 
information in there before the annotations interface becomes hard to 
change.

One further consideration is whether nullability annotations should be 
extended to lists and other conceptually non-scalar types?  (A separate 
type for non-empty lists can have similar benefits.)

Phil