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

@@ -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
  **/

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
  */

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
  **/

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

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)

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
  **/

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
  **/

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)

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)