[gimp] Fix some gtk-doc comments and GIR annotations

From: Niels De Graef <nielsdg src gnome org>
To: commits-list gnome org
Cc:
Subject: [gimp] Fix some gtk-doc comments and GIR annotations
Date: Fri, 8 May 2020 13:27:01 +0000 (UTC)
commit ed310dd48d165a2ad8ef2418ccf2f30feb75a82e
Author: Niels De Graef <nielsdegraef gmail com>
Date:   Fri May 8 15:23:56 2020 +0200

    Fix some gtk-doc comments and GIR annotations

 libgimp/gimpexport.c             |  6 ++---
 libgimpwidgets/gimpenumwidgets.c | 47 ++++++++++++++++++++--------------------
 libgimpwidgets/gimpquerybox.h    |  2 +-
 libgimpwidgets/gimpwidgets.c     |  9 ++++----
 4 files changed, 33 insertions(+), 31 deletions(-)
---
diff --git a/libgimp/gimpexport.c b/libgimp/gimpexport.c
index ca6712e0b7..56735ace3c 100644
--- a/libgimp/gimpexport.c
+++ b/libgimp/gimpexport.c
@@ -1052,7 +1052,7 @@ gimp_export_image (GimpImage             **image,
  *
  * Creates a new export dialog. All file plug-ins should use this
  * dialog to get a consistent look on the export dialogs. Use
- * gimp_export_dialog_get_content_area() to get a #GtkVBox to be
+ * gimp_export_dialog_get_content_area() to get a vertical #GtkBox to be
  * filled with export options. The export dialog is a wrapped
  * #GimpDialog.
  *
@@ -1098,10 +1098,10 @@ gimp_export_dialog_new (const gchar *format_name,
  * gimp_export_dialog_get_content_area:
  * @dialog: A dialog created with gimp_export_dialog_new()
  *
- * Returns the #GtkVBox of the passed export dialog to be filled with
+ * Returns the vertical #GtkBox of the passed export dialog to be filled with
  * export options.
  *
- * Returns: (transfer none): The #GtkVBox to fill with export options.
+ * Returns: (transfer none): The #GtkBox to fill with export options.
  *
  * Since: 2.8
  **/
diff --git a/libgimpwidgets/gimpenumwidgets.c b/libgimpwidgets/gimpenumwidgets.c
index 6f2fb6eb00..6baf3fdf77 100644
--- a/libgimpwidgets/gimpenumwidgets.c
+++ b/libgimpwidgets/gimpenumwidgets.c
@@ -45,18 +45,18 @@
 /**
  * gimp_enum_radio_box_new:
  * @enum_type:     the #GType of an enum.
- * @callback:      a callback to connect to the "toggled" signal of each
- *                 #GtkRadioButton that is created.
+ * @callback: (nullable): a callback to connect to the "toggled" signal of each
+ *                        #GtkRadioButton that is created.
  * @callback_data: data to pass to the @callback.
  * @callback_data_destroy: Destroy function for @callback_data.
- * @first_button:  returns the first button in the created group.
+ * @first_button: (out) (optional): returns the first button in the created group.
  *
  * Creates a new group of #GtkRadioButtons representing the enum
  * values.  A group of radiobuttons is a good way to represent enums
  * with up to three or four values. Often it is better to use a
  * #GimpEnumComboBox instead.
  *
- * Returns: (transfer full): a new #GtkVBox holding a group of #GtkRadioButtons.
+ * Returns: (transfer full): a new #GtkBox holding a group of #GtkRadioButtons.
  *
  * Since: 2.4
  **/
@@ -91,17 +91,18 @@ gimp_enum_radio_box_new (GType            enum_type,
  * @minimum:       the minimum enum value
  * @maximum:       the maximum enum value
  * @enum_type:     the #GType of an enum.
- * @callback:      a callback to connect to the "toggled" signal of each
+ * @callback: (nullable): a callback to connect to the "toggled" signal of each
  *                 #GtkRadioButton that is created.
  * @callback_data: data to pass to the @callback.
  * @callback_data_destroy: Destroy function for @callback_data.
- * @first_button:  returns the first button in the created group.
+ * @first_button: (out) (optional): returns the first button in the created group.
  *
  * Just like gimp_enum_radio_box_new(), this function creates a group
  * of radio buttons, but additionally it supports limiting the range
  * of available enum values.
  *
- * Returns: (transfer full): a new #GtkVBox holding a group of #GtkRadioButtons.
+ * Returns: (transfer full): a new vertical #GtkBox holding a group of
+ *                           #GtkRadioButtons
  *
  * Since: 2.4
  **/
@@ -168,13 +169,13 @@ gimp_enum_radio_box_new_with_range (GType            enum_type,
 /**
  * gimp_enum_radio_frame_new:
  * @enum_type:     the #GType of an enum.
- * @label_widget:  a widget to use as label for the frame that will
- *                 hold the radio box.
- * @callback:      a callback to connect to the "toggled" signal of each
- *                 #GtkRadioButton that is created.
+ * @label_widget: (nullable): a #GtkWidget to use as label for the frame
+ *                            that will hold the radio box.
+ * @callback: (nullable): a callback to connect to the "toggled" signal of each
+ *                        #GtkRadioButton that is created.
  * @callback_data: data to pass to the @callback.
  * @callback_data_destroy: Destroy function for @callback_data.
- * @first_button:  returns the first button in the created group.
+ * @first_button: (out) (optional): returns the first button in the created group.
  *
  * Calls gimp_enum_radio_box_new() and puts the resulting vbox into a
  * #GtkFrame.
@@ -221,15 +222,15 @@ gimp_enum_radio_frame_new (GType            enum_type,
  * @enum_type:     the #GType of an enum.
  * @minimum:       the minimum enum value
  * @maximum:       the maximum enum value
- * @label_widget:  a widget to put into the frame that will hold the radio box.
- * @callback:      a callback to connect to the "toggled" signal of each
- *                 #GtkRadioButton that is created.
+ * @label_widget: (nulllable): a widget to put into the frame that will hold the radio box.
+ * @callback: (nullable): a callback to connect to the "toggled" signal of each
+ *                        #GtkRadioButton that is created.
  * @callback_data: data to pass to the @callback.
  * @callback_data_destroy: Destroy function for @callback_data.
- * @first_button:  returns the first button in the created group.
+ * @first_button: (out) (optional): returns the first button in the created group.
  *
  * Calls gimp_enum_radio_box_new_with_range() and puts the resulting
- * vbox into a #GtkFrame.
+ * vertical box into a #GtkFrame.
  *
  * Returns: (transfer full): a new #GtkFrame holding a group of #GtkRadioButtons.
  *
@@ -277,11 +278,11 @@ gimp_enum_radio_frame_new_with_range (GType            enum_type,
  * @enum_type:     the #GType of an enum.
  * @icon_prefix:   the prefix of the group of icon names to use.
  * @icon_size:     the icon size for the icons
- * @callback:      a callback to connect to the "toggled" signal of each
- *                 #GtkRadioButton that is created.
+ * @callback: (nullable): a callback to connect to the "toggled" signal of each
+ *                        #GtkRadioButton that is created.
  * @callback_data: data to pass to the @callback.
  * @callback_data_destroy: Destroy function for @callback_data.
- * @first_button:  returns the first button in the created group.
+ * @first_button: (out) (optional): returns the first button in the created group.
  *
  * Creates a horizontal box of radio buttons with named icons. The
  * icon name for each icon is created by appending the enum_value's
@@ -327,11 +328,11 @@ gimp_enum_icon_box_new (GType            enum_type,
  * @maximum:       the maximum enum value
  * @icon_prefix:   the prefix of the group of icon names to use.
  * @icon_size:     the icon size for the icons
- * @callback:      a callback to connect to the "toggled" signal of each
- *                 #GtkRadioButton that is created.
+ * @callback: (nullable): a callback to connect to the "toggled" signal of each
+ *                        #GtkRadioButton that is created.
  * @callback_data: data to pass to the @callback.
  * @callback_data_destroy: Destroy function for @callback_data.
- * @first_button:  returns the first button in the created group.
+ * @first_button: (out) (optional): returns the first button in the created group.
  *
  * Just like gimp_enum_icon_box_new(), this function creates a group
  * of radio buttons, but additionally it supports limiting the range
diff --git a/libgimpwidgets/gimpquerybox.h b/libgimpwidgets/gimpquerybox.h
index 7f31aa59d9..515aa50b31 100644
--- a/libgimpwidgets/gimpquerybox.h
+++ b/libgimpwidgets/gimpquerybox.h
@@ -98,7 +98,7 @@ typedef void (* GimpQueryBooleanCallback) (GtkWidget   *query_box,
  * GIMP_QUERY_BOX_VBOX:
  * @qbox: The query box.
  *
- * A macro to access the #GtkVBox in a #libgimpwidgets-gimpquerybox.
+ * A macro to access the vertical #GtkBox in a #libgimpwidgets-gimpquerybox.
  * Useful if you want to add more widgets.
  **/
 #define GIMP_QUERY_BOX_VBOX(qbox) g_object_get_data (G_OBJECT (qbox), \
diff --git a/libgimpwidgets/gimpwidgets.c b/libgimpwidgets/gimpwidgets.c
index 106b06bdc7..948f10f323 100644
--- a/libgimpwidgets/gimpwidgets.c
+++ b/libgimpwidgets/gimpwidgets.c
@@ -48,8 +48,9 @@
  * gimp_int_radio_group_new:
  * @in_frame:              %TRUE if you want a #GtkFrame around the
  *                         radio button group.
- * @frame_title:           The title of the Frame or %NULL if you don't want
- *                         a title.
+ * @frame_title: (nullable):
+ *                         The title of the Frame or %NULL if you don't want a
+ *                         title.
  * @radio_button_callback: (scope notified): The callback each button's
  *                         "toggled" signal will be connected with.
  * @radio_button_callback_data: (closure radio_button_callback):
@@ -60,12 +61,12 @@
  *                         the radio buttons.
  *
  * Convenience function to create a group of radio buttons embedded into
- * a #GtkFrame or #GtkVBox. This function does the same thing as
+ * a #GtkFrame or #GtkBox. This function does the same thing as
  * gimp_radio_group_new2(), but it takes integers as @item_data instead of
  * pointers, since that is a very common case (mapping an enum to a radio
  * group).
  *
- * Returns: (transfer full): A #GtkFrame or #GtkVBox (depending on @in_frame).
+ * Returns: (transfer full): A #GtkFrame or #GtkBox (depending on @in_frame).
  **/
 GtkWidget *
 gimp_int_radio_group_new (gboolean         in_frame,
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]