From ba5993195ad43b11a4f4b2a89a3205ec18df0680 Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Sat, 25 May 2024 11:29:32 +0200 Subject: [PATCH 01/10] filedialog: Document get_accept_label --- gtk/gtkfiledialog.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/gtk/gtkfiledialog.c b/gtk/gtkfiledialog.c index 51b45a29fd..f3355b4940 100644 --- a/gtk/gtkfiledialog.c +++ b/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 From 30eaa2c3ccc3926f242cfd436c7061c6eac3fc6e Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Sat, 25 May 2024 18:10:07 +0200 Subject: [PATCH 02/10] gtk: Add missing return annotations --- gtk/gtkaccelgroup.c | 2 ++ gtk/gtkeditable.c | 2 ++ gtk/gtkeventcontrollerkey.c | 2 ++ gtk/gtkpaned.c | 12 ++++++++++++ gtk/gtkscrolledwindow.c | 2 ++ gtk/gtktext.c | 4 ++++ gtk/gtktextview.c | 4 ++++ 7 files changed, 28 insertions(+) diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c index 181433aa25..112ec9a996 100644 --- a/gtk/gtkaccelgroup.c +++ b/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, diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c index cf71f1c58e..bf195bb5f4 100644 --- a/gtk/gtkeditable.c +++ b/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 diff --git a/gtk/gtkeventcontrollerkey.c b/gtk/gtkeventcontrollerkey.c index 0ca3ac29bc..4f9097e8e2 100644 --- a/gtk/gtkeventcontrollerkey.c +++ b/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"), diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c index 5c30aad390..0169d2aa85 100644 --- a/gtk/gtkpaned.c +++ b/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 F6. + * + * 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 Tab. + * + * 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 F8. + * + * 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 Return or * Space. + * + * 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 Escape. + * + * Returns: whether the position was canceled */ signals [CANCEL_POSITION] = g_signal_new (I_("cancel-position"), diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c index c4fca8033a..b5249205b1 100644 --- a/gtk/gtkscrolledwindow.c +++ b/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"), diff --git a/gtk/gtktext.c b/gtk/gtktext.c index fae3547fea..599ccbb99f 100644 --- a/gtk/gtktext.c +++ b/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) diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c index 5a2110ff65..10f7b693c6 100644 --- a/gtk/gtktextview.c +++ b/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) From 3cc17268569a12dca3d493c069246c8cd1a3ae09 Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Sat, 25 May 2024 18:13:30 +0200 Subject: [PATCH 03/10] gtkstringlist: Document strings property --- gtk/gtkstringlist.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/gtk/gtkstringlist.c b/gtk/gtkstringlist.c index c389094f99..3f08a52813 100644 --- a/gtk/gtkstringlist.c +++ b/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] = From 1ab8ffaceb479eb44f6ca9d7318d3522068df2aa Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Sat, 25 May 2024 18:21:23 +0200 Subject: [PATCH 04/10] gtktextchild: Document new_with_replacement arg --- gtk/gtktextchild.c | 1 + 1 file changed, 1 insertion(+) diff --git a/gtk/gtktextchild.c b/gtk/gtktextchild.c index a7d2fa1860..2571ad605c 100644 --- a/gtk/gtktextchild.c +++ b/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. * From 2e9e2166412d12346c4cbcdd311cca17aafb4d7b Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Sat, 25 May 2024 18:21:59 +0200 Subject: [PATCH 05/10] gtkicontheme: Document lockup_icon arguments --- gtk/gtkicontheme.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c index a51376cbe6..5135d8e044 100644 --- a/gtk/gtkicontheme.c +++ b/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 From 949cd45bb78ddd28dc539e4b1b80b428b94d359b Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Sat, 25 May 2024 18:44:17 +0200 Subject: [PATCH 06/10] gskstroke: Add missing return annotations --- gsk/gskstroke.c | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/gsk/gskstroke.c b/gsk/gskstroke.c index 61cdc6a47a..6cd43375ca 100644 --- a/gsk/gskstroke.c +++ b/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 From 0bacde8e0a010d93da5333717211ab0ae37a23be Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Sat, 25 May 2024 18:46:10 +0200 Subject: [PATCH 07/10] gskpathbuilder: Document add_cairo_path path arg --- gsk/gskpathbuilder.c | 1 + 1 file changed, 1 insertion(+) diff --git a/gsk/gskpathbuilder.c b/gsk/gskpathbuilder.c index 82af89db0c..881b921923 100644 --- a/gsk/gskpathbuilder.c +++ b/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. * From cf4d13bee302a909c19015b2c2fc669f9afbf159 Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Sat, 25 May 2024 19:21:56 +0200 Subject: [PATCH 08/10] gdkevents: gdk_event_get_position return value --- gdk/gdkevents.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c index 93703d6225..cb698a2544 100644 --- a/gdk/gdkevents.c +++ b/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, From 39dbc5ea87b866deb22c7f229b80609c250a7a6f Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Sat, 25 May 2024 23:16:03 +0200 Subject: [PATCH 09/10] gtkcombobox: Document popdown signal return value --- gtk/deprecated/gtkcombobox.c | 2 ++ 1 file changed, 2 insertions(+) diff --git a/gtk/deprecated/gtkcombobox.c b/gtk/deprecated/gtkcombobox.c index 2be8d3b784..45b1c1a59b 100644 --- a/gtk/deprecated/gtkcombobox.c +++ b/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"), From a93a986ef2f34a709276f39c904110cb0f7d28aa Mon Sep 17 00:00:00 2001 From: Maximiliano Sandoval Date: Sat, 25 May 2024 23:41:40 +0200 Subject: [PATCH 10/10] gtkiconview: docs: Add missing return annotation --- gtk/deprecated/gtkiconview.c | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/gtk/deprecated/gtkiconview.c b/gtk/deprecated/gtkiconview.c index 3038bd3b12..8543721bb9 100644 --- a/gtk/deprecated/gtkiconview.c +++ b/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"),