[gtk/ebassi/for-master: 2/2] Add annotations for GtkBuildable virtual functions

[Emmanuele Bassi <ebassi src gnome org>]

commit c6cedf608a6b1b86cc84bc0d357b3eaa163010dd
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Tue Sep 29 19:48:55 2020 +0100

    Add annotations for GtkBuildable virtual functions
    
    Now that the functions that wrap them have gone away from the public
    API, we need proper annotations for the virtual functions, otherwise
    languages will not have enough information on nullable arguments and
    ownership transfer.

 gtk/gtkbuildable.c |  4 ++--
 gtk/gtkbuildable.h | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 63 insertions(+), 4 deletions(-)
---
diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c
index 05573c1d45..659a0ff3bd 100644
--- a/gtk/gtkbuildable.c
+++ b/gtk/gtkbuildable.c
@@ -57,7 +57,7 @@ gtk_buildable_default_init (GtkBuildableInterface *iface)
  */
 void
 gtk_buildable_set_buildable_id (GtkBuildable *buildable,
-                      const char   *id)
+                                const char   *id)
 {
   GtkBuildableIface *iface;
 
@@ -108,7 +108,7 @@ gtk_buildable_get_buildable_id (GtkBuildable *buildable)
  * @buildable: a #GtkBuildable
  * @builder: a #GtkBuilder
  * @child: child to add
- * @type: (allow-none): kind of child or %NULL
+ * @type: (nullable): kind of child or %NULL
  *
  * Adds a child to @buildable. @type is an optional string
  * describing how the child should be added.
diff --git a/gtk/gtkbuildable.h b/gtk/gtkbuildable.h
index ed0dbdd25a..84008c9ff5 100644
--- a/gtk/gtkbuildable.h
+++ b/gtk/gtkbuildable.h
@@ -101,7 +101,7 @@ struct _GtkBuildableParser
  *  content below <child>. To handle an element, the implementation
  *  must fill in the @parser and @user_data and return %TRUE.
  *  #GtkWidget implements this to parse keyboard accelerators specified
- *  in <accelerator> elements. 
+ *  in <accelerator> elements.
  *  Note that @user_data must be freed in @custom_tag_end or @custom_finished.
  * @custom_tag_end: Called for the end tag of each custom element that is
  *  handled by the buildable (see @custom_tag_start).
@@ -128,7 +128,18 @@ struct _GtkBuildableIface
   /* virtual table */
   void          (* set_id)                 (GtkBuildable       *buildable,
                                             const char         *id);
-  const char * (* get_id)                  (GtkBuildable       *buildable);
+  const char *  (* get_id)                 (GtkBuildable       *buildable);
+
+  /**
+   * GtkBuildableIface::add_child:
+   * @buildable: a #GtkBuildable
+   * @builder: a #GtkBuilder
+   * @child: child to add
+   * @type: (nullable): kind of child or %NULL
+   *
+   * Adds a child to @buildable. @type is an optional string
+   * describing how the child should be added.
+   */
   void          (* add_child)              (GtkBuildable       *buildable,
                                             GtkBuilder         *builder,
                                             GObject            *child,
@@ -140,17 +151,55 @@ struct _GtkBuildableIface
   GObject *     (* construct_child)        (GtkBuildable       *buildable,
                                             GtkBuilder         *builder,
                                             const char         *name);
+
+  /**
+   * GtkBuildableIface::custom_tag_start:
+   * @buildable: a #GtkBuildable
+   * @builder: a #GtkBuilder used to construct this object
+   * @child: (nullable): child object or %NULL for non-child tags
+   * @tagname: name of tag
+   * @parser: (out): a #GMarkupParser to fill in
+   * @data: (out): return location for user data that will be passed in
+   *   to parser functions
+   *
+   * Called for each unknown element under `<child>`.
+   *
+   * Returns: %TRUE if an object has a custom implementation, %FALSE
+   *   if it doesn't.
+   */
   gboolean      (* custom_tag_start)       (GtkBuildable       *buildable,
                                             GtkBuilder         *builder,
                                             GObject            *child,
                                             const char         *tagname,
                                             GtkBuildableParser *parser,
                                             gpointer           *data);
+  /**
+   * GtkBuildableIface::custom_tag_end:
+   * @buildable: A #GtkBuildable
+   * @builder: #GtkBuilder used to construct this object
+   * @child: (nullable): child object or %NULL for non-child tags
+   * @tagname: name of tag
+   * @data: user data that will be passed in to parser functions
+   *
+   * Called at the end of each custom element handled by
+   * the buildable.
+   */
   void          (* custom_tag_end)         (GtkBuildable       *buildable,
                                             GtkBuilder         *builder,
                                             GObject            *child,
                                             const char         *tagname,
                                             gpointer            data);
+   /**
+    * GtkBuildableIface::custom_finished:
+    * @buildable: a #GtkBuildable
+    * @builder: a #GtkBuilder
+    * @child: (nullable): child object or %NULL for non-child tags
+    * @tagname: the name of the tag
+    * @data: user data created in custom_tag_start
+    *
+    * Similar to gtk_buildable_parser_finished() but is
+    * called once for each custom tag handled by the @buildable.
+    */
   void          (* custom_finished)        (GtkBuildable       *buildable,
                                             GtkBuilder         *builder,
                                             GObject            *child,
@@ -159,6 +208,16 @@ struct _GtkBuildableIface
   void          (* parser_finished)        (GtkBuildable       *buildable,
                                             GtkBuilder         *builder);
 
+  /**
+   * GtkBuildableIface::get_internal_child:
+   * @buildable: a #GtkBuildable
+   * @builder: a #GtkBuilder
+   * @childname: name of child
+   *
+   * Retrieves the internal child called @childname of the @buildable object.
+   *
+   * Returns: (transfer none): the internal child of the buildable object
+   */
   GObject *     (* get_internal_child)     (GtkBuildable       *buildable,
                                             GtkBuilder         *builder,
                                             const char         *childname);