Merge branch 'ebassi/docs-for-master' into 'master'

Ebassi/docs for master

See merge request GNOME/gtk!2960

23 files changed, 397 insertions, 24 deletions

diff --git a/docs/reference/gdk/gdk4-sections.txt b/docs/reference/gdk/gdk4-sections.txt
index 22c4646caf..2c82ab8d92 100644
--- a/docs/reference/gdk/gdk4-sections.txt
+++ b/docs/reference/gdk/gdk4-sections.txt
@@ -1,4 +1,3 @@
-
 <INCLUDE>gdk/gdk.h</INCLUDE>
 
 <SECTION>
@@ -29,8 +28,9 @@ GDK_TYPE_GRAB_STATUS
 GDK_TYPE_STATUS
 GdkStatus
 GDKVAR
-GDK_VERSION_3_92
-GDK_VERSION_3_94
+GDK_EXTERN_VAR
+_GDK_EXTERN
+GDK_DECLARE_INTERNAL_TYPE
 gdk_axis_use_get_type
 gdk_byte_order_get_type
 gdk_crossing_mode_get_type
@@ -375,6 +375,7 @@ gdk_device_tool_get_hardware_id
 gdk_device_tool_get_axes
 
 <SUBSECTION Standard>
+GDK_TYPE_AXIS_FLAGS
 GDK_TYPE_AXIS_USE
 GDK_TYPE_EXTENSION_MODE
 GDK_TYPE_INPUT_MODE
@@ -447,6 +448,7 @@ gdk_seat_capabilities_get_type
 <FILE>events</FILE>
 GdkEvent
 GdkEventType
+GdkKeymapKey
 GdkKeyMatch
 GdkTouchpadGesturePhase
 GdkScrollDirection
@@ -482,10 +484,14 @@ gdk_event_get_axis
 gdk_event_get_history
 gdk_event_get_pointer_emulated
 gdk_event_triggers_context_menu
+GdkButtonEvent
 gdk_button_event_get_button
+GdkScrollEvent
 gdk_scroll_event_get_direction
 gdk_scroll_event_get_deltas
 gdk_scroll_event_is_stop
+GdkMotionEvent
+GdkKeyEvent
 gdk_key_event_get_keyval
 gdk_key_event_get_keycode
 gdk_key_event_get_consumed_modifiers
@@ -494,22 +500,31 @@ gdk_key_event_get_level
 gdk_key_event_is_modifier
 gdk_key_event_matches
 gdk_key_event_get_match
+GdkFocusEvent
 gdk_focus_event_get_in
 gdk_touch_event_get_emulating_pointer
+GdkCrossingEvent
 gdk_crossing_event_get_mode
 gdk_crossing_event_get_detail
 gdk_crossing_event_get_focus
+GdkGrabBrokenEvent
 gdk_grab_broken_event_get_grab_surface
 gdk_grab_broken_event_get_implicit
+GdkDeleteEvent
+GdkDNDEvent
 gdk_dnd_event_get_drop
+GdkTouchEvent
+GdkTouchpadEvent
 gdk_touchpad_event_get_gesture_phase
 gdk_touchpad_event_get_n_fingers
 gdk_touchpad_event_get_deltas
 gdk_touchpad_event_get_pinch_angle_delta
 gdk_touchpad_event_get_pinch_scale
+GdkPadEvent
 gdk_pad_event_get_axis_value
 gdk_pad_event_get_button
 gdk_pad_event_get_group_mode
+GdkProximityEvent
 
 <SUBSECTION>
 gdk_events_get_angle
@@ -517,6 +532,7 @@ gdk_events_get_center
 gdk_events_get_distance
 
 <SUBSECTION Standard>
+GDK_EVENT
 GDK_TYPE_EVENT
 GDK_TYPE_EVENT_MASK
 GDK_TYPE_EVENT_TYPE
@@ -524,6 +540,20 @@ GDK_TYPE_CROSSING_MODE
 GDK_TYPE_SCROLL_DIRECTION
 GDK_TYPE_NOTIFY_TYPE
 GDK_IS_EVENT
+GDK_IS_EVENT_TYPE
+GDK_TYPE_BUTTON_EVENT
+GDK_TYPE_CROSSING_EVENT
+GDK_TYPE_DELETE_EVENT
+GDK_TYPE_DND_EVENT
+GDK_TYPE_FOCUS_EVENT
+GDK_TYPE_GRAB_BROKEN_EVENT
+GDK_TYPE_KEY_EVENT
+GDK_TYPE_MOTION_EVENT
+GDK_TYPE_PAD_EVENT
+GDK_TYPE_PROXIMITY_EVENT
+GDK_TYPE_SCROLL_EVENT
+GDK_TYPE_TOUCH_EVENT
+GDK_TYPE_TOUCHPAD_EVENT
 
 gdk_event_get_type
 gdk_event_sequence_get_type
@@ -1173,6 +1203,10 @@ GdkCairoContext
 gdk_cairo_context_cairo_create
 
 <SUBSECTION Standard>
