[gobject-introspection] How to use caller-allocates and allow-none annotations in Clutter

[Kouhei Sutou <kou cozmixng org>]

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