docs: Miscellaneous doc fixes

Additions and correction all over the place,
in GDK and GTK docs.

27 files changed, 221 insertions, 54 deletions

diff --git a/docs/reference/gdk/gdk4-sections.txt b/docs/reference/gdk/gdk4-sections.txt
index 75824dfef8..88b2cd60aa 100644
--- a/docs/reference/gdk/gdk4-sections.txt
+++ b/docs/reference/gdk/gdk4-sections.txt
@@ -213,6 +213,7 @@ gdk_surface_get_pass_through
 gdk_surface_move
 gdk_surface_resize
 gdk_surface_move_resize
+gdk_surface_move_to_rect
 gdk_surface_has_native
 gdk_surface_raise
 gdk_surface_lower
@@ -374,6 +375,7 @@ gdk_content_formats_builder_to_formats
 GDK_TYPE_FILE_LIST
 gdk_file_list_get_type
 gdk_content_formats_get_type
+gdk_content_formats_builder_get_type
 </SECTION>
 
 <SECTION>
@@ -439,6 +441,7 @@ gdk_keymap_get_modifier_state
 gdk_keymap_add_virtual_modifiers
 gdk_keymap_map_virtual_modifiers
 gdk_keymap_get_modifier_mask
+gdk_keymap_get_display
 
 <SUBSECTION>
 gdk_keyval_name
@@ -619,6 +622,7 @@ GDK_BUTTON_SECONDARY
 gdk_event_new
 gdk_event_copy
 gdk_event_get_axes
+gdk_event_get_axis
 gdk_event_get_button
 gdk_event_get_click_count
 gdk_event_get_coords
@@ -681,6 +685,7 @@ GDK_TYPE_SCROLL_DIRECTION
 GDK_TYPE_NOTIFY_TYPE
 GDK_IS_EVENT
 gdk_event_get_type
+gdk_event_sequence_get_type
 </SECTION>
 
 <SECTION>
@@ -776,7 +781,6 @@ GDK_ACTION_ALL
 
 gdk_drag_get_display
 gdk_drag_get_actions
-gdk_drag_get_suggested_action
 gdk_drag_get_selected_action
 gdk_drag_get_formats
 gdk_drag_get_device