+GDK_CAIRO_CONTEXT
+GDK_IS_CAIRO_CONTEXT
+GDK_TYPE_CAIRO_CONTEXT
+GDK_CAIRO_ERROR
 gdk_cairo_context_get_type
 </SECTION>
 
@@ -1192,6 +1226,11 @@ gdk_vulkan_context_get_queue
 gdk_vulkan_context_get_queue_family_index
 
 <SUBSECTION Standard>
+GDK_VULKAN_CONTEXT
+GDK_IS_VULKAN_CONTEXT
+GDK_TYPE_VULKAN_CONTEXT
+GDK_RENDERING_VULKAN
+GDK_VULKAN_ERROR
 gdk_vulkan_context_get_type
 gdk_vulkan_error_quark
 gdk_vulkan_strerror
diff --git a/docs/reference/gdk/meson.build b/docs/reference/gdk/meson.build
index be256e9175..c895131a3d 100644
--- a/docs/reference/gdk/meson.build
+++ b/docs/reference/gdk/meson.build
@@ -45,10 +45,13 @@ private_headers = [
   'gdktoplevelprivate.h',
   'gdktoplevelsizeprivate.h',
   'gdkvulkancontextprivate.h',
+
   'filetransferportalprivate.h',
+  'gdkconstructor.h',
   'keyname-table.h',
 
   # gdk/x11
+  'gdkasync.h',
   'gdkcairocontext-x11.h',
   'gdkclipboard-x11.h',
   'gdkdevice-xi2-private.h',
diff --git a/docs/reference/gsk/gsk4-sections.txt b/docs/reference/gsk/gsk4-sections.txt
index e18975b64d..78d5bb0a10 100644
--- a/docs/reference/gsk/gsk4-sections.txt
+++ b/docs/reference/gsk/gsk4-sections.txt
@@ -20,6 +20,40 @@ GSK_TYPE_RENDERER
 GskRendererClass
 gsk_renderer_get_type
 GSK_TYPE_SCALING_FILTER
+GSK_BROADWAY_RENDERER
+GSK_BROADWAY_RENDERER_CLASS
+GSK_BROADWAY_RENDERER_GET_CLASS
+GSK_IS_BROADWAY_RENDERER
+GSK_IS_BROADWAY_RENDERER_CLASS
+GSK_TYPE_BROADWAY_RENDERER
+GskBroadwayRenderer
+GskBroadwayRendererClass
+GSK_CAIRO_RENDERER
+GSK_CAIRO_RENDERER_CLASS
+GSK_CAIRO_RENDERER_GET_CLASS
+GSK_IS_CAIRO_RENDERER
+GSK_IS_CAIRO_RENDERER_CLASS
+GSK_TYPE_CAIRO_RENDERER
+GskCairoRenderer
+GskCairoRendererClass
+GSK_GL_RENDERER
+GSK_GL_RENDERER_CLASS
+GSK_GL_RENDERER_GET_CLASS
+GSK_IS_GL_RENDERER
+GSK_IS_GL_RENDERER_CLASS
+GSK_TYPE_GL_RENDERER
+GskGLRenderer
+GskGLRendererClass
+gsk_gl_renderer_get_type
+GSK_VULKAN_RENDERER
+GSK_VULKAN_RENDERER_CLASS
+GSK_VULKAN_RENDERER_GET_CLASS
+GSK_IS_VULKAN_RENDERER
+GSK_IS_VULKAN_RENDERER_CLASS
+GSK_TYPE_VULKAN_RENDERER
+GskVulkanRenderer
+GskVulkanRendererClass
+gsk_vulkan_renderer_get_type
 </SECTION>
 
 <SECTION>
@@ -180,11 +214,14 @@ GSK_TYPE_CONTAINER_NODE
 GSK_TYPE_CONIC_GRADIENT_NODE
 GSK_TYPE_CROSS_FADE_NODE
 GSK_TYPE_DEBUG_NODE
+GSK_TYPE_GL_SHADER_NODE
 GSK_TYPE_INSET_SHADOW_NODE
 GSK_TYPE_LINEAR_GRADIENT_NODE
 GSK_TYPE_OPACITY_NODE
 GSK_TYPE_OUTSET_SHADOW_NODE
+GSK_TYPE_RADIAL_GRADIENT_NODE
 GSK_TYPE_REPEATING_LINEAR_GRADIENT_NODE
+GSK_TYPE_REPEATING_RADIAL_GRADIENT_NODE
 GSK_TYPE_REPEAT_NODE
 GSK_TYPE_ROUNDED_CLIP_NODE
 GSK_TYPE_SHADOW_NODE
@@ -192,6 +229,7 @@ GSK_TYPE_TEXT_NODE
 GSK_TYPE_TEXTURE_NODE
 GSK_TYPE_TRANSFORM_NODE
 GSK_TYPE_GLSHADER_NODE
+GSK_TYPE_RENDER_NODE_TYPE
 GskRenderNodeClass
 gsk_blend_node_get_type
 gsk_blur_node_get_type
@@ -243,6 +281,8 @@ gsk_rounded_rect_is_rectilinear
 gsk_rounded_rect_contains_point
 gsk_rounded_rect_contains_rect
 gsk_rounded_rect_intersects_rect
+<SUBSECTION Standard>
+GSK_TYPE_CORNER
 </SECTION>
 
 <SECTION>
@@ -331,5 +371,8 @@ gsk_shader_args_builder_set_vec3
 gsk_shader_args_builder_set_vec4
 
 <SUBSECTION Private>
+GSK_TYPE_GL_SHADER
+GSK_TYPE_GL_UNIFORM_TYPE
+GSK_TYPE_SHADER_ARGS_BUILDER
 gsk_shader_args_builder_get_type
 </SECTION>
diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index 635c23d6fd..ad134ee06f 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -1011,7 +1011,6 @@ gtk_editable_label_get_type
 <FILE>gtktext</FILE>
 <TITLE>GtkText</TITLE>
 GtkText
-GtkTextClass
 gtk_text_new
 gtk_text_new_with_buffer
 gtk_text_set_buffer
@@ -1143,8 +1142,6 @@ gtk_password_entry_set_show_peek_icon
 gtk_password_entry_get_show_peek_icon
 gtk_password_entry_set_extra_menu
 gtk_password_entry_get_extra_menu
-gtk_password_entry_get_text_widget
-gtk_password_entry_toggle_peek
 <SUBSECTION Private>
 gtk_password_entry_get_type
 </SECTION>
@@ -2639,9 +2636,7 @@ GtkSorterOrder
 GtkSorterChange
 gtk_sorter_compare
 gtk_sorter_get_order
-gtk_sorter_get_keys
 gtk_sorter_changed
-gtk_sorter_changed_with_keys
 <SUBSECTION Standard>
 GTK_SORTER
 GTK_IS_SORTER
@@ -2797,7 +2792,6 @@ gtk_spin_button_get_climb_rate
 gtk_spin_button_configure
 gtk_spin_button_spin
 gtk_spin_button_update
-gtk_spin_button_get_text_widget
 GTK_INPUT_ERROR
 <SUBSECTION Standard>
 GTK_SPIN_BUTTON
@@ -5513,7 +5507,6 @@ gtk_test_accessible_assert_property
 gtk_test_accessible_assert_relation
 gtk_test_accessible_assert_role
 gtk_test_accessible_assert_state
-gtk_test_accessible_assertion_message_role
 gtk_test_accessible_check_property
 gtk_test_accessible_check_relation
 gtk_test_accessible_check_state
@@ -5521,6 +5514,8 @@ gtk_test_accessible_has_property
 gtk_test_accessible_has_relation
 gtk_test_accessible_has_role
 gtk_test_accessible_has_state
+<SECTION Private>
+gtk_test_accessible_assertion_message_role
 </SECTION>
 
 <SECTION>
diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index 67fbaf55cb..cdd53d61e8 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -193,6 +193,7 @@ private_headers = [
   'gtknomediafileprivate.h',
   'gtkpango.h',
   'gtkpasswordentrybufferprivate.h',
+  'gtkpasswordentryprivate.h',
   'gtkpathbar.h',
   'gdkpixbufutilsprivate.h',
   'gtkplacessidebarprivate.h',
@@ -237,7 +238,9 @@ private_headers = [
   'gtksizegroup-private.h',
   'gtksizerequestcacheprivate.h',
   'gtksnapshotprivate.h',
+  'gtksorterprivate.h',
   'gtksortkeysprivate.h',
+  'gtkspinbuttonprivate.h',
   'gtkstyleanimationprivate.h',
   'gtkstylecascadeprivate.h',
   'gtkstylecontextprivate.h',
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index 30dee67dcd..141a95a283 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -1314,6 +1314,12 @@ gdk_event_get_position (GdkEvent *event,
 
 /* {{{ GdkButtonEvent */
 
+/**
+ * GdkButtonEvent:
+ *
+ * An event related to a button on a pointer device/
+ */
+
 static void
 gdk_button_event_finalize (GdkEvent *event)
 {
@@ -1438,6 +1444,12 @@ gdk_button_event_get_button (GdkEvent *event)
 
 /* {{{ GdkKeyEvent */
 
+/**
+ * GdkKeyEvent:
+ *
+ * An event related to a key-based device.
+ */
+
 static GdkModifierType
 gdk_key_event_get_state (GdkEvent *event)
 {
@@ -1819,6 +1831,12 @@ gdk_key_event_get_match (GdkEvent        *event,
 
 /* {{{ GdkTouchEvent */
 
+/**
+ * GdkTouchEvent:
+ *
+ * An event related to a touch-based device.
+ */
+
 static void
 gdk_touch_event_finalize (GdkEvent *event)
 {
@@ -1950,6 +1968,12 @@ gdk_touch_event_get_emulating_pointer (GdkEvent *event)
 
 /* {{{ GdkCrossingEvent */
 
+/**
+ * GdkCrossingEvent:
+ *
+ * An event caused by a pointing device moving between surfaces.
+ */
+
 static void
 gdk_crossing_event_finalize (GdkEvent *event)
 {
@@ -2088,6 +2112,12 @@ gdk_crossing_event_get_detail (GdkEvent *event)
 
 /* {{{ GdkDeleteEvent */
 
+/**
+ * GdkDeleteEvent:
+ *
+ * An event related to closing a top-level surface.
+ */
+
 static const GdkEventTypeInfo gdk_delete_event_info = {
   sizeof (GdkDeleteEvent),
   NULL,
@@ -2113,6 +2143,12 @@ gdk_delete_event_new (GdkSurface *surface)
 
 /* {{{ GdkFocusEvent */
 
+/**
+ * GdkFocusEvent:
+ *
+ * An event related to a focus change.
+ */
+
 static const GdkEventTypeInfo gdk_focus_event_info = {
   sizeof (GdkFocusEvent),
   NULL,
@@ -2164,6 +2200,12 @@ gdk_focus_event_get_in (GdkEvent *event)
 
 /* {{{ GdkScrollEvent */
 
+/**
+ * GdkScrollEvent:
+ *
+ * An event related to a scrolling motion.
+ */
+
 static void
 gdk_scroll_event_finalize (GdkEvent *event)
 {
@@ -2321,6 +2363,12 @@ gdk_scroll_event_is_stop (GdkEvent *event)
 
 /* {{{ GdkTouchpadEvent */
 
+/**
+ * GdkTouchpadEvent:
+ *
+ * An event related to a touchpad device.
+ */
+
 static GdkModifierType
 gdk_touchpad_event_get_state (GdkEvent *event)
 {
@@ -2517,6 +2565,12 @@ gdk_touchpad_event_get_pinch_scale (GdkEvent *event)
 
 /* {{{ GdkPadEvent */
 
+/**
+ * GdkPadEvent:
+ *
+ * An event related to a pad-based device.
+ */
+
 static const GdkEventTypeInfo gdk_pad_event_info = {
   sizeof (GdkPadEvent),
   NULL,
@@ -2685,6 +2739,12 @@ gdk_pad_event_get_group_mode (GdkEvent *event,
 
 /* {{{ GdkMotionEvent */
 
+/**
+ * GdkMotionEvent:
+ *
+ * An event related to a pointer or touch device motion.
+ */
+
 static void
 gdk_motion_event_finalize (GdkEvent *event)
 {
@@ -2839,6 +2899,12 @@ gdk_event_get_history (GdkEvent *event,
 
 /* {{{ GdkProximityEvent */
 
+/**
+ * GdkProximityEvent:
+ *
+ * An event related to the proximity of a tool to a device.
+ */
+
 static void
 gdk_proximity_event_finalize (GdkEvent *event)
 {
@@ -2896,6 +2962,12 @@ gdk_proximity_event_new (GdkEventType   type,
 
 /* {{{ GdkDNDEvent */
 
+/**
+ * GdkDNDEvent:
+ *
+ * An event related to drag and drop operations.
+ */
+
 static void
 gdk_dnd_event_finalize (GdkEvent *event)
 {
@@ -2996,6 +3068,12 @@ gdk_dnd_event_get_drop (GdkEvent *event)
 
 /* {{{ GdkGrabBrokenEvent */
 
+/**
+ * GdkGrabBrokenEvent:
+ *
+ * An event related to a broken windowing system grab.
+ */
+
 static const GdkEventTypeInfo gdk_grab_broken_event_info = {
   sizeof (GdkGrabBrokenEvent),
   NULL,
diff --git a/gdk/gdkversionmacros.h.in b/gdk/gdkversionmacros.h.in
index c315f33a45..3c6d6fbf05 100644
--- a/gdk/gdkversionmacros.h.in
+++ b/gdk/gdkversionmacros.h.in
@@ -24,8 +24,25 @@
 
 #include <glib.h>
 
+/**
+ * GDK_MAJOR_VERSION:
+ *
+ * The major version component of the library's version, e.g. "1" for "1.2.3".
+ */
 #define GDK_MAJOR_VERSION (@GTK_MAJOR_VERSION@)
+
+/**
+ * GDK_MINOR_VERSION:
+ *
+ * The minor version component of the library's version, e.g. "2" for "1.2.3".
+ */
 #define GDK_MINOR_VERSION (@GTK_MINOR_VERSION@)
+
+/**
+ * GDK_MICRO_VERSION:
+ *
+ * The micro version component of the library's version, e.g. "3" for "1.2.3".
+ */
 #define GDK_MICRO_VERSION (@GTK_MICRO_VERSION@)
 
 #ifndef _GDK_EXTERN
diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c
index 1315d8878b..e5fccf927c 100644
--- a/gtk/gtkcellrenderer.c
+++ b/gtk/gtkcellrenderer.c
@@ -1691,6 +1691,13 @@ gtk_cell_renderer_get_state (GtkCellRenderer      *cell,
   return state;
 }
 
+/**
+ * gtk_cell_renderer_set_is_expander:
+ * @cell: a #GtkCellRenderer
+ * @is_expander: whether @cell is an expander
+ *
+ * Sets whether the given #GtkCellRenderer is an expander.
+ */
 void
 gtk_cell_renderer_set_is_expander (GtkCellRenderer *cell,
                                    gboolean         is_expander)
@@ -1709,6 +1716,14 @@ gtk_cell_renderer_set_is_expander (GtkCellRenderer *cell,
     }
 }
 
+/**
+ * gtk_cell_renderer_get_is_expander:
+ * @cell: a #GtkCellRenderer
+ *
+ * Checks whether the given #GtkCellRenderer is an expander.
+ *
+ * Returns: %TRUE if @cell is an expander, and %FALSE otherwise
+ */
 gboolean
 gtk_cell_renderer_get_is_expander (GtkCellRenderer *cell)
 {
@@ -1719,6 +1734,13 @@ gtk_cell_renderer_get_is_expander (GtkCellRenderer *cell)
   return priv->is_expander;
 }
 
+/**
+ * gtk_cell_renderer_set_is_expanded:
+ * @cell: a #GtkCellRenderer
+ * @is_expanded: whether @cell should be expanded
+ *
+ * Sets whether the given #GtkCellRenderer is expanded.
+ */
 void
 gtk_cell_renderer_set_is_expanded (GtkCellRenderer *cell,
                                    gboolean         is_expanded)
@@ -1737,6 +1759,14 @@ gtk_cell_renderer_set_is_expanded (GtkCellRenderer *cell,
     }
 }
 
+/**
+ * gtk_cell_renderer_get_is_expanded:
+ * @cell: a #GtkCellRenderer
+ *
+ * Checks whether the given #GtkCellRenderer is expanded.
+ *
+ * Returns: %TRUE if the cell renderer is expanded
+ */
 gboolean
 gtk_cell_renderer_get_is_expanded (GtkCellRenderer *cell)
 {
diff --git a/gtk/gtkcellrenderer.h b/gtk/gtkcellrenderer.h
index 6eb53587e9..ca59826a02 100644
--- a/gtk/gtkcellrenderer.h
+++ b/gtk/gtkcellrenderer.h
@@ -280,7 +280,7 @@ gboolean         gtk_cell_renderer_get_is_expander (GtkCellRenderer     *cell);
 
 GDK_AVAILABLE_IN_ALL
 void             gtk_cell_renderer_set_is_expanded (GtkCellRenderer     *cell,
-                                                    gboolean             is_expander);
+                                                    gboolean             is_expanded);
 GDK_AVAILABLE_IN_ALL
 gboolean         gtk_cell_renderer_get_is_expanded (GtkCellRenderer     *cell);
 
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index e96fe4506f..2626a2ffc7 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -975,7 +975,7 @@ gtk_entry_class_init (GtkEntryClass *class)
   gtk_editable_install_properties (gobject_class, PROP_EDITING_CANCELED + 1);
 
   /**
-   * GtkEntry:activate:
+   * GtkEntry::activate:
    * @self: The widget on which the signal is emitted
    *
    * The ::activate signal is forwarded from the
diff --git a/gtk/gtkexpander.c b/gtk/gtkexpander.c
index bbe08fcced..16adad8f44 100644
--- a/gtk/gtkexpander.c
+++ b/gtk/gtkexpander.c
@@ -369,6 +369,12 @@ gtk_expander_class_init (GtkExpanderClass *klass)
                                                         GTK_TYPE_WIDGET,
                                                         GTK_PARAM_READWRITE));
 
+  /**
+   * GtkExpander::activate:
+   * @expander: the #GtkExpander that emitted the signal
+   *
+   * Activates the #GtkExpander.
+   */
   activate_signal =
     g_signal_new (I_("activate"),
                   G_TYPE_FROM_CLASS (gobject_class),
diff --git a/gtk/gtkgesturestylus.c b/gtk/gtkgesturestylus.c
index c1b7a51109..bd6238f3a8 100644
--- a/gtk/gtkgesturestylus.c
+++ b/gtk/gtkgesturestylus.c
@@ -24,7 +24,8 @@
  * @See_also: #GtkGesture, #GtkGestureSingle
  *
  * #GtkGestureStylus is a #GtkGesture implementation specific to stylus
- * input. The provided signals just provide the basic information
+ * input. The provided signals just relay the basic information of the
+ * stylus events.
  */
 
 #include "config.h"
@@ -94,6 +95,14 @@ gtk_gesture_stylus_class_init (GtkGestureStylusClass *klass)
   event_controller_class = GTK_EVENT_CONTROLLER_CLASS (klass);
   event_controller_class->handle_event = gtk_gesture_stylus_handle_event;
 
+  /**
+   * GtkGestureStylus::proximity:
+   * @gesture: the #GtkGestureStylus that emitted the signal
+   * @x: the X coordinate of the stylus event
+   * @y: the Y coordinate of the stylus event
+   *
+   * A signal emitted when the stylus is in proximity of the device.
+   */
   signals[PROXIMITY] =
     g_signal_new (I_("proximity"),
                   G_TYPE_FROM_CLASS (klass),
@@ -106,6 +115,14 @@ gtk_gesture_stylus_class_init (GtkGestureStylusClass *klass)
                               G_TYPE_FROM_CLASS (klass),
                               _gtk_marshal_VOID__DOUBLE_DOUBLEv);
 
+  /**
+   * GtkGestureStylus::down:
+   * @gesture: the #GtkGestureStylus that emitted the signal
+   * @x: the X coordinate of the stylus event
+   * @y: the Y coordinate of the stylus event
+   *
+   * A signal emitted when the stylus touches the device.
+   */
   signals[DOWN] =
     g_signal_new (I_("down"),
                   G_TYPE_FROM_CLASS (klass),
@@ -118,6 +135,14 @@ gtk_gesture_stylus_class_init (GtkGestureStylusClass *klass)
                               G_TYPE_FROM_CLASS (klass),
                               _gtk_marshal_VOID__DOUBLE_DOUBLEv);
 
+  /**
+   * GtkGestureStylus::motion:
+   * @gesture: the #GtkGestureStylus that emitted the signal
+   * @x: the X coordinate of the stylus event
+   * @y: the Y coordinate of the stylus event
+   *
+   * A signal emitted when the stylus moves while touching the device.
+   */
   signals[MOTION] =
     g_signal_new (I_("motion"),
                   G_TYPE_FROM_CLASS (klass),
@@ -130,6 +155,14 @@ gtk_gesture_stylus_class_init (GtkGestureStylusClass *klass)
                               G_TYPE_FROM_CLASS (klass),
                               _gtk_marshal_VOID__DOUBLE_DOUBLEv);
 
+  /**
+   * GtkGestureStylus::up:
+   * @gesture: the #GtkGestureStylus that emitted the signal
+   * @x: the X coordinate of the stylus event
+   * @y: the Y coordinate of the stylus event
+   *
+   * A signal emitted when the stylus no longer touches the device.
+   */
   signals[UP] =
     g_signal_new (I_("up"),
                   G_TYPE_FROM_CLASS (klass),
@@ -178,12 +211,13 @@ gesture_get_current_event (GtkGestureStylus *gesture)
  * @axis: requested device axis
  * @value: (out): return location for the axis value
  *
- * Returns the current value for the requested @axis. This function
- * must be called from either the #GtkGestureStylus::down,
- * #GtkGestureStylus::motion, #GtkGestureStylus::up or #GtkGestureStylus::proximity
- * signals.
+ * Returns the current value for the requested @axis.
+ *
+ * This function must be called from the handler of one of the
+ * #GtkGestureStylus::down, #GtkGestureStylus::motion,
+ * #GtkGestureStylus::up or #GtkGestureStylus::proximity signals.
  *
- * Returns: #TRUE if there is a current value for the axis
+ * Returns: %TRUE if there is a current value for the axis
  **/
 gboolean
 gtk_gesture_stylus_get_axis (GtkGestureStylus *gesture,
@@ -214,7 +248,7 @@ gtk_gesture_stylus_get_axis (GtkGestureStylus *gesture,
  * #GtkGestureStylus::motion, #GtkGestureStylus::up or #GtkGestureStylus::proximity
  * signals.
  *
- * Returns: #TRUE if there is a current value for the axes
+ * Returns: %TRUE if there is a current value for the axes
  **/
 gboolean
 gtk_gesture_stylus_get_axes (GtkGestureStylus  *gesture,
@@ -272,9 +306,9 @@ gtk_gesture_stylus_get_axes (GtkGestureStylus  *gesture,
  * gtk_gesture_stylus_get_axis() call express the latest (most up-to-date)
  * state in motion history.
  *
- * @backlog is provided in chronological order.
+ * The @backlog is provided in chronological order.
  *
- * Returns: #TRUE if there is a backlog to unfold in the current state.
+ * Returns: %TRUE if there is a backlog to unfold in the current state.
  **/
 gboolean
 gtk_gesture_stylus_get_backlog (GtkGestureStylus  *gesture,
diff --git a/gtk/gtknative.c b/gtk/gtknative.c
index 00dfd35820..1f6ed48f3a 100644
--- a/gtk/gtknative.c
+++ b/gtk/gtknative.c
@@ -119,6 +119,12 @@ verify_priv_unrealized (gpointer user_data)
   g_free (priv);
 }
 
+/**
+ * gtk_native_realize:
+ * @self: a #GtkNative
+ *
+ * Realizes a #GtkNative.
+ */
 void
 gtk_native_realize (GtkNative *self)
 {
@@ -146,6 +152,12 @@ gtk_native_realize (GtkNative *self)
                            verify_priv_unrealized);
 }
 
+/**
+ * gtk_native_unrealize:
+ * @self: a #GtkNative
+ *
+ * Unrealizes a #GtkNative.
+ */
 void
 gtk_native_unrealize (GtkNative *self)
 {
diff --git a/gtk/gtknativedialog.h b/gtk/gtknativedialog.h
index 09f8546f19..a4e75680d4 100644
--- a/gtk/gtknativedialog.h
+++ b/gtk/gtknativedialog.h
@@ -32,10 +32,18 @@ G_BEGIN_DECLS
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_DERIVABLE_TYPE (GtkNativeDialog, gtk_native_dialog, GTK, NATIVE_DIALOG, GObject)
 
+/**
+ * GtkNativeDialogClass:
+ * @response: class handler for the #GtkNativeDialog::response signal
+ *
+ * Class structure for #GtkNativeDialog.
+ */
 struct _GtkNativeDialogClass
 {
+  /*< private >*/
   GObjectClass parent_class;
 
+  /*< public >*/
   void (* response) (GtkNativeDialog *self, int response_id);
 
   /* <private> */
diff --git a/gtk/gtknotebook.h b/gtk/gtknotebook.h
index d02e384e74..d219f78c42 100644
--- a/gtk/gtknotebook.h
+++ b/gtk/gtknotebook.h
@@ -44,8 +44,22 @@ G_BEGIN_DECLS
 #define GTK_NOTEBOOK_PAGE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_NOTEBOOK_PAGE, GtkNotebookPage))
 #define GTK_IS_NOTEBOOK_PAGE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_NOTEBOOK_PAGE))
 
+/**
+ * GtkNotebookPage:
+ *
+ * A page in the #GtkNotebook.
+ *
+ * The `GtkNotebookPage` structure only contains private data.
+ */
 typedef struct _GtkNotebookPage GtkNotebookPage;
 
+/**
+ * GtkNotebookTab:
+ * @GTK_NOTEBOOK_TAB_FIRST: the first tab in the notebook
+ * @GTK_NOTEBOOK_TAB_LAST: the last tab in the notebook
+ *
+ * The parameter used in the action signals of #GtkNotebook.
+ */
 typedef enum
 {
   GTK_NOTEBOOK_TAB_FIRST,
diff --git a/gtk/gtkpasswordentry.c b/gtk/gtkpasswordentry.c
index 1babb6a2f7..36b2a187ec 100644
--- a/gtk/gtkpasswordentry.c
+++ b/gtk/gtkpasswordentry.c
@@ -528,6 +528,14 @@ gtk_password_entry_accessible_init (GtkAccessibleInterface *iface)
   iface->get_platform_state = gtk_password_entry_accessible_get_platform_state;
 }
 
+/*< private >
+ * gtk_password_entry_get_text_widget
+ * @entry: a #GtkPasswordEntry
+ *
+ * Retrieves the #GtkText delegate of the #GtkPasswordEntry.
+ *
+ * Returns: (transfer none): the #GtkText delegate widget
+ */
 GtkText *
 gtk_password_entry_get_text_widget (GtkPasswordEntry *entry)
 {
diff --git a/gtk/gtkpopover.c b/gtk/gtkpopover.c
index 5d8a01266d..c087f58dc5 100644
--- a/gtk/gtkpopover.c
+++ b/gtk/gtkpopover.c
@@ -577,6 +577,12 @@ present_popup (GtkPopover *popover)
   return FALSE;
 }
 
+/**
+ * gtk_popover_present:
+ * @popover: a #GtkPopover
+ *
+ * Presents the popover to the user.
+ */
 void
 gtk_popover_present (GtkPopover *popover)
 {
diff --git a/gtk/gtksearchentry.c b/gtk/gtksearchentry.c
index 5fc31bf9e4..48bdf5a9f4 100644
--- a/gtk/gtksearchentry.c
+++ b/gtk/gtksearchentry.c
@@ -302,7 +302,7 @@ gtk_search_entry_class_init (GtkSearchEntryClass *klass)
   gtk_editable_install_properties (object_class, NUM_PROPERTIES);
 
   /**
-   * GtkSearchEntry:activate:
+   * GtkSearchEntry::activate:
    * @self: The widget on which the signal is emitted
    *
    * The ::activate signal is forwarded from the
diff --git a/gtk/gtkstatusbar.c b/gtk/gtkstatusbar.c
index addb48eef4..e997a69c5f 100644
--- a/gtk/gtkstatusbar.c
+++ b/gtk/gtkstatusbar.c
@@ -489,6 +489,14 @@ gtk_statusbar_remove_all (GtkStatusbar *statusbar,
     }
 }
 
+/**
+ * gtk_statusbar_get_message:
+ * @statusbar: a #GtkStatusbar
+ *
+ * Retrieves the contents of the label in #GtkStatusbar.
+ *
+ * Returns: (transfer none): the contents of the statusbar
+ */
 const char *
 gtk_statusbar_get_message (GtkStatusbar *statusbar)
 {
diff --git a/gtk/gtktestatcontext.c b/gtk/gtktestatcontext.c
index 27ad90da67..601be1144e 100644
--- a/gtk/gtktestatcontext.c
+++ b/gtk/gtktestatcontext.c
@@ -114,6 +114,16 @@ gtk_test_at_context_new (GtkAccessibleRole  accessible_role,
                        NULL);
 }
 
+/**
+ * gtk_test_accessible_has_role:
+ * @accessible: a #GtkAccessible
+ * @role: a #GtkAccessibleRole
+ *
+ * Checks whether the #GtkAccessible:accessible-role of the accessible
+ * is @role.
+ *
+ * Returns: %TRUE if the role matches
+ */
 gboolean
 gtk_test_accessible_has_role (GtkAccessible     *accessible,
                               GtkAccessibleRole  role)
@@ -123,6 +133,15 @@ gtk_test_accessible_has_role (GtkAccessible     *accessible,
   return gtk_accessible_get_accessible_role (accessible) == role;
 }
 
+/**
+ * gtk_test_accessible_has_property:
+ * @accessible: a #GtkAccessible
+ * @property: a #GtkAccessibleProperty
+ *
+ * Checks whether the #GtkAccessible has @property set.
+ *
+ * Returns: %TRUE if the @property is set in the @accessible
+ */
 gboolean
 gtk_test_accessible_has_property (GtkAccessible         *accessible,
                                   GtkAccessibleProperty  property)
@@ -190,6 +209,15 @@ out:
   return res;
 }
 
+/**
+ * gtk_test_accessible_has_state:
+ * @accessible: a #GtkAccessible
+ * @state: a #GtkAccessibleState
+ *
+ * Checks whether the #GtkAccessible has @state set.
+ *
+ * Returns: %TRUE if the @state is set in the @accessible
+ */
 gboolean
 gtk_test_accessible_has_state (GtkAccessible      *accessible,
                                GtkAccessibleState  state)
@@ -257,6 +285,15 @@ out:
   return res;
 }
 
+/**
+ * gtk_test_accessible_has_relation:
+ * @accessible: a #GtkAccessible
+ * @relation: a #GtkAccessibleRelation
+ *
+ * Checks whether the #GtkAccessible has @relation set.
+ *
+ * Returns: %TRUE if the @relation is set in the @accessible
+ */
 gboolean
 gtk_test_accessible_has_relation (GtkAccessible         *accessible,
                                   GtkAccessibleRelation  relation)
@@ -324,6 +361,19 @@ out:
   return res;
 }
 
+/*< private >
+ * gtk_test_accessible_assertion_message_role:
+ * @domain: a domain
+ * @file: a file name
+ * @line: the line in @file
+ * @func: a function name in @file
+ * @expr: the expression being tested
+ * @accessible: a #GtkAccessible
+ * @expected_role: the expected #GtkAccessibleRole
+ * @actual_role: the actual #GtkAccessibleRole
+ *
+ * Prints an assertion message for gtk_test_accessible_assert_role().
+ */
 void
 gtk_test_accessible_assertion_message_role (const char        *domain,
                                             const char        *file,
diff --git a/gtk/gtktextiter.h b/gtk/gtktextiter.h
index d47f0cfba2..c2ffd35c20 100644
--- a/gtk/gtktextiter.h
+++ b/gtk/gtktextiter.h
@@ -355,6 +355,17 @@ GDK_AVAILABLE_IN_ALL
 gboolean gtk_text_iter_backward_to_tag_toggle (GtkTextIter *iter,
                                                GtkTextTag  *tag);
 
+/**
+ * GtkTextCharPredicate:
+ * @ch: a Unicode code point
+ * @user_data: data passed to the callback
+ *
+ * The predicate function used by gtk_text_iter_forward_find_char() and
+ * gtk_text_iter_backward_find_char().
+ *
+ * Returns: %TRUE if the predicate is satisfied, and the iteration should
+ *   stop, and %FALSE otherwise
+ */
 typedef gboolean (* GtkTextCharPredicate) (gunichar ch, gpointer user_data);
 
 GDK_AVAILABLE_IN_ALL
diff --git a/gtk/gtktreeviewcolumn.c b/gtk/gtktreeviewcolumn.c
index f224182192..e321bed4b6 100644
--- a/gtk/gtktreeviewcolumn.c
+++ b/gtk/gtktreeviewcolumn.c
@@ -257,7 +257,13 @@ gtk_tree_view_column_class_init (GtkTreeViewColumnClass *class)
   object_class->dispose = gtk_tree_view_column_dispose;
   object_class->set_property = gtk_tree_view_column_set_property;
   object_class->get_property = gtk_tree_view_column_get_property;
-  
+
+  /**
+   * GtkTreeViewColumn::clicked:
+   * @column: the #GtkTreeViewColumn that emitted the signal
+   *
+   * Emitted when the column's header has been clicked.
+   */
   tree_column_signals[CLICKED] =
     g_signal_new (I_("clicked"),
                   G_OBJECT_CLASS_TYPE (object_class),
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index d2cd6db327..9204d62210 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1535,7 +1535,9 @@ gtk_widget_class_init (GtkWidgetClass *klass)
   /**
    * GtkWidget::move-focus:
    * @widget: the object which received the signal.
-   * @direction:
+   * @direction: the direction of the focus move
+   *
+   * Emitted when the focus is moved.
    */
   widget_signals[MOVE_FOCUS] =
     g_signal_new (I_("move-focus"),