[gimp] GIR: Try to return more specific GtkWidget subclass

[Niels De Graef <nielsdg src gnome org>]

commit df28349c177ebddc5300ac0e544f5baab0d650c8
Author: Niels De Graef <nielsdegraef gmail com>
Date:   Fri Dec 25 15:05:16 2020 +0100

    GIR: Try to return more specific GtkWidget subclass
    
    In GTK, a common scheme is to let a function creating a specific widget
    to return a `GtkWidget *`, rather than the specific subtype, since you
    often need to call API of GtkWidget, avoiding some useless casts.
    
    For bindings however (and especially bindings to compiled languages),
    this is a bit annoying, as you have to explicitly change the type of the
    return value (downcast), which is not trivial (or at least desirable) in
    each language.
    
    Luckily, we can use `(type ...)` annotation for this use case, leaving
    the C API unchanged, while improving the experience for bindings.

 libgimpwidgets/gimpbrowser.c        |  4 ++--
 libgimpwidgets/gimpchainbutton.c    |  2 +-
 libgimpwidgets/gimpcolornotebook.c  |  2 +-
 libgimpwidgets/gimpcolorselection.c |  2 +-
 libgimpwidgets/gimplabeled.c        |  2 +-
 libgimpwidgets/gimpmemsizeentry.c   |  2 +-
 libgimpwidgets/gimppreview.c        | 16 ++++++++++------
 libgimpwidgets/gimpscaleentry.c     |  2 +-
 libgimpwidgets/gimpsizeentry.c      |  2 +-
 9 files changed, 19 insertions(+), 15 deletions(-)
