GNOME Bugzilla – Bug 787812
Annotation Documentation for gchar* incorrect
Last modified: 2017-09-18 12:33:53 UTC
Created attachment 359954 [details] Example to reproduce the issue. The documentation indicates that the default annotations for gchar* should be (type utf8) (transfer full) (see https://wiki.gnome.org/Projects/GObjectIntrospection/Annotations). However, in practice, it appears that they are actually annotated (type utf8) (transfer none). Attached is a modified version of the tutorial code with function parameters that are gchar* and char*, but receive annotations of (type utf8) (transfer none). I don't know whether (transfer none) might actually be the right thing to do in many cases, but if it is now the default, the documentation should reflect this.
The default annotation of `(type utf8) (transfer full)` for `char*` is for return types. For out and in-out arguments, the default annotation is `(transfer full)`, unless marked as `(caller-allocates)`, in which case you get a `(transfer none)`. In your example, the API uses a `char*` as an in-argument to a function, which means that the default transfer rule is `none`. I'll amend the documentation.
The wiki page now reads: ``` Default Annotations: To avoid having the developers annotate everything the introspection framework is providing sane default annotation values for a couple of situations: * (in) parameters: (transfer none) * (inout) and (out) parameters: (transfer full) * if (caller allocates) is set: (transfer none) * gchar* means (type utf8) * return values: (transfer full) * gchar* means (type utf8) (transfer full) * const gchar* means (type utf8) (transfer none) * GObject* defaults to (transfer full) ``` The confusion was mostly due to the fact that the last three items in the list were supposed to refer to the "return values" item, but the indentation to create a sub-list was missing.