Merge branch 'docs-add-missing-returns-args' into 'main'

docs: Add missing returns and parameter annotations

See merge request GNOME/gtk!7325

gdk/gdkevents.c

@@ -1371,6 +1371,8 @@ gdk_event_get_modifier_state (GdkEvent *event)
  * Extract the event surface relative x/y coordinates from an event.
  *
  * This position is in [surface coordinates](coordinates.html).
+ *
+ * Returns: whether the positions were set
  */
 gboolean
 gdk_event_get_position (GdkEvent *event,

gsk/gskpathbuilder.c

@@ -387,6 +387,7 @@ gsk_path_builder_add_reverse_path (GskPathBuilder *self,
 /**
  * gsk_path_builder_add_cairo_path:
  * @self: a `GskPathBuilder`
+ * @path: a path
  *
  * Adds a Cairo path to the builder.
  *

gsk/gskstroke.c

@@ -354,6 +354,8 @@ gsk_stroke_set_miter_limit (GskStroke  *self,
  *
  * Returns the miter limit of a `GskStroke`.
  *
+ * Returns: the miter limit
+ *
  * Since: 4.14
  */
 float
@@ -478,6 +480,8 @@ gsk_stroke_set_dash_offset (GskStroke *self,
  *
  * Returns the dash_offset of a `GskStroke`.
  *
+ * Returns: the dash_offset
+ *
  * Since: 4.14
  */
 float

gtk/deprecated/gtkcombobox.c

@@ -512,6 +512,8 @@ gtk_combo_box_class_init (GtkComboBoxClass *klass)
    * This is an [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are Alt+Up and Escape.
+   *
+   * Returns: whether the combo box was popped down
    */
   combo_box_signals[POPDOWN] =
     g_signal_new_class_handler (I_("popdown"),

gtk/deprecated/gtkiconview.c

@@ -723,6 +723,8 @@ gtk_icon_view_class_init (GtkIconViewClass *klass)
    * programmatically.
    *
    * The default bindings for this signal are Space, Return and Enter.
+   *
+   * Returns: whether the item was activated
    */
   icon_view_signals[ACTIVATE_CURSOR_ITEM] =
     g_signal_new (I_("activate-cursor-item"),
@@ -758,6 +760,8 @@ gtk_icon_view_class_init (GtkIconViewClass *klass)
    * - PageUp/PageDown which move by "pages"
    * All of these will extend the selection when combined with
    * the Shift modifier.
+   *
+   * Returns: whether the cursor was moved
    */
   icon_view_signals[MOVE_CURSOR] =
     g_signal_new (I_("move-cursor"),

gtk/gtkaccelgroup.c

@@ -505,6 +505,8 @@ out:
  *
  * If the parse operation fails, @accelerator_key and @accelerator_mods will
  * be set to 0 (zero).
+ *
+ * Returns: whether parsing succeeded
  */
 gboolean
 gtk_accelerator_parse (const char      *accelerator,

gtk/gtkeditable.c

@@ -1231,6 +1231,8 @@ gtk_editable_delegate_get_property (GObject    *object,
  * delegate the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role, or you can
  * change your tree to allow this function to work.
  *
+ * Returns: the accessible platform state of the delegate
+ *
  * Since: 4.10
  */
 gboolean

gtk/gtkeventcontrollerkey.c

@@ -237,6 +237,8 @@ gtk_event_controller_key_class_init (GtkEventControllerKeyClass *klass)
    *   pointer buttons.
    *
    * Emitted whenever the state of modifier keys and pointer buttons change.
+   *
+   * Returns: whether to ignore modifiers
    */
   signals[MODIFIERS] =
     g_signal_new (I_("modifiers"),

gtk/gtkfiledialog.c

@@ -1268,6 +1268,8 @@ gtk_file_dialog_select_multiple_folders_finish (GtkFileDialog   *self,
  * gtk_file_dialog_get_accept_label:
  * @self: a `GtkFileDialog`
  *
+ * Retrieves the text used by the dialog on its accept button.
+ *
  * Returns: (nullable): the label shown on the file chooser's accept button.
  *
  * Since: 4.10

gtk/gtkicontheme.c

@@ -2433,7 +2433,7 @@ load_icon_thread (GTask        *task,
  * gtk_icon_theme_lookup_icon:
  * @self: a `GtkIconTheme`
  * @icon_name: the name of the icon to lookup
- * @fallbacks: (nullable) (array zero-terminated=1):
+ * @fallbacks: (nullable) (array zero-terminated=1): fallback names
  * @size: desired icon size, in application pixels
  * @scale: the window scale this will be displayed on
  * @direction: text direction the icon will be displayed in

gtk/gtkpaned.c

@@ -558,6 +558,8 @@ gtk_paned_class_init (GtkPanedClass *class)
    * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default binding is <kbd>F6</kbd>.
+   *
+   * Returns: whether the behavior was cycled
    */
   signals [CYCLE_CHILD_FOCUS] =
     g_signal_new (I_("cycle-child-focus"),
@@ -582,6 +584,8 @@ gtk_paned_class_init (GtkPanedClass *class)
    * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default binding is <kbd>Tab</kbd>.
+   *
+   * Return: whether handle focus was toggled
    */
   signals [TOGGLE_HANDLE_FOCUS] =
     g_signal_new (I_("toggle-handle-focus"),
@@ -603,6 +607,8 @@ gtk_paned_class_init (GtkPanedClass *class)
    * Emitted to move the handle with key bindings.
    *
    * This is a [keybinding signal](class.SignalAction.html).
+   *
+   * Returns: whether the handle was moved
    */
   signals[MOVE_HANDLE] =
     g_signal_new (I_("move-handle"),
@@ -628,6 +634,8 @@ gtk_paned_class_init (GtkPanedClass *class)
    * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default binding for this signal is <kbd>F8</kbd>.
+   *
+   * Returns: whether the behavior was cycled
    */
   signals [CYCLE_HANDLE_FOCUS] =
     g_signal_new (I_("cycle-handle-focus"),
@@ -653,6 +661,8 @@ gtk_paned_class_init (GtkPanedClass *class)
    *
    * The default binding for this signal is <kbd>Return</kbd> or
    * <kbd>Space</kbd>.
+   *
+   * Returns: whether the position was accepted
    */
   signals [ACCEPT_POSITION] =
     g_signal_new (I_("accept-position"),
@@ -679,6 +689,8 @@ gtk_paned_class_init (GtkPanedClass *class)
    * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default binding for this signal is <kbd>Escape</kbd>.
+   *
+   * Returns: whether the position was canceled
    */
   signals [CANCEL_POSITION] =
     g_signal_new (I_("cancel-position"),

gtk/gtkscrolledwindow.c

@@ -776,6 +776,8 @@ gtk_scrolled_window_class_init (GtkScrolledWindowClass *class)
    *
    * The horizontal or vertical adjustment is updated which triggers a
    * signal that the scrolled window’s child may listen to and scroll itself.
+   *
+   * Returns: whether the scroll happened
    */
   signals[SCROLL_CHILD] =
     g_signal_new (I_("scroll-child"),

gtk/gtkstringlist.c

@@ -514,6 +514,8 @@ gtk_string_list_class_init (GtkStringListClass *class)
   /**
    * GtkStringList:strings:
    *
+   * The strings in the model.
+   *
    * Since: 4.10
    */
   properties[PROP_STRINGS] =

gtk/gtktext.c

@@ -6876,6 +6876,8 @@ gtk_text_set_input_purpose (GtkText         *self,
  * @self: a `GtkText`
  *
  * Gets the input purpose of the `GtkText`.
+ *
+ * Returns: the input purpose
  */
 GtkInputPurpose
 gtk_text_get_input_purpose (GtkText *self)
@@ -6925,6 +6927,8 @@ gtk_text_set_input_hints (GtkText       *self,
  * @self: a `GtkText`
  *
  * Gets the input hints of the `GtkText`.
+ *
+ * Returns: the input hints
  */
 GtkInputHints
 gtk_text_get_input_hints (GtkText *self)

gtk/gtktextchild.c

@@ -414,6 +414,7 @@ gtk_text_child_anchor_new (void)
 
 /**
  * gtk_text_child_anchor_new_with_replacement:
+ * @character: a replacement character
  *
  * Creates a new `GtkTextChildAnchor` with the given replacement character.
  *

gtk/gtktextview.c

@@ -10058,6 +10058,8 @@ gtk_text_view_set_input_purpose (GtkTextView     *text_view,
  * @text_view: a `GtkTextView`
  *
  * Gets the `input-purpose` of the `GtkTextView`.
+ *
+ * Returns: the input purpose
  */
 GtkInputPurpose
 gtk_text_view_get_input_purpose (GtkTextView *text_view)
@@ -10106,6 +10108,8 @@ gtk_text_view_set_input_hints (GtkTextView   *text_view,
  * @text_view: a `GtkTextView`
  *
  * Gets the `input-hints` of the `GtkTextView`.
+ *
+ * Returns: the input hints
  */
 GtkInputHints
 gtk_text_view_get_input_hints (GtkTextView *text_view)