GNOME Bugzilla – Bug 622294
More annotations for GVariant
Last modified: 2010-06-29 17:39:03 UTC
I've gone over all functions and added 'allow-none', 'array length', 'out' and 'default' annotations where needed. I can't guarantee I've not missed a few things, though. The 'default' annotation is not yet used, but it's still good to have. I've put '(default NULL)' where optional parameters are used e.g. to limit the size of a string which is expected to be NULL-terminated if the param is omitted. For size parameters, I've not added it since bindings know what it's used to, and can decide to skip it if they want. I'm not familiar with how bindings work, so I may have done silly things!
Created attachment 164224 [details] [review] More annotations for GVariant This adds annotations to all functions in gvariant.c. A few docs were also fixed (wrong parameter names, missing mention that NULL is allowed).
Looks good to me.
/** * g_variant_print_string: * @value: a #GVariant - * @string: a #GString, or %NULL + * @string: (out) (allow-none) (default NULL): a #GString, or %NULL That doesn't seem correct. @string is an (in) param, not (out). This function however does return @string if it was non-NULL, and otherwise a _new_ #GString. I don't think a construct like that can currently be expressed as an annotation on Return: ... ?
Indeed, yes. Anyway I don't think it can be fully used by bindings without manual tweaking. So just removing the (out) should be enough - it's hard to explain that if @string wasn't NULL, then the return value shouldn't be freed (twice).
My perspective is that GVariant should be bound manually. This doesn't mean that the annotations shouldn't be added - I find them useful also for C authors instead of the extremely verbose boilerplate English equivalents of e.g. (transfer full).
Pushed with a fix to the print_string() @string param, and a missing (default NULL) annotation for the get_string() @string param. Commit ab6b6c6.