Assorted documentation fixes

19 files changed, 242 insertions, 35 deletions

diff --git a/gtk/gtkaboutdialog.h b/gtk/gtkaboutdialog.h
index 5d0e560840..1624f4628f 100644
--- a/gtk/gtkaboutdialog.h
+++ b/gtk/gtkaboutdialog.h
@@ -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.
  *
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index b1be03fa9f..666c403a0f 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -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
  *
diff --git a/gtk/gtkcalendar.c b/gtk/gtkcalendar.c
index 0c524c3726..d60a55b24e 100644
--- a/gtk/gtkcalendar.c
+++ b/gtk/gtkcalendar.c
@@ -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)
diff --git a/gtk/gtkcenterlayout.c b/gtk/gtkcenterlayout.c
index b4d8a79fac..c9519f15b2 100644
--- a/gtk/gtkcenterlayout.c
+++ b/gtk/gtkcenterlayout.c
@@ -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 *
diff --git a/gtk/gtkemojichooser.c b/gtk/gtkemojichooser.c
index 3e1d65221d..e8a0d70353 100644
--- a/gtk/gtkemojichooser.c
+++ b/gtk/gtkemojichooser.c
@@ -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);
 
diff --git a/gtk/gtkeventcontroller.c b/gtk/gtkeventcontroller.c
index ad8a1b5991..37a048ec81 100644
--- a/gtk/gtkeventcontroller.c
+++ b/gtk/gtkeventcontroller.c
@@ -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)
diff --git a/gtk/gtkgesturelongpress.c b/gtk/gtkgesturelongpress.c
index 6475919974..4906abd2bf 100644
--- a/gtk/gtkgesturelongpress.c
+++ b/gtk/gtkgesturelongpress.c
@@ -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)
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 704e2894f3..6d2023ac60 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -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);
 }
diff --git a/gtk/gtkmenubutton.c b/gtk/gtkmenubutton.c
index b5d13d8556..7f36353236 100644
--- a/gtk/gtkmenubutton.c
+++ b/gtk/gtkmenubutton.c
@@ -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)
 {
diff --git a/gtk/gtkpopover.c b/gtk/gtkpopover.c
index 4a2893b324..ad0ec0f862 100644
--- a/gtk/gtkpopover.c
+++ b/gtk/gtkpopover.c
@@ -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)
diff --git a/gtk/gtkpopovermenu.c b/gtk/gtkpopovermenu.c
index 457153598f..b4a129e147 100644
--- a/gtk/gtkpopovermenu.c
+++ b/gtk/gtkpopovermenu.c
@@ -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
  *
diff --git a/gtk/gtkshortcut.c b/gtk/gtkshortcut.c
index 57a2a2ea3d..a32437fed9 100644
--- a/gtk/gtkshortcut.c
+++ b/gtk/gtkshortcut.c
@@ -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)
diff --git a/gtk/gtkshow.c b/gtk/gtkshow.c
index 066e9ccb55..f688f79ad2 100644
--- a/gtk/gtkshow.c
+++ b/gtk/gtkshow.c
@@ -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
diff --git a/gtk/gtkstylecontext.c b/gtk/gtkstylecontext.c
index 6474761939..821f5a9fdd 100644
--- a/gtk/gtkstylecontext.c
+++ b/gtk/gtkstylecontext.c
@@ -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.
diff --git a/gtk/gtktext.c b/gtk/gtktext.c
index 77ddeb488b..397c09b4d7 100644
--- a/gtk/gtktext.c
+++ b/gtk/gtktext.c
@@ -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");
diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c
index 7dd04c5e24..37f7f00b25 100644
--- a/gtk/gtktextbuffer.c
+++ b/gtk/gtktextbuffer.c
@@ -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]);
     }
diff --git a/gtk/gtktextlayout.c b/gtk/gtktextlayout.c
index a646151f29..0719dcb222 100644
--- a/gtk/gtktextlayout.c
+++ b/gtk/gtktextlayout.c
@@ -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):
diff --git a/gtk/gtkviewport.c b/gtk/gtkviewport.c
index 64011d1f3f..d03a7f1fda 100644
--- a/gtk/gtkviewport.c
+++ b/gtk/gtkviewport.c
@@ -523,6 +523,15 @@ gtk_viewport_adjustment_value_changed (GtkAdjustment *adjustment,
   gtk_widget_queue_allocate (GTK_WIDGET (data));
 }
 
+/**
+ * gtk_viewport_get_scroll_to_focus:
+ * @viewport: a #GtkViewport
+ *
+ * Gets whether the viewport is scrolling to keep the focused
+ * child in view. See gtk_viewport_set_scroll_to_focus().
+ *
+ * Returns: %TRUE if the viewport keeps the focus child scrolled to view
+ */
 gboolean
 gtk_viewport_get_scroll_to_focus (GtkViewport *viewport)
 {
@@ -533,6 +542,14 @@ gtk_viewport_get_scroll_to_focus (GtkViewport *viewport)
   return priv->scroll_to_focus;
 }
 
+/**
+ * gtk_viewport_set_scroll_to_focus:
+ * @viewport: a #GtkViewport
+ * @scroll_to_focus: whether to keep the focus widget scrolled to view
+ *
+ * Sets whether the viewport should automatically scroll
+ * to keep the focused child in view.
+ */
 void
 gtk_viewport_set_scroll_to_focus (GtkViewport *viewport,
                                   gboolean     scroll_to_focus)
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 307f516f14..c715411ebc 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -12335,7 +12335,7 @@ gtk_widget_class_add_action (GtkWidgetClass  *widget_class,
   priv->actions = action;
 }
 
-/*
+/**
  * gtk_widget_class_install_action:
  * @widget_class: a #GtkWidgetClass
  * @action_name: a prefixed action name, such as "clipboard.paste"
@@ -12409,11 +12409,18 @@ determine_type (GParamSpec *pspec)
  * Installs an action called @action_name on @widget_class and binds its
  * state to the value of the @property_name property.
  *
- * This function will perform a few santity checks on the property selected via
- * @property_name. Namely, the property must exist, must be readable, writable and
- * must not be construct-only. There are also certain restrictions on the type of
- * the given property. If any of these conditions are not met, a critical
+ * This function will perform a few santity checks on the property selected
+ * via @property_name. Namely, the property must exist, must be readable,
+ * writable and must not be construct-only. There are also restrictions
+ * on the type of the given property, it must be boolean, int, unsigned int,
+ * double or string. If any of these conditions are not met, a critical
  * warning will be printed and no action will be added.
+ *
+ * The state type of the action matches the property type.
+ *
+ * If the property is boolean, the action will have no parameter and
+ * toggle the property value. Otherwise, the action will have a parameter
+ * of the same type as the property.
  */
 void
 gtk_widget_class_install_property_action (GtkWidgetClass *widget_class,