---
diff --git a/libgimpwidgets/gimpbrowser.c b/libgimpwidgets/gimpbrowser.c
index c96373f9fe..311566c5be 100644
--- a/libgimpwidgets/gimpbrowser.c
+++ b/libgimpwidgets/gimpbrowser.c
@@ -293,7 +293,7 @@ gimp_browser_add_search_types (GimpBrowser *browser,
  * gimp_browser_get_left_vbox:
  * @browser: a #GimpBrowser widget
  *
- * Returns: (transfer none): The left vbox.
+ * Returns: (transfer none) (type GtkBox): The left vbox.
  *
  * Since: 3.0
  **/
@@ -313,7 +313,7 @@ gimp_browser_get_left_vbox (GimpBrowser *browser)
  * gimp_browser_get_right_vbox:
  * @browser: a #GimpBrowser widget
  *
- * Returns: (transfer none): The right vbox.
+ * Returns: (transfer none) (type GtkBox): The right vbox.
  *
  * Since: 3.0
  **/
diff --git a/libgimpwidgets/gimpchainbutton.c b/libgimpwidgets/gimpchainbutton.c
index dd7ace0c3f..1c4b586ebd 100644
--- a/libgimpwidgets/gimpchainbutton.c
+++ b/libgimpwidgets/gimpchainbutton.c
@@ -440,7 +440,7 @@ gimp_chain_button_get_active (GimpChainButton *button)
  * gimp_chain_button_get_button
  * @button: A #GimpChainButton.
  *
- * Returns: (transfer none): The #GimpChainButton's button.
+ * Returns: (transfer none) (type GtkButton): The #GimpChainButton's button.
  *
  * Since: 3.0
  */
diff --git a/libgimpwidgets/gimpcolornotebook.c b/libgimpwidgets/gimpcolornotebook.c
index d567d16098..839a06fe41 100644
--- a/libgimpwidgets/gimpcolornotebook.c
+++ b/libgimpwidgets/gimpcolornotebook.c
@@ -552,7 +552,7 @@ gimp_color_notebook_set_has_page (GimpColorNotebook *notebook,
  * gimp_color_notebook_get_notebook:
  * @notebook:  A #GimpColorNotebook widget.
  *
- * Returns: (transfer none): The #GtkNotebook inside.
+ * Returns: (transfer none) (type GtkNotebook): The #GtkNotebook inside.
  *
  * Since: 3.0
  **/
diff --git a/libgimpwidgets/gimpcolorselection.c b/libgimpwidgets/gimpcolorselection.c
index 16874c58cc..6f239de2bb 100644
--- a/libgimpwidgets/gimpcolorselection.c
+++ b/libgimpwidgets/gimpcolorselection.c
@@ -612,7 +612,7 @@ gimp_color_selection_get_notebook (GimpColorSelection *selection)
  * gimp_color_selection_get_right_vbox:
  * @selection: A #GimpColorSelection widget.
  *
- * Returns: (transfer none): The selection's right #GtkBox which
+ * Returns: (transfer none) (type GtkBox): The selection's right #GtkBox which
  *          contains the color scales.
  *
  * Since: 3.0
diff --git a/libgimpwidgets/gimplabeled.c b/libgimpwidgets/gimplabeled.c
index f39a8b8739..19c088c1e2 100644
--- a/libgimpwidgets/gimplabeled.c
+++ b/libgimpwidgets/gimplabeled.c
@@ -184,7 +184,7 @@ gimp_labeled_get_property (GObject    *object,
  * This function returns the #GtkLabel packed in @labeled. This can be
  * useful if you need to customize some aspects of the widget.
  *
- * Returns: (transfer none): The #GtkLabel contained in @labeled.
+ * Returns: (transfer none) (type GtkLabel): The #GtkLabel contained in @labeled.
  **/
 GtkWidget *
 gimp_labeled_get_label (GimpLabeled *labeled)
diff --git a/libgimpwidgets/gimpmemsizeentry.c b/libgimpwidgets/gimpmemsizeentry.c
index e4249fd9fb..508f63a3a1 100644
--- a/libgimpwidgets/gimpmemsizeentry.c
+++ b/libgimpwidgets/gimpmemsizeentry.c
@@ -323,7 +323,7 @@ gimp_memsize_entry_get_value (GimpMemsizeEntry *entry)
  * gimp_memsize_entry_get_spinbutton:
  * @entry: a #GimpMemsizeEntry
  *
- * Returns: (transfer none): the entry's #GtkSpinbutton.
+ * Returns: (transfer none) (type GtkSpinButton): the entry's #GtkSpinbutton.
  *
  * Since: 3.0
  **/
diff --git a/libgimpwidgets/gimppreview.c b/libgimpwidgets/gimppreview.c
index 7b1df2a7cb..9a16e5fc6a 100644
--- a/libgimpwidgets/gimppreview.c
+++ b/libgimpwidgets/gimppreview.c
@@ -799,7 +799,8 @@ gimp_preview_untransform (GimpPreview *preview,
  * gimp_preview_get_frame:
  * @preview: a #GimpPreview widget
  *
- * Returns: (transfer none): a pointer to the #GtkAspectFrame used in the @preview.
+ * Returns: (transfer none) (type GtkAspectFrame): a pointer to the
+ * #GtkAspectFrame used in the @preview.
  *
  * Since: 3.0
  **/
@@ -815,7 +816,8 @@ gimp_preview_get_frame (GimpPreview  *preview)
  * gimp_preview_get_grid:
  * @preview: a #GimpPreview widget
  *
- * Returns: (transfer none): a pointer to the #GtkGrid used in the @preview.
+ * Returns: (transfer none) (type GtkGrid): a pointer to
+ * the #GtkGrid used in the @preview.
  *
  * Since: 3.0
  **/
@@ -836,7 +838,8 @@ gimp_preview_get_grid (GimpPreview  *preview)
  * For example if you want to receive mouse events from the area. In
  * such cases, use gimp_preview_get_area().
  *
- * Returns: (transfer none): a pointer to the #GimpPreviewArea used in the @preview.
+ * Returns: (transfer none) (type GimpPreviewArea): a pointer to the
+ * #GimpPreviewArea used in the @preview.
  *
  * Since: 2.4
  **/
@@ -976,11 +979,12 @@ gimp_preview_get_default_cursor (GimpPreview *preview)
  * gimp_preview_get_controls:
  * @preview: a #GimpPreview widget
  *
- * Gives access to the #GtkHBox at the bottom of the preview that
- * contains the update toggle. Derived widgets can use this function
+ * Gives access to the horizontal #GtkBox at the bottom of the preview
+ * that contains the update toggle. Derived widgets can use this function
  * if they need to add controls to this area.
  *
- * Returns: (transfer none): the #GtkHBox at the bottom of the preview.
+ * Returns: (transfer none) (type GtkBox): the horizontal #GtkBox at the
+ * bottom of the preview.
  *
  * Since: 2.4
  **/
diff --git a/libgimpwidgets/gimpscaleentry.c b/libgimpwidgets/gimpscaleentry.c
index e2cb49073b..67b2e6e4ef 100644
--- a/libgimpwidgets/gimpscaleentry.c
+++ b/libgimpwidgets/gimpscaleentry.c
@@ -310,7 +310,7 @@ gimp_scale_entry_new  (const gchar *text,
  * #GtkRange if a subclass overrode the new_range_widget() protected
  * method.
  *
- * Returns: (transfer none): The #GtkRange contained in @entry.
+ * Returns: (transfer none) (type GtkRange): The #GtkRange contained in @entry.
  **/
 GtkWidget *
 gimp_scale_entry_get_range (GimpScaleEntry *entry)
diff --git a/libgimpwidgets/gimpsizeentry.c b/libgimpwidgets/gimpsizeentry.c
index c612d6d405..4f10cb6bf8 100644
--- a/libgimpwidgets/gimpsizeentry.c
+++ b/libgimpwidgets/gimpsizeentry.c
@@ -543,7 +543,7 @@ gimp_size_entry_get_n_fields (GimpSizeEntry *gse)
  * gimp_size_entry_get_unit_combo:
  * @gse: a #GimpSizeEntry.
  *
- * Returns: (transfer none): the size entry's #GimpUnitComboBox.
+ * Returns: (transfer none) (type GimpUnitComboBox): the size entry's #GimpUnitComboBox.
  **/
 GtkWidget *
 gimp_size_entry_get_unit_combo (GimpSizeEntry *gse)