diff --git a/docs/reference/gdk/meson.build b/docs/reference/gdk/meson.build
index 57f93a9637..6df0882ec7 100644
--- a/docs/reference/gdk/meson.build
+++ b/docs/reference/gdk/meson.build
@@ -15,7 +15,9 @@ private_headers = [
   'gdkdisplaymanagerprivate.h',
   'gdkdisplayprivate.h',
   'gdkdndprivate.h',
+  'gdkdragprivate.h',
   'gdkdrawcontextprivate.h',
+  'gdkdropprivate.h',
   'gdkeventsprivate.h',
   'gdkframeclockidleprivate.h',
   'gdkframeclockprivate.h',
diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml
index fc3705cad5..d530df9878 100644
--- a/docs/reference/gtk/gtk4-docs.xml
+++ b/docs/reference/gtk/gtk4-docs.xml
@@ -68,6 +68,7 @@
 
     <chapter id="WindowWidgets">
       <title>Windows</title>
+      <xi:include href="xml/gtkroot.xml" />
       <xi:include href="xml/gtkwindow.xml" />
       <xi:include href="xml/gtkdialog.xml" />
       <xi:include href="xml/gtkmessagedialog.xml" />
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 6aa9d56f95..151be6a9bb 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -675,12 +675,6 @@ gtk_combo_box_new
 gtk_combo_box_new_with_entry
 gtk_combo_box_new_with_model
 gtk_combo_box_new_with_model_and_entry
-gtk_combo_box_get_wrap_width
-gtk_combo_box_set_wrap_width
-gtk_combo_box_get_row_span_column
-gtk_combo_box_set_row_span_column
-gtk_combo_box_get_column_span_column
-gtk_combo_box_set_column_span_column
 gtk_combo_box_get_active
 gtk_combo_box_set_active
 gtk_combo_box_get_active_iter
@@ -695,6 +689,7 @@ gtk_combo_box_popdown
 gtk_combo_box_get_popup_accessible
 gtk_combo_box_get_row_separator_func
 gtk_combo_box_set_row_separator_func
+GtkSensitivityType
 gtk_combo_box_set_button_sensitivity
 gtk_combo_box_get_button_sensitivity
 gtk_combo_box_get_has_entry
@@ -2279,11 +2274,6 @@ gtk_range_set_increments
 gtk_range_set_range
 gtk_range_get_round_digits
 gtk_range_set_round_digits
-GtkSensitivityType
-gtk_range_set_lower_stepper_sensitivity
-gtk_range_get_lower_stepper_sensitivity
-gtk_range_set_upper_stepper_sensitivity
-gtk_range_get_upper_stepper_sensitivity
 gtk_range_get_flippable
 gtk_range_set_flippable
 gtk_range_get_range_rect
@@ -4398,6 +4388,7 @@ gtk_snapshot_push_clip
 gtk_snapshot_push_rounded_clip
 gtk_snapshot_push_cross_fade
 gtk_snapshot_push_blend
+gtk_snapshot_push_debug
 gtk_snapshot_pop
 gtk_snapshot_save
 gtk_snapshot_restore
@@ -4491,6 +4482,7 @@ gtk_widget_set_parent
 gtk_widget_set_parent_surface
 gtk_widget_get_parent_surface
 gtk_widget_get_toplevel
+gtk_widget_get_root
 gtk_widget_get_ancestor
 gtk_widget_is_ancestor
 gtk_widget_translate_coordinates
@@ -7184,3 +7176,12 @@ gtk_media_stream_error_valist
 GTK_TYPE_MEDIA_STREAM
 gtk_media_stream_get_type
 </SECTION>
+
+<SECTION>
+<FILE>gtkroot</FILE>
+<TITLE>GtkRoot</TITLE>
+GtkRoot
+gtk_root_get_for_surface
+<SUBSECTION Private>
+gtk_root_get_type
+</SECTION>
diff --git a/docs/reference/gtk/gtk4.types.in b/docs/reference/gtk/gtk4.types.in
index c7301ed750..9bf0f4ced0 100644
--- a/docs/reference/gtk/gtk4.types.in
+++ b/docs/reference/gtk/gtk4.types.in
@@ -137,6 +137,7 @@ gtk_radio_tool_button_get_type
 gtk_range_get_type
 gtk_recent_manager_get_type
 gtk_revealer_get_type
+gtk_root_get_type
 gtk_scale_button_get_type
 gtk_scale_get_type
 gtk_scrollable_get_type
diff --git a/gtk/gtkaccellabel.c b/gtk/gtkaccellabel.c
index e8a0ba6121..92090faaf2 100644
--- a/gtk/gtkaccellabel.c
+++ b/gtk/gtkaccellabel.c
@@ -1076,9 +1076,11 @@ gtk_accel_label_set_use_underline (GtkAccelLabel *accel_label,
  * gtk_accel_label_get_use_underline:
  * @accel_label: a #GtkAccelLabel
  *
- * Returns: Whether the accel label interprets underscores in it's
- * GtkAccelLabel:label property as mnemonic indicators.
+ * Returns whether the accel label interprets underscores in it's
+ * label property as mnemonic indicators.
  * See gtk_accel_label_set_use_underline() and gtk_label_set_use_underline();
+ *
+ * Returns: whether the accel label uses mnemonic underlines
  */
 gboolean
 gtk_accel_label_get_use_underline (GtkAccelLabel *accel_label)
diff --git a/gtk/gtkcheckbutton.c b/gtk/gtkcheckbutton.c
index 1be4a1e3a8..bda29bf7e8 100644
--- a/gtk/gtkcheckbutton.c
+++ b/gtk/gtkcheckbutton.c
@@ -557,8 +557,9 @@ gtk_check_button_set_inconsistent (GtkCheckButton *check_button,
  * gtk_check_button_get_inconsistent:
  * @check_button: a #GtkCheckButton
  *
- * Returns: %TRUE if @check_button is currently in an 'in between' state,
- *   %FALSE otherwise.
+ * Returns whether the check button is in an inconsistent state.
+ * 
+ * Returns: %TRUE if @check_button is currently in an 'in between' state, %FALSE otherwise.
  */
 gboolean
 gtk_check_button_get_inconsistent (GtkCheckButton *check_button)
diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c
index d392846523..f710d51cc0 100644
--- a/gtk/gtkeditable.c
+++ b/gtk/gtkeditable.c
@@ -516,6 +516,7 @@ gtk_editable_get_text (GtkEditable *editable)
 /**
  * gtk_editable_set_text:
  * @editable: a #GtkEditable
+ * @text: the text to set
  *
  * Sets the text in the editable to the given value,
  * replacing the current contents.
@@ -911,7 +912,7 @@ gtk_editable_finish_delegate (GtkEditable *editable)
 }
 
 /**
- * gtk_editable_set_property:
+ * gtk_editable_delegate_set_property:
  * @object: a #GObject
  * @prop_id: a property ID
  * @value: value to set
@@ -969,7 +970,7 @@ gtk_editable_delegate_set_property (GObject      *object,
 }
 
 /**
- * gtk_editable_get_property:
+ * gtk_editable_delegate_get_property:
  * @object: a #GObject
  * @prop_id: a property ID
  * @value: value to set
diff --git a/gtk/gtkeventcontrollerlegacy.c b/gtk/gtkeventcontrollerlegacy.c
index b3c8c62398..661c81be72 100644
--- a/gtk/gtkeventcontrollerlegacy.c
+++ b/gtk/gtkeventcontrollerlegacy.c
@@ -17,7 +17,20 @@
  * Author(s): Carlos Garnacho <carlosg@gnome.org>
  */
 
+/**
+ * SECTION:gtkeventcontrollerlegacy
+ * @Short_description: Event controller for miscellaneous events
+ * @Title: GtkEventControllerLegacy
+ * @See_also: #GtkEventController
+ *
+ * #GtkEventControllerLegacy is an event controller that gives you
+ * direct access to the event stream. It should only be used as a
+ * last resort if none of the other event controllers or gestures
+ * do the job.
+ **/
+
 #include "config.h"
+
 #include "gtkeventcontrollerlegacy.h"
 #include "gtkeventcontrollerprivate.h"
 #include "gtkmarshalers.h"
@@ -67,11 +80,10 @@ gtk_event_controller_legacy_class_init (GtkEventControllerLegacyClass *klass)
    * @controller: the object which received the signal.
    * @event: the #GdkEvent which triggered this signal
    *
-   * The GTK+ main loop will emit this signal for each GDK event delivered
-   * to @controller.
+   * Emitted for each GDK event delivered to @controller.
    *
    * Returns: %TRUE to stop other handlers from being invoked for the event
-   * and the emission of this signal. %FALSE to propagate the event further.
+   *    and the emission of this signal. %FALSE to propagate the event further.
    */
   signals[EVENT] =
     g_signal_new (I_("event"),
@@ -91,6 +103,13 @@ gtk_event_controller_legacy_init (GtkEventControllerLegacy *controller)
 {
 }
 
+/**
+ * gtk_event_controller_legacy_new:
+ *
+ * Creates a new legacy event controller.
+ *
+ * Returns: the newly created event controller.
+ */
 GtkEventController *
 gtk_event_controller_legacy_new (void)
 {
diff --git a/gtk/gtkfilterlistmodel.c b/gtk/gtkfilterlistmodel.c
index 8f515b5b9c..493c893f32 100644
--- a/gtk/gtkfilterlistmodel.c
+++ b/gtk/gtkfilterlistmodel.c
@@ -28,7 +28,7 @@
 /**
  * SECTION:gtkfilterlistmodel
  * @title: GtkFilterListModel
- * @short_description: a #GListModel that filters its items
+ * @short_description: A list model that filters its items
  * @see_also: #GListModel
  *
  * #GtkFilterListModel is a list model that filters a given other
diff --git a/gtk/gtkflattenlistmodel.c b/gtk/gtkflattenlistmodel.c
index c8d5118c9b..614493e28f 100644
--- a/gtk/gtkflattenlistmodel.c
+++ b/gtk/gtkflattenlistmodel.c
@@ -28,7 +28,7 @@
 /**
  * SECTION:gtkflattenlistmodel
  * @title: GtkFlattenListModel
- * @short_description: a #GListModel that flattens a given listmodel
+ * @short_description: A list model that flattens a list of lists
  * @see_also: #GListModel
  *
  * #GtkFlattenListModel is a list model that takes a list model containing
diff --git a/gtk/gtkimcontextsimple.c b/gtk/gtkimcontextsimple.c
index 1c738bf103..730f4bac0a 100644
--- a/gtk/gtkimcontextsimple.c
+++ b/gtk/gtkimcontextsimple.c
@@ -1476,7 +1476,7 @@ gtk_im_context_simple_add_table (GtkIMContextSimple *context_simple,
   G_UNLOCK (global_tables);
 }
 
-/*
+/**
  * gtk_im_context_simple_add_compose_file:
  * @context_simple: A #GtkIMContextSimple
  * @compose_file: The path of compose file
diff --git a/gtk/gtkinfobar.c b/gtk/gtkinfobar.c
index f6497bbac0..2631fbc624 100644
--- a/gtk/gtkinfobar.c
+++ b/gtk/gtkinfobar.c
@@ -1151,7 +1151,9 @@ gtk_info_bar_set_revealed (GtkInfoBar *info_bar,
  * gtk_info_bar_get_revealed:
  * @info_bar: a #GtkInfoBar
  *
- * Returns: the current value of the #GtkInfoBar:revealed property.
+ * Returns whether the info bar is currently revealed.
+ *
+ * Returns: the current value of the #GtkInfoBar:revealed property
  */
 gboolean
 gtk_info_bar_get_revealed (GtkInfoBar *info_bar)
diff --git a/gtk/gtkmaplistmodel.c b/gtk/gtkmaplistmodel.c
index 1fbf526f58..7d998d89ff 100644
--- a/gtk/gtkmaplistmodel.c
+++ b/gtk/gtkmaplistmodel.c
@@ -28,8 +28,7 @@
 /**
  * SECTION:gtkmaplistmodel
  * @title: GtkMapListModel
- * @short_description: a #GListModel that maps items from a child list model to
- *     a different item
+ * @short_description: A list model that transforms its items
  * @see_also: #GListModel
  *
  * #GtkMapListModel is a list model that takes a list model and maps the items
diff --git a/gtk/gtkmediastream.c b/gtk/gtkmediastream.c
index e6529041f7..b402f136df 100644
--- a/gtk/gtkmediastream.c
+++ b/gtk/gtkmediastream.c
@@ -614,7 +614,7 @@ gtk_media_stream_set_playing (GtkMediaStream *self,
 }
 
 /**
- * gtk_medai_stream_get_ended:
+ * gtk_media_stream_get_ended:
  * @self: a #GtkMediaStream
  *
  * Returns whether the streams playback is finished.
diff --git a/gtk/gtkoverlay.c b/gtk/gtkoverlay.c
index 4770c78057..643ca00d2e 100644
--- a/gtk/gtkoverlay.c
+++ b/gtk/gtkoverlay.c
@@ -771,7 +771,7 @@ gtk_overlay_set_clip_overlay (GtkOverlay *overlay,
 }
 
 /**
- * gtk_overlay_get_overlay_clip_overlay:
+ * gtk_overlay_get_clip_overlay:
  * @overlay: a #GtkOverlay
  * @widget: an overlay child of #GtkOverlay
  *
diff --git a/gtk/gtkpasswordentry.c b/gtk/gtkpasswordentry.c
index 78f12b0d62..8b2a022e88 100644
--- a/gtk/gtkpasswordentry.c
+++ b/gtk/gtkpasswordentry.c
@@ -36,12 +36,17 @@
 #include "a11y/gtkentryaccessible.h"
 
 /**
- * SECTION:gtkpasswordhentry
+ * SECTION:gtkpasswordentry
  * @Short_description: An entry for secrets
  * @Title: GtkPasswordEntry
  *
  * #GtkPasswordEntry is entry that has been tailored for
- * entering secrets.
+ * entering secrets. It does not show its contents in clear text,
+ * does not allow to copy it to the clipboard, and it shows a
+ * warning when Caps-Lock is engaged.
+ *
+ * GtkPasswordEntry provides no API of its own and should be used
+ * with the #GtkEditable API.
  */
 
 typedef struct {
diff --git a/gtk/gtkrange.h b/gtk/gtkrange.h
index 33c521f5a0..60787e195a 100644
--- a/gtk/gtkrange.h
+++ b/gtk/gtkrange.h
@@ -120,17 +120,6 @@ void               gtk_range_get_slider_range              (GtkRange      *range
                                                             gint          *slider_end);
 
 GDK_AVAILABLE_IN_ALL
-void               gtk_range_set_lower_stepper_sensitivity (GtkRange      *range,
-                                                            GtkSensitivityType sensitivity);
-GDK_AVAILABLE_IN_ALL
-GtkSensitivityType gtk_range_get_lower_stepper_sensitivity (GtkRange      *range);
-GDK_AVAILABLE_IN_ALL
-void               gtk_range_set_upper_stepper_sensitivity (GtkRange      *range,
-                                                            GtkSensitivityType sensitivity);
-GDK_AVAILABLE_IN_ALL
-GtkSensitivityType gtk_range_get_upper_stepper_sensitivity (GtkRange      *range);
-
-GDK_AVAILABLE_IN_ALL
 void               gtk_range_set_increments                (GtkRange      *range,
                                                             gdouble        step,
                                                             gdouble        page);
diff --git a/gtk/gtkroot.c b/gtk/gtkroot.c
index 103502dbc6..ad93f8791a 100644
--- a/gtk/gtkroot.c
+++ b/gtk/gtkroot.c
@@ -23,9 +23,9 @@
 #include "gdk/gdk-private.h"
 
 /**
- * SECTION:root
+ * SECTION:gtkroot
  * @Title: GtkRoot
- * @Short_description: Root widgets
+ * @Short_description: Interface for root widgets
  * @See_also: #GtkWindow
  *
  * #GtkRoot is the interface implemented by all widgets that can act as a toplevel
diff --git a/gtk/gtkselectionmodel.c b/gtk/gtkselectionmodel.c
index cc0823d1c6..8d29f395c6 100644
--- a/gtk/gtkselectionmodel.c
+++ b/gtk/gtkselectionmodel.c
@@ -41,7 +41,7 @@
  * A #GtkSelectionModel supports a single boolean per row indicating if a row is selected
  * or not. This can be queried via gtk_selection_model_is_selected(). When the selected
  * state of one or more rows changes, the model will emit the
- * GtkSelectionModel::selection-changed signal by calling the
+ * #GtkSelectionModel::selection-changed signal by calling the
  * gtk_selection_model_selection_changed() function. The positions given in that signal
  * may have their selection state changed, though that is not a requirement.  
  * If new items added to the model via the #GListModel::items-changed signal are selected
@@ -57,6 +57,7 @@
  * selection functions do NOT indicate if selection or unselection happened. They are
  * only meant to indicate complete failure, like when this mode of selecting is not
  * supported by the model.
+ *
  * Selections may happen asynchronously, so the only reliable way to find out when an
  * item was selected is to listen to the signals that indicate selection.
  */
@@ -201,6 +202,14 @@ gtk_selection_model_is_selected (GtkSelectionModel *model,
   return iface->is_selected (model, position);
 }
 
+/**
+ * gtk_selection_model_select_item:
+ * @model: a #GtkSelectionModel
+ * @position: the position of the item to select
+ * @exclusive: whether previously selected items should be unselected
+ *
+ * Requests to select an item in the model.
+ */
 gboolean
 gtk_selection_model_select_item (GtkSelectionModel *model,
                                  guint              position,
@@ -214,6 +223,13 @@ gtk_selection_model_select_item (GtkSelectionModel *model,
   return iface->select_item (model, position, exclusive);
 }
 
+/**
+ * gtk_selection_model_unselect_item:
+ * @model: a #GtkSelectionModel
+ * @position: the position of the item to unselect
+ *
+ * Requests to unselect an item in the model.
+ */
 gboolean
 gtk_selection_model_unselect_item (GtkSelectionModel *model,
                                    guint              position)
@@ -226,6 +242,15 @@ gtk_selection_model_unselect_item (GtkSelectionModel *model,
   return iface->unselect_item (model, position);
 }
 
+/**
+ * gtk_selection_model_select_range:
+ * @model: a #GtkSelectionModel
+ * @position: the first item to select
+ * @n_items: the number of items to select
+ * @exclusive: whether previously selected items should be unselected
+ *
+ * Requests to select a range of items in the model.
+ */
 gboolean
 gtk_selection_model_select_range (GtkSelectionModel *model,
                                   guint              position,
@@ -240,6 +265,14 @@ gtk_selection_model_select_range (GtkSelectionModel *model,
   return iface->select_range (model, position, n_items, exclusive);
 }
 
+/**
+ * gtk_selection_model_unselect_range:
+ * @model: a #GtkSelectionModel
+ * @position: the first item to unselect
+ * @n_items: the number of items to unselect
+ *
+ * Requests to unselect a range of items in the model.
+ */
 gboolean
 gtk_selection_model_unselect_range (GtkSelectionModel *model,
                                     guint              position,
@@ -253,6 +286,12 @@ gtk_selection_model_unselect_range (GtkSelectionModel *model,
   return iface->unselect_range (model, position, n_items);
 }
 
+/**
+ * gtk_selection_model_select_all:
+ * @model: a #GtkSelectionModel
+ *
+ * Requests to select all items in the model.
+ */
 gboolean
 gtk_selection_model_select_all (GtkSelectionModel *model)
 {
@@ -264,6 +303,12 @@ gtk_selection_model_select_all (GtkSelectionModel *model)
   return iface->select_all (model);
 }
 
+/**
+ * gtk_selection_model_unselect_all:
+ * @model: a #GtkSelectionModel
+ *
+ * Requests to unselect all items in the model.
+ */
 gboolean
 gtk_selection_model_unselect_all (GtkSelectionModel *model)
 {
@@ -315,6 +360,16 @@ gtk_selection_model_query_range (GtkSelectionModel *model,
   return iface->query_range (model, position, start_range, n_items, selected);
 }
 
+/**
+ * gtk_selection_model_selection_changed:
+ * @model: a #GtkSelectionModel
+ * @position: the first changed item
+ * @n_items: the number of changed items
+ *
+ * Helper function for implementations of #GtkSelectionModel.
+ * Call this when a the selection changes to emit the ::selection-changed
+ * signal.
+ */
 void
 gtk_selection_model_selection_changed (GtkSelectionModel *model,
                                        guint              position,
diff --git a/gtk/gtkslicelistmodel.c b/gtk/gtkslicelistmodel.c
index 753807fa6f..a6aa4f3b7f 100644
--- a/gtk/gtkslicelistmodel.c
+++ b/gtk/gtkslicelistmodel.c
@@ -27,7 +27,7 @@
 /**
  * SECTION:gtkslicelistmodel
  * @title: GtkSliceListModel
- * @short_description: a #GListModel that presents a slice out of a larger list
+ * @short_description: A list model that presents a slice out of a larger list
  * @see_also: #GListModel
  *
  * #GtkSliceListModel is a list model that takes a list model and presents a slice of
diff --git a/gtk/gtksnapshot.c b/gtk/gtksnapshot.c
index 318024f59f..0f2973d4a3 100644
--- a/gtk/gtksnapshot.c
+++ b/gtk/gtksnapshot.c
@@ -300,6 +300,16 @@ gtk_snapshot_collect_debug (GtkSnapshot      *snapshot,
   return debug_node;
 }
 
+/**
+ * gtk_snapshot_push_debug:
+ * @snapshot: a #GtkSnapshot
+ * @message: a printf-style format string
+ * @...: arguments for @message
+ *
+ * Inserts a debug node with a message. Debug nodes don't affect
+ * the rendering at all, but can be helpful in identifying parts
+ * of a render node tree dump, for example in the GTK inspector.
+ */
 void
 gtk_snapshot_push_debug (GtkSnapshot *snapshot,
                          const char  *message,
@@ -356,6 +366,15 @@ gtk_snapshot_collect_opacity (GtkSnapshot      *snapshot,
   return opacity_node;
 }
 
+/**
+ * gtk_snapshot_push_opacity:
+ * @snapshot: a #GtkSnapshot
+ * @opacity: the opacity to use
+ *
+ * Modifies the opacity of an image.
+ *
+ * The image is recorded until the next call to gtk_snapshot_pop().
+ */
 void
 gtk_snapshot_push_opacity (GtkSnapshot *snapshot,
                            double       opacity)
@@ -394,6 +413,15 @@ gtk_snapshot_collect_blur (GtkSnapshot      *snapshot,
   return blur_node;
 }
 
+/**
+ * gtk_snapshot_push_blur:
+ * @snapshot: a #GtkSnapshot
+ * @radius: the blur radius to use
+ *
+ * Blurs an image.
+ *
+ * The image is recorded until the next call to gtk_snapshot_pop().
+ */
 void
 gtk_snapshot_push_blur (GtkSnapshot *snapshot,
                         double       radius)
@@ -458,6 +486,17 @@ gtk_snapshot_collect_color_matrix (GtkSnapshot      *snapshot,
   return color_matrix_node;
 }
 
+/**
+ * gtk_snapshot_push_color_matrix:
+ * @snapshot: a #GtkSnapshot
+ * @color_matrix: the color matrix to use
+ * @color_offset: the color offset to use
+ *
+ * Modifies the colors of an image by applying an affine transformation
+ * in RGB space.
+ *
+ * The image is recorded until the next call to gtk_snapshot_pop().
+ */
 void
 gtk_snapshot_push_color_matrix (GtkSnapshot             *snapshot,
                                 const graphene_matrix_t *color_matrix,
@@ -631,6 +670,15 @@ gtk_snapshot_collect_clip (GtkSnapshot      *snapshot,
   return clip_node;
 }
 
+/**
+ * gtk_snapshot_push_clip:
+ * @snapshot: a #GtkSnapshot
+ * @bounds: the rectangle to clip to
+ *
+ * Clips an image to a rectangle.
+ *
+ * The image is recorded until the next call to gtk_snapshot_pop().
+ */
 void
 gtk_snapshot_push_clip (GtkSnapshot           *snapshot,
                         const graphene_rect_t *bounds)
@@ -689,6 +737,15 @@ gtk_snapshot_collect_rounded_clip (GtkSnapshot      *snapshot,
   return clip_node;
 }
 
+/**
+ * gtk_snapshot_push_rounded_clip:
+ * @snapshot: a #GtkSnapshot
+ * @bounds: the rounded rectangle to clip to
+ *
+ * Clips an image to a rounded rectangle.
+ *
+ * The image is recorded until the next call to gtk_snapshot_pop().
+ */
 void
 gtk_snapshot_push_rounded_clip (GtkSnapshot          *snapshot,
                                 const GskRoundedRect *bounds)
@@ -729,6 +786,16 @@ gtk_snapshot_collect_shadow (GtkSnapshot      *snapshot,
   return shadow_node;
 }
 
+/**
+ * gtk_snapshot_push_shadow:
+ * @snapshot: a #GtkSnapshot
+ * @shadow: the first shadow specification
+ * @n_shadows: number of shadow specifications
+ *
+ * Applies a shadow to an image.
+ *
+ * The image is recorded until the next call to gtk_snapshot_pop().
+ */
 void
 gtk_snapshot_push_shadow (GtkSnapshot     *snapshot,
                           const GskShadow *shadow,
@@ -1171,7 +1238,7 @@ gtk_snapshot_restore (GtkSnapshot *snapshot)
 /**
  * gtk_snapshot_transform:
  * @snapshot: a #GtkSnapshot
- * @tranform: (allow-none): the transform to apply
+ * @transform: (allow-none): the transform to apply
  *
  * Transforms @snapshot's coordinate system with the given @transform.
  **/
@@ -1222,7 +1289,7 @@ gtk_snapshot_transform_matrix_with_category (GtkSnapshot             *snapshot,
 }
 
 /**
- * gtk_snapshot_transform_translate:
+ * gtk_snapshot_translate:
  * @snapshot: a #GtkSnapshot
  * @point: the point to translate the snapshot by
  *
@@ -1242,7 +1309,7 @@ gtk_snapshot_translate (GtkSnapshot            *snapshot,
 }
 
 /**
- * gtk_snapshot_transform_translate_3d:
+ * gtk_snapshot_translate_3d:
  * @snapshot: a #GtkSnapshot
  * @point: the point to translate the snapshot by
  *
@@ -1262,7 +1329,7 @@ gtk_snapshot_translate_3d (GtkSnapshot              *snapshot,
 }
 
 /**
- * gtk_snapshot_transform_rotate:
+ * gtk_snapshot_rotate:
  * @snapshot: a #GtkSnapshot
  * @angle: the rotation angle, in degrees (clockwise)
  *
@@ -1282,7 +1349,7 @@ gtk_snapshot_rotate (GtkSnapshot *snapshot,
 }
 
 /**
- * gtk_snapshot_transform_rotate_3d:
+ * gtk_snapshot_rotate_3d:
  * @snapshot: a #GtkSnapshot
  * @angle: the rotation angle, in degrees (clockwise)
  * @axis: The rotation axis
diff --git a/gtk/gtksortlistmodel.c b/gtk/gtksortlistmodel.c
index 4b9fa64acf..4a3b09dde3 100644
--- a/gtk/gtksortlistmodel.c
+++ b/gtk/gtksortlistmodel.c
@@ -27,7 +27,7 @@
 /**
  * SECTION:gtksortlistmodel
  * @title: GtkSortListModel
- * @short_description: a #GListModel that sorts a listmodel
+ * @short_description: A list model that sorts its items
  * @see_also: #GListModel
  *
  * #GtkSortListModel is a list model that takes a list model and
diff --git a/gtk/gtkspinbutton.c b/gtk/gtkspinbutton.c
index 280a324305..83a66831df 100644
--- a/gtk/gtkspinbutton.c
+++ b/gtk/gtkspinbutton.c
@@ -2221,6 +2221,8 @@ gtk_spin_button_update (GtkSpinButton *spin_button)
  * gtk_spin_button_get_text:
  * @spin_button: a #GtkSpinButton
  *
+ * Returns the text shown in the entry.
+ *
  * Returns: (transfer none): The current text shown in the entry area of @spin_button.
  */
 const char *
diff --git a/gtk/gtktransform.c b/gtk/gtktransform.c
index f114b69bfe..db15668d37 100644
--- a/gtk/gtktransform.c
+++ b/gtk/gtktransform.c
@@ -19,7 +19,7 @@
 
 
 /**
- * SECTION:GtkTransform
+ * SECTION:gtktransform
  * @Title: GtkTransform
  * @Short_description: A description for transform operations
  *
diff --git a/gtk/gtktreelistmodel.c b/gtk/gtktreelistmodel.c
index f74d61f6d9..333b8b70e6 100644
--- a/gtk/gtktreelistmodel.c
+++ b/gtk/gtktreelistmodel.c
@@ -27,7 +27,7 @@
 
 /**
  * SECTION:gtktreelistmodel
- * @Short_description: a List model that can create child models on demand
+ * @Short_description: A list model that can create child models on demand
  * @Title: GtkTreeListModel
  * @See_also: #GListModel
  *
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index b782022d6f..9f61ec5448 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -13593,6 +13593,14 @@ gtk_widget_get_cursor (GtkWidget *widget)
   return priv->cursor;
 }
 
+/**
+ * gtk_widget_set_can_pick:
+ * @widget: a #GtkWidget
+ * @can_pick: whether this widget should be able to receive pointer events
+ *
+ * Sets whether @widget can be the target of pointer events and
+ * can be returned by gtk_widget_pick().
+ */
 void
 gtk_widget_set_can_pick (GtkWidget *widget,
                          gboolean   can_pick)
@@ -13609,6 +13617,14 @@ gtk_widget_set_can_pick (GtkWidget *widget,
   g_object_notify_by_pspec (G_OBJECT (widget), widget_props[PROP_CAN_PICK]);
 }
 
+/**
+ * gtk_widget_get_can_pick:
+ * @widget: a #GtkWidget
+ * 
+ * Queries whether @widget can be the target of pointer events.
+ * 
+ * Returns: %TRUE if @widget can receive pointer events
+ */
 gboolean
 gtk_widget_get_can_pick (GtkWidget *widget)
 {