Hi, I have questions about "out caller-allocates" and "allow-none" annotations of GObject Introspection. I'm sending this e-mail to gtk-devel-list because https://live.gnome.org/GObjectIntrospection introduces this list.
I submitted a bug report to Clutter: "child" of clutter_actor_iter_next() and _prev() misses some GObject Introspection tags https://bugzilla.gnome.org/show_bug.cgi?id=691217 In this bug report, I was suggested that I need to ask GObject Introspection developers about what annotations should be used for clutter_actor_iter_next() [*1]. I hope that GObject Introspection developers answer my question. [*1] http://developer.gnome.org/clutter/stable/ClutterActor.html#clutter-actor-iter-next Here is the clutter_actor_iter_next() signature: gboolean clutter_actor_iter_next (ClutterActorIter *iter, ClutterActor **child); The "child" parameter is the target in the bug report. The function is used like: ClutterActorIter iter; ClutterActor *child; clutter_actor_iter_init (&iter, container); while (clutter_actor_iter_next (&iter, &child)) { /* do something with child */ } There is two questions. (1) The "child" parameter is a return location and the return location is allocated by caller. (The returned object isn't allocated by caller.) What annotation should be used for the case? I thought "out caller-allocates". Is it right usage for the annotation? Or "out" is the right annotation? (2) The "child" parameter can be NULL. What annotation should be used for the case? I thought "allow-none". Is it right usage for the annotation? Can I use "allow-none" for an out parameter? I found a real usage of "out caller-allocate" and "allow-none". It is gtk_text_iter_forward_search(): http://developer.gnome.org/gtk3/stable/GtkTextIter.html#gtk-text-iter-forward-search gboolean gtk_text_iter_forward_search (const GtkTextIter *iter, const gchar *str, GtkTextSearchFlags flags, GtkTextIter *match_start, GtkTextIter *match_end, const GtkTextIter *limit); "out caller-allocate" and "allow-none" are used for match_start and match_end: match_start: return location for start of match, or NULL. [out caller-allocates][allow-none] match_end: return location for end of match, or NULL. [out caller-allocates][allow-none] Is clutter_actor_iter_next() case the same case as gtk_text_iter_forward_search()? Thanks, -- kou _______________________________________________ gtk-devel-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/gtk-devel-list
