From 97276a5cd46c07d73a90b942f529f1c0c88d5798 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 29 Sep 2020 19:39:34 +0100 Subject: [PATCH 1/2] Remove gtk-doc stanzas from private GtkBuildable API Various functions were moved to the private GtkBuildable header by commit 2715b3ec31256ee1c3e0276fdc0154cd8a69fa8e, but the functions still have gtk-doc stanzas. --- gtk/gtkbuildable.c | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c index dd0e33040d..05573c1d45 100644 --- a/gtk/gtkbuildable.c +++ b/gtk/gtkbuildable.c @@ -48,13 +48,13 @@ gtk_buildable_default_init (GtkBuildableInterface *iface) { } -/** +/*< private > * gtk_buildable_set_buildable_id: * @buildable: a #GtkBuildable * @id: name to set * * Sets the ID of the @buildable object. - **/ + */ void gtk_buildable_set_buildable_id (GtkBuildable *buildable, const char *id) @@ -103,7 +103,7 @@ gtk_buildable_get_buildable_id (GtkBuildable *buildable) "gtk-builder-id"); } -/** +/*< private > * gtk_buildable_add_child: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder @@ -112,7 +112,7 @@ gtk_buildable_get_buildable_id (GtkBuildable *buildable) * * Adds a child to @buildable. @type is an optional string * describing how the child should be added. - **/ + */ void gtk_buildable_add_child (GtkBuildable *buildable, GtkBuilder *builder, @@ -130,7 +130,7 @@ gtk_buildable_add_child (GtkBuildable *buildable, (* iface->add_child) (buildable, builder, child, type); } -/** +/*< private > * gtk_buildable_set_buildable_property: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder @@ -138,7 +138,7 @@ gtk_buildable_add_child (GtkBuildable *buildable, * @value: value of property * * Sets the property name @name to @value on the @buildable object. - **/ + */ void gtk_buildable_set_buildable_property (GtkBuildable *buildable, GtkBuilder *builder, @@ -159,7 +159,7 @@ gtk_buildable_set_buildable_property (GtkBuildable *buildable, g_object_set_property (G_OBJECT (buildable), name, value); } -/** +/*< private > * gtk_buildable_parser_finished: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder @@ -169,7 +169,7 @@ gtk_buildable_set_buildable_property (GtkBuildable *buildable, * Note that this will be called once for each time * gtk_builder_add_from_file() or gtk_builder_add_from_string() * is called on a builder. - **/ + */ void gtk_buildable_parser_finished (GtkBuildable *buildable, GtkBuilder *builder) @@ -184,7 +184,7 @@ gtk_buildable_parser_finished (GtkBuildable *buildable, (* iface->parser_finished) (buildable, builder); } -/** +/*< private > * gtk_buildable_construct_child: * @buildable: A #GtkBuildable * @builder: #GtkBuilder used to construct this object @@ -196,7 +196,7 @@ gtk_buildable_parser_finished (GtkBuildable *buildable, * specified in the UI definition. * * Returns: (transfer full): the constructed child - **/ + */ GObject * gtk_buildable_construct_child (GtkBuildable *buildable, GtkBuilder *builder, @@ -214,7 +214,7 @@ gtk_buildable_construct_child (GtkBuildable *buildable, return (* iface->construct_child) (buildable, builder, name); } -/** +/*< private > * gtk_buildable_custom_tag_start: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder used to construct this object @@ -228,7 +228,7 @@ gtk_buildable_construct_child (GtkBuildable *buildable, * * Returns: %TRUE if an object has a custom implementation, %FALSE * if it doesn't. - **/ + */ gboolean gtk_buildable_custom_tag_start (GtkBuildable *buildable, GtkBuilder *builder, @@ -250,7 +250,7 @@ gtk_buildable_custom_tag_start (GtkBuildable *buildable, tagname, parser, data); } -/** +/*< private > * gtk_buildable_custom_tag_end: * @buildable: A #GtkBuildable * @builder: #GtkBuilder used to construct this object @@ -260,7 +260,7 @@ gtk_buildable_custom_tag_start (GtkBuildable *buildable, * * This is called at the end of each custom element handled by * the buildable. - **/ + */ void gtk_buildable_custom_tag_end (GtkBuildable *buildable, GtkBuilder *builder, @@ -279,7 +279,7 @@ gtk_buildable_custom_tag_end (GtkBuildable *buildable, (* iface->custom_tag_end) (buildable, builder, child, tagname, data); } -/** +/*< private > * gtk_buildable_custom_finished: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder @@ -289,7 +289,7 @@ gtk_buildable_custom_tag_end (GtkBuildable *buildable, * * This is similar to gtk_buildable_parser_finished() but is * called once for each custom tag handled by the @buildable. - **/ + */ void gtk_buildable_custom_finished (GtkBuildable *buildable, GtkBuilder *builder, @@ -307,7 +307,7 @@ gtk_buildable_custom_finished (GtkBuildable *buildable, (* iface->custom_finished) (buildable, builder, child, tagname, data); } -/** +/*< private > * gtk_buildable_get_internal_child: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder @@ -316,7 +316,7 @@ gtk_buildable_custom_finished (GtkBuildable *buildable, * Get the internal child called @childname of the @buildable object. * * Returns: (transfer none): the internal child of the buildable object - **/ + */ GObject * gtk_buildable_get_internal_child (GtkBuildable *buildable, GtkBuilder *builder, From c6cedf608a6b1b86cc84bc0d357b3eaa163010dd Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 29 Sep 2020 19:48:55 +0100 Subject: [PATCH 2/2] 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 . 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 elements. + * in 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 ``. + * + * 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);