Commit b4c79bad authored by Matthias Clasen's avatar Matthias Clasen
Browse files

Assorted documentation fixes

parent 013cc096
Pipeline #171669 passed with stages
in 47 minutes and 49 seconds
......@@ -74,6 +74,8 @@ gtk_accel_label_get_accel
gtk_accel_label_refetch
gtk_accel_label_set_label
gtk_accel_label_get_label
gtk_accel_label_get_use_underline
gtk_accel_label_set_use_underline
<SUBSECTION Standard>
GTK_ACCEL_LABEL
GTK_IS_ACCEL_LABEL
......@@ -180,6 +182,7 @@ GTK_ASSISTANT_GET_CLASS
<SUBSECTION Private>
GtkAssistantPrivate
gtk_assistant_get_type
gtk_assistant_page_get_type
</SECTION>
<SECTION>
......@@ -559,6 +562,12 @@ gtk_calendar_mark_day
gtk_calendar_unmark_day
gtk_calendar_get_day_is_marked
gtk_calendar_clear_marks
gtk_calendar_get_show_day_names
gtk_calendar_set_show_day_names
gtk_calendar_get_show_heading
gtk_calendar_set_show_heading
gtk_calendar_get_show_week_numbers
gtk_calendar_set_show_week_numbers
<SUBSECTION>
gtk_calendar_get_date
......@@ -1591,7 +1600,6 @@ gtk_label_set_text
gtk_label_set_attributes
gtk_label_set_markup
gtk_label_set_markup_with_mnemonic
gtk_label_set_pattern
gtk_label_set_justify
gtk_label_set_xalign
gtk_label_set_yalign
......@@ -1632,8 +1640,6 @@ gtk_label_set_use_markup
gtk_label_set_use_underline
gtk_label_set_single_line_mode
gtk_label_get_current_uri
gtk_label_set_track_visited_links
gtk_label_get_track_visited_links
gtk_label_set_extra_menu
gtk_label_get_extra_menu
......@@ -1714,6 +1720,8 @@ gtk_menu_button_set_label
gtk_menu_button_get_label
gtk_menu_button_set_has_frame
gtk_menu_button_get_has_frame
gtk_menu_button_get_use_underline
gtk_menu_button_set_use_underline
gtk_menu_button_popup
gtk_menu_button_popdown
GtkMenuButtonCreatePopupFunc
......@@ -3843,6 +3851,8 @@ gtk_list_store_get_type
<TITLE>GtkViewport</TITLE>
GtkViewport
gtk_viewport_new
gtk_viewport_set_scroll_to_focus
gtk_viewport_get_scroll_to_focus
<SUBSECTION Standard>
GTK_VIEWPORT
GTK_IS_VIEWPORT
......@@ -3971,6 +3981,9 @@ gtk_widget_allocate
gtk_widget_class_add_shortcut
gtk_widget_class_add_binding
gtk_widget_class_add_binding_signal
gtk_widget_class_add_binding_action
gtk_widget_class_set_layout_manager_type
gtk_widget_class_get_layout_manager_type
gtk_widget_activate
gtk_widget_is_focus
gtk_widget_grab_focus
......@@ -5813,6 +5826,8 @@ gtk_event_controller_get_propagation_limit
gtk_event_controller_set_propagation_limit
gtk_event_controller_get_widget
gtk_event_controller_reset
gtk_event_controller_get_name
gtk_event_controller_set_name
<SUBSECTION>
gtk_event_controller_get_current_event
......@@ -5987,6 +6002,7 @@ gtk_mnemonic_trigger_get_keyval
GtkAlternativeTrigger
gtk_alternative_trigger_new
gtk_alternative_trigger_get_first
gtk_alternative_trigger_get_second
<SUBSECTION>
GtkNeverTrigger
......@@ -6072,7 +6088,7 @@ GtkShortcutManagerInterface
<TITLE>GtkShortcutController</TITLE>
GtkShortcutController
gtk_shortcut_controller_new
gtk_shortcut_controller_new_with_model
gtk_shortcut_controller_new_for_model
GtkShortcutScope
GtkShortcutManager
GtkShortcutManagerInterface
......
......@@ -55,6 +55,9 @@ typedef struct _GtkAboutDialog GtkAboutDialog;
* @GTK_LICENSE_LGPL_3_0_ONLY: The GNU Lesser General Public License, version 3.0 only
* @GTK_LICENSE_AGPL_3_0: The GNU Affero General Public License, version 3.0 or later
* @GTK_LICENSE_AGPL_3_0_ONLY: The GNU Affero General Public License, version 3.0 only
* @GTK_LICENSE_BSD_3: The 3-clause BSD licence
* @GTK_LICENSE_APACHE_2_0: The Apache License, version 2.0
* @GTK_LICENSE_MPL_2_0: The Mozilla Public License, version 2.0
*
* The type of license for an application.
*
......
......@@ -640,7 +640,7 @@ gtk_button_new_with_mnemonic (const gchar *label)
}
/**
* gtk_Button_set_has_frame:
* gtk_button_set_has_frame:
* @button: a #GtkButton
* @has_frame: whether the button should have a visible frame
*
......
......@@ -1635,8 +1635,12 @@ gtk_calendar_unmark_day (GtkCalendar *calendar,
* gtk_calendar_get_date:
* @self: a #GtkCalendar
*
* Returns: (transfer full): A #GDateTime representing the shown
* year, month and the selected day, in the local time zone.
* Returns a #GDateTime representing the shown
* year, month and the selected day, in the local
* time zone.
*
* Returns: (transfer full): the #GDate representing
* the shown date.
*/
GDateTime *
gtk_calendar_get_date (GtkCalendar *self)
......@@ -1649,9 +1653,9 @@ gtk_calendar_get_date (GtkCalendar *self)
}
/**
* gtk_calendar_set_show_week_numbers
* gtk_calendar_set_show_week_numbers:
* @self: a #GtkCalendar
* @value: Whether to show week numbers on the left of the days
* @value: whether to show week numbers on the left of the days
*
* Sets whether week numbers are shown in the calendar.
*/
......@@ -1680,8 +1684,11 @@ gtk_calendar_set_show_week_numbers (GtkCalendar *self,
* gtk_calendar_get_show_week_numbers:
* @self: a #GtkCalendar
*
* Returns: Whether @self is showing week numbers right now,
* i.e. the value of the #GtkCalendar:show-week-numbers property.
* Returns whether @self is showing week numbers right
* now, i.e. the value of the #GtkCalendar:show-week-numbers
* property.
*
* Return: Whether the calendar is showing week numbers.
*/
gboolean
gtk_calendar_get_show_week_numbers (GtkCalendar *self)
......@@ -1696,9 +1703,11 @@ gtk_calendar_get_show_week_numbers (GtkCalendar *self)
/**
* gtk_calendar_set_show_heading:
* @self: a #GtkCalendar
* @value: Whether to show the heading in the calendar,
* containing the current year and month as well as
* buttons for changing both.
* @value: Whether to show the heading in the calendar
*
* Sets whether the calendar should show a heading
* containing the current year and month as well as
* buttons for changing both.
*/
void
gtk_calendar_set_show_heading (GtkCalendar *self,
......@@ -1722,8 +1731,10 @@ gtk_calendar_set_show_heading (GtkCalendar *self,
* gtk_calendar_get_show_heading:
* @self: a #GtkCalendar
*
* Returns: Whether @self is currently showing the heading,
* i.e. the value of the #GtkCalendar:show-heading property.
* Returns whether @self is currently showing the heading,
* i.e. the value of the #GtkCalendar:show-heading property.
*
* Return: Whether the calendar is showing a heading.
*/
gboolean
gtk_calendar_get_show_heading (GtkCalendar *self)
......@@ -1738,8 +1749,9 @@ gtk_calendar_get_show_heading (GtkCalendar *self)
/**
* gtk_calendar_set_show_day_names:
* @self: a #GtkCalendar
* @value: Whether to show week day names above the
* day numbers
* @value: Whether to show day names above the day numbers
*
* Sets whether the calendar shows day names.
*/
void
gtk_calendar_set_show_day_names (GtkCalendar *self,
......@@ -1763,12 +1775,14 @@ gtk_calendar_set_show_day_names (GtkCalendar *self,
}
/**
* gtk_calendar_get_day_names:
* gtk_calendar_get_show_day_names:
* @self: a #GtkCalendar
*
* Returns: Whether @self is currently showing the names
* of the week days above the day numbers, i.e. the value
* of the #GtkCalendar:show-day-names property.
* Returns whether @self is currently showing the names
* of the week days above the day numbers, i.e. the value
* of the #GtkCalendar:show-day-names property.
*
* Returns: Whether the calendar shows day names.
*/
gboolean
gtk_calendar_get_show_day_names (GtkCalendar *self)
......
......@@ -568,6 +568,7 @@ gtk_center_layout_set_orientation (GtkCenterLayout *self,
* gtk_center_layout_get_orientation:
* @self: a #GtkCenterLayout
*
* Gets the current orienration of the layout manager.
*
* Returns: The current orientation of @self
*/
......@@ -599,6 +600,8 @@ gtk_center_layout_set_baseline_position (GtkCenterLayout *self,
* gtk_center_layout_get_baseline_position:
* @self: a #GtkCenterLayout
*
* Returns the baseline position of the layout.
*
* Returns: The current baseline position of @self.
*/
GtkBaselinePosition
......@@ -625,6 +628,8 @@ gtk_center_layout_set_start_widget (GtkCenterLayout *self,
* gtk_center_layout_get_start_widget:
* @self: a #GtkCenterLayout
*
* Returns the start widget fo the layout.
*
* Returns: (transfer none): The current start widget of @self
*/
GtkWidget *
......@@ -651,6 +656,8 @@ gtk_center_layout_set_center_widget (GtkCenterLayout *self,
* gtk_center_layout_get_center_widget:
* @self: a #GtkCenterLayout
*
* Returns the center widget of the layout.
*
* Returns: (transfer none): the current center widget of @self
*/
GtkWidget *
......@@ -677,6 +684,8 @@ gtk_center_layout_set_end_widget (GtkCenterLayout *self,
* gtk_center_layout_get_end_widget:
* @self: a #GtkCenterLayout
*
* Returns the end widget of the layout.
*
* Returns: (transfer none): the current end widget of @self
*/
GtkWidget *
......
......@@ -1058,6 +1058,12 @@ gtk_emoji_chooser_class_init (GtkEmojiChooserClass *klass)
gtk_widget_class_bind_template_callback (widget_class, long_pressed_cb);
gtk_widget_class_bind_template_callback (widget_class, keynav_failed);
/**
* GtkEmojiChooser|scroll.section:
* @direction: 1 to scroll forward, -1 to scroll back
*
* Scrolls to the next or previous section.
*/
gtk_widget_class_install_action (widget_class, "scroll.section", "i",
gtk_emoji_chooser_scroll_section);
......
......@@ -476,6 +476,14 @@ gtk_event_controller_set_propagation_phase (GtkEventController *controller,
g_object_notify_by_pspec (G_OBJECT (controller), properties[PROP_PROPAGATION_PHASE]);
}
/**
* gtk_event_controller_get_propagation_limit:
* @controller: a #GtkEventController
*
* Gets the propagation limit of the event controller.
*
* Returns: the propagation limit
*/
GtkPropagationLimit
gtk_event_controller_get_propagation_limit (GtkEventController *controller)
{
......@@ -487,6 +495,18 @@ gtk_event_controller_get_propagation_limit (GtkEventController *controller)
return priv->limit;
}
/**
* gtk_event_controller_set_propagation_limit:
* @controller: a #GtkEventController
* @limit: the propagation limit
*
* Sets the event propagation limit on the event controller.
*
* If the limit is set to %@GTK_LIMIT_SAME_NATIVE, the controller
* won't handle events that are targeted at widgets on a different
* surface, such as popovers.
*/
void
gtk_event_controller_set_propagation_limit (GtkEventController *controller,
GtkPropagationLimit limit)
......@@ -505,6 +525,12 @@ gtk_event_controller_set_propagation_limit (GtkEventController *controller,
g_object_notify_by_pspec (G_OBJECT (controller), properties[PROP_PROPAGATION_LIMIT]);
}
/**
* gtk_event_controller_get_name:
* @controller: a #GtkEventController
*
* Gets the name of @controller.
*/
const char *
gtk_event_controller_get_name (GtkEventController *controller)
{
......@@ -515,6 +541,14 @@ gtk_event_controller_get_name (GtkEventController *controller)
return priv->name;
}
/**
* gtk_event_controller_set_name:
* @controller: a #GtkEventController
* @name: a name for @controller
*
* Sets a name on the controller that can be used for
* debugging.
*/
void
gtk_event_controller_set_name (GtkEventController *controller,
const char *name)
......
......@@ -334,13 +334,12 @@ gtk_gesture_long_press_new (void)
}
/**
* gtk_gesture_long_press_set_property:
* gtk_gesture_long_press_set_delay_factor:
* @gesture: A #GtkGestureLongPress
* @delay_factor: The delay factor to apply
*
* Applies the given delay factor. The default long press time will be
* multiplied by this value.
* Valid values are in the range [0.5..2.0].
* multiplied by this value. Valid values are in the range [0.5..2.0].
*/
void
gtk_gesture_long_press_set_delay_factor (GtkGestureLongPress *gesture,
......@@ -358,10 +357,12 @@ gtk_gesture_long_press_set_delay_factor (GtkGestureLongPress *gesture,
}
/**
* gtk_gesture_long_press_get_property:
* gtk_gesture_long_press_get_delay_factor:
* @gesture: A #GtkGestureLongPress
*
* Returns the delay factor as set by gtk_gesture_long_press_set_delay_factor().
*
* Returns: the delay factor
*/
double
gtk_gesture_long_press_get_delay_factor (GtkGestureLongPress *gesture)
......
......@@ -1086,18 +1086,60 @@ gtk_label_class_init (GtkLabelClass *class)
quark_mnemonics_visible_connected = g_quark_from_static_string ("gtk-label-mnemonics-visible-connected");
/**
* GtkLabel|clipboard.cut:
*
* Doesn't do anything, since text in labels can't be deleted.
*/
gtk_widget_class_install_action (widget_class, "clipboard.cut", NULL,
gtk_label_nop);
/**
* GtkLabel|clipboard.copy:
*
* Copies the text to the clipboard.
*/
gtk_widget_class_install_action (widget_class, "clipboard.copy", NULL,
gtk_label_activate_clipboard_copy);
/**
* GtkLabel|clipboard.paste:
*
* Doesn't do anything, since text in labels can't be edited.
*/
gtk_widget_class_install_action (widget_class, "clipboard.paste", NULL,
gtk_label_nop);
/**
* GtkLabel|selection.delete:
*
* Doesn't do anything, since text in labels can't be deleted.
*/
gtk_widget_class_install_action (widget_class, "selection.delete", NULL,
gtk_label_nop);
/**
* GtkLabel|selection.select-all:
*
* Selects all of the text, if the label allows selection.
*/
gtk_widget_class_install_action (widget_class, "selection.select-all", NULL,
gtk_label_activate_selection_select_all);
/**
* GtkLabel|link.open:
*
* Opens the link, when activated on a link inside the label.
*/
gtk_widget_class_install_action (widget_class, "link.open", NULL,
gtk_label_activate_link_open);
/**
* GtkLabel|link.copy:
*
* Copies the link to the clipboard, when activated on a link
* inside the label.
*/
gtk_widget_class_install_action (widget_class, "link.copy", NULL,
gtk_label_activate_link_copy);
}
......
......@@ -1046,6 +1046,14 @@ gtk_menu_button_set_create_popup_func (GtkMenuButton *menu_button
update_sensitivity (menu_button);
}
/**
* gtk_menu_button_set_use_underline:
* @menu_button: a #GtkMenuButton
* @use_underline: %TRUE if underlines in the text indicate mnemonics
*
* If true, an underline in the text indicates the next character should be
* used for the mnemonic accelerator key.
*/
void
gtk_menu_button_set_use_underline (GtkMenuButton *menu_button,
gboolean use_underline)
......@@ -1062,6 +1070,16 @@ gtk_menu_button_set_use_underline (GtkMenuButton *menu_button,
g_object_notify_by_pspec (G_OBJECT (menu_button), menu_button_props[PROP_USE_UNDERLINE]);
}
/**
* gtk_menu_button_get_use_underline:
* @menu_button: a #GtkMenuButton
*
* Returns whether an embedded underline in the text indicates a
* mnemonic. See gtk_menu_button_set_use_underline().
*
* Returns: %TRUE whether an embedded underline in the text indicates
* the mnemonic accelerator keys.
*/
gboolean
gtk_menu_button_get_use_underline (GtkMenuButton *menu_button)
{
......
......@@ -1741,12 +1741,29 @@ gtk_popover_class_init (GtkPopoverClass *klass)
gtk_widget_class_set_css_name (widget_class, "popover");
}
/**
* gtk_popover_new:
*
* Creates a new popover.
*
* Returns: the new popover
*/
GtkWidget *
gtk_popover_new (void)
{
return g_object_new (GTK_TYPE_POPOVER, NULL);
}
/**
* gtk_popover_set_default_widget:
* @popover: a #GtkPopover
* @widget: (allow-none): a child widget of @popover to set as
* the default, or %NULL to unset the default widget for the popover
*
* The default widget is the widget that’s activated when the user
* presses Enter in a dialog (for example). This function sets or
* unsets the default widget for a #GtkPopover.
*/
void
gtk_popover_set_default_widget (GtkPopover *popover,
GtkWidget *widget)
......
......@@ -601,7 +601,7 @@ gtk_popover_menu_new_from_model_full (GMenuModel *model,
}
/**
* gtk_popover_menu_set_model:
* gtk_popover_menu_set_menu_model:
* @popover: a #GtkPopoverMenu
* @model: (nullable): a #GtkMenuModel, or %NULL
*
......
......@@ -361,6 +361,14 @@ gtk_shortcut_set_trigger (GtkShortcut *self,
}
}
/**
* gtk_shortcut_get_arguments:
* @self: a #GtkShortcut
*
* Gets the arguments that are passed when activating the shortcut.
*
* Returns: (transfer none) (nullable): the arguments
*/
GVariant *
gtk_shortcut_get_arguments (GtkShortcut *self)
{
......@@ -369,6 +377,13 @@ gtk_shortcut_get_arguments (GtkShortcut *self)
return self->args;
}
/**
* gtk_shortcut_set_arguments:
* @self: a #GtkShortcut
* @args: (nullable): arguments to pass when activating @self
*
* Sets the arguments to pass when activating the shortcut.
*/
void
gtk_shortcut_set_arguments (GtkShortcut *self,
GVariant *args)
......
......@@ -85,7 +85,7 @@ window_handle_exported (GtkWindow *window,
* @uri: the uri to show
* @timestamp: timestamp from the event that triggered this call, or %GDK_CURRENT_TIME
* @cancellable: (nullable): a #GCancellable to cancel the launch
* @callback (scope async): a callback to call when the action is complete
* @callback: (scope async): a callback to call when the action is complete
* @user_data: (closure callback): data to pass to @callback
*
* This function launches the default application for showing
......
......@@ -1467,6 +1467,8 @@ _gtk_style_context_get_attributes (AtkAttributeSet *attributes,
* CSS nodes starting at the style context's node
* @GTK_STYLE_CONTEXT_PRINT_SHOW_STYLE: Show the values of the
* CSS properties for each node
* @GTK_STYLE_CONTEXT_PRINT_SHOW_CHANGE: Show information about
* what changes affect the styles
*
* Flags that modify the behavior of gtk_style_context_to_string().
* New values may be added to this enumeration.
......
......@@ -1216,7 +1216,7 @@ gtk_text_class_init (GtkTextClass *class)
gtk_text_activate_clipboard_copy);
/**
* GtkText|clipboard.copy:
* GtkText|clipboard.paste:
*
* Inserts the contents of the clipboard into the widget.
*/
......@@ -1247,6 +1247,11 @@ gtk_text_class_init (GtkTextClass *class)
gtk_widget_class_install_action (widget_class, "misc.insert-emoji", NULL,
gtk_text_activate_misc_insert_emoji);
/**
* GtkText|misc.toggle-visibility:
*
* Toggles the #GtkText:visibility property.
*/
gtk_widget_class_install_property_action (widget_class,
"misc.toggle-visibility",
"visibility");
......
......@@ -4941,6 +4941,14 @@ gtk_text_buffer_real_redo (GtkTextBuffer *buffer)
gtk_text_history_redo (buffer->priv->history);
}
/**
* gtk_text_buffer_get_can_undo:
* @buffer: a #GtkTextBuffer
*
* Gets whether there is an undoable action in the history.
*
* Returns: %TRUE if there is an undoable action
*/
gboolean
gtk_text_buffer_get_can_undo (GtkTextBuffer *buffer)
{
......@@ -4949,6 +4957,14 @@ gtk_text_buffer_get_can_undo (GtkTextBuffer *buffer)
return gtk_text_history_get_can_undo (buffer->priv->history);
}
/**
* gtk_text_buffer_get_can_redo:
* @buffer: a #GtkTextBuffer
*
* Gets whether there is a redoable action in the history.
*
* Returns: %TRUE if there is an redoable action
*/
gboolean
gtk_text_buffer_get_can_redo (GtkTextBuffer *buffer)
{
......@@ -5080,6 +5096,7 @@ gtk_text_buffer_get_enable_undo (GtkTextBuffer *buffer)
/**
* gtk_text_buffer_set_enable_undo:
* @buffer: a #GtkTextBuffer
* @enable_undo: %TRUE to enable undo
*
* Sets whether or not to enable undoable actions in the text buffer. If
* enabled, the user will be able to undo the last number of actions up to
......@@ -5091,13 +5108,13 @@ gtk_text_buffer_get_enable_undo (GtkTextBuffer *buffer)
*/
void
gtk_text_buffer_set_enable_undo (GtkTextBuffer *buffer,
gboolean enabled)
gboolean enable_undo)
{
g_return_if_fail (GTK_IS_TEXT_BUFFER (buffer));
if (enabled != gtk_text_history_get_enabled (buffer->priv->history))
if (enable_undo != gtk_text_history_get_enabled (buffer->priv->history))
{
gtk_text_history_set_enabled (buffer->priv->history, enabled);
gtk_text_history_set_enabled (buffer->priv->history, enable_undo);
g_object_notify_by_pspec (G_OBJECT (buffer),
text_buffer_props[PROP_ENABLE_UNDO]);
}
......
......@@ -318,7 +318,7 @@ free_style_cache (GtkTextLayout *text_layout)
}
}
/**
/*
* gtk_text_layout_set_buffer:
* @buffer: (allow-none):
*/
......@@ -724,7 +724,7 @@ gtk_text_layout_wrap (GtkTextLayout *layout,
}
/**
/*
* gtk_text_layout_get_lines:
*
* Returns: (element-type GtkTextLine) (transfer container):
......
......@@ -523,6 +523,15 @@ gtk_viewport_adjustment_value_changed (GtkAdjustment *adjustment,
gtk_widget_queue_allocate (GTK_WIDGET (data));
}
/**