From 5a307fa7f3c5d1f474b2eb6abf61190608066b15 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 13:37:59 +0000
Subject: [PATCH 01/26] docs: Ignore more private headers

---
 docs/reference/gdk/meson.build | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/reference/gdk/meson.build b/docs/reference/gdk/meson.build
index ed7e4ddb36..2037531241 100644
--- a/docs/reference/gdk/meson.build
+++ b/docs/reference/gdk/meson.build
@@ -16,6 +16,7 @@ private_headers = [
   'gdkdisplayprivate.h',
   'gdkdndprivate.h',
   'gdkdragprivate.h',
+  'gdkdragsurfaceprivate.h',
   'gdkdrawcontextprivate.h',
   'gdkdropprivate.h',
   'gdkeventsprivate.h',
@@ -37,6 +38,7 @@ private_headers = [
   'gdksurfaceprivate.h',
   'gdktextureprivate.h',
   'gdktoplevelprivate.h',
+  'gdktoplevelsizeprivate.h',
   'gdkvulkancontextprivate.h',
   'keyname-table.h',
   'x11/gdkprivate-x11.h',

From 4021734047250b897156e7029c0843562fffdfde Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 13:38:12 +0000
Subject: [PATCH 02/26] docs: Annotate the GdkContentProviderClass structure

---
 gdk/gdkcontentprovider.h | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/gdk/gdkcontentprovider.h b/gdk/gdkcontentprovider.h
index f63be7676c..f1f558ab74 100644
--- a/gdk/gdkcontentprovider.h
+++ b/gdk/gdkcontentprovider.h
@@ -49,6 +49,12 @@ struct _GdkContentProvider
   GObject parent;
 };
 
+/**
+ * GdkContentProviderClass:
+ * @content_changed: Signal class closure for #GdkContentProvider::content-changed
+ *
+ * Class structure for #GdkContentProvider.
+ */
 struct _GdkContentProviderClass
 {
   GObjectClass parent_class;
@@ -56,6 +62,7 @@ struct _GdkContentProviderClass
   /* signals */
   void                  (* content_changed)                             (GdkContentProvider     *provider);
 
+  /*< private >*/
   /* vfuncs */
   void                  (* attach_clipboard)                            (GdkContentProvider     *provider,
                                                                          GdkClipboard           *clipboard);

From e3fbc0ee9c2e2f7cc096e0da388a9451ba5c3922 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 13:38:33 +0000
Subject: [PATCH 03/26] docs: Fix typo in the GdkTolevelLayout annotation

---
 gdk/gdktoplevellayout.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gdk/gdktoplevellayout.h b/gdk/gdktoplevellayout.h
index 23b2660414..62f2790f75 100644
--- a/gdk/gdktoplevellayout.h
+++ b/gdk/gdktoplevellayout.h
@@ -30,7 +30,7 @@
 G_BEGIN_DECLS
 
 /**
- * GdkTopLevelLayout:
+ * GdkToplevelLayout:
  *
  * Struct containing information for gdk_toplevel_present()
  */

From 598e1304f6bf4cea7c5cd2dbb86d780985e80fc7 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 13:39:48 +0000
Subject: [PATCH 04/26] docs: Annotate the GdkToplevel interface

---
 gdk/gdktoplevel.h | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/gdk/gdktoplevel.h b/gdk/gdktoplevel.h
index 0cae8e4eb8..05fafa4b5f 100644
--- a/gdk/gdktoplevel.h
+++ b/gdk/gdktoplevel.h
@@ -120,6 +120,11 @@ typedef enum
 
 #define GDK_TYPE_TOPLEVEL (gdk_toplevel_get_type ())
 
+/**
+ * GdkToplevel:
+ *
+ * An interface for top level surfaces.
+ */
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_INTERFACE (GdkToplevel, gdk_toplevel, GDK, TOPLEVEL, GObject)
 
@@ -198,7 +203,6 @@ void          gdk_toplevel_begin_move                (GdkToplevel    *toplevel,
                                                       double          y,
                                                       guint32         timestamp);
 
-
 G_END_DECLS
 
 #endif /* __GDK_TOPLEVEL_H__ */

From 6e4dd5811da2303df1a84726cb6c43419e9c7148 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 13:41:28 +0000
Subject: [PATCH 05/26] docs: Annotate GdkSnapshot

---
 gdk/gdksnapshot.h | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/gdk/gdksnapshot.h b/gdk/gdksnapshot.h
index ccee850e98..c2b4ce2e1c 100644
--- a/gdk/gdksnapshot.h
+++ b/gdk/gdksnapshot.h
@@ -29,7 +29,13 @@
 
 G_BEGIN_DECLS
 
-typedef struct _GdkSnapshotClass       GdkSnapshotClass;
+/**
+ * GdkSnapshot:
+ *
+ * Base type for snapshot operations.
+ */
+
+typedef struct _GdkSnapshotClass        GdkSnapshotClass;
 
 #define GDK_TYPE_SNAPSHOT               (gdk_snapshot_get_type ())
 

From ecce3756d41198245449adf8c21d1274c7bd5c8f Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 13:42:07 +0000
Subject: [PATCH 06/26] docs: Annotate GdkPopup

---
 gdk/gdkpopup.h | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/gdk/gdkpopup.h b/gdk/gdkpopup.h
index ba8a2782a7..361d4bac03 100644
--- a/gdk/gdkpopup.h
+++ b/gdk/gdkpopup.h
@@ -31,6 +31,11 @@ G_BEGIN_DECLS
 
 #define GDK_TYPE_POPUP (gdk_popup_get_type ())
 
+/**
+ * GdkPopup:
+ *
+ * Interface for popup surfaces.
+ */
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_INTERFACE (GdkPopup, gdk_popup, GDK, POPUP, GObject)
 

From 879b2845ada835229aadbeb1290399f2571fc140 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 13:44:51 +0000
Subject: [PATCH 07/26] docs: Annotate GdkPaintable

The dummy typedef needs a gtk-doc stanza, and the interface
documentation needs to be slightly clarified.
---
 gdk/gdkpaintable.h | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/gdk/gdkpaintable.h b/gdk/gdkpaintable.h
index b6efee983c..2936a75b7a 100644
--- a/gdk/gdkpaintable.h
+++ b/gdk/gdkpaintable.h
@@ -31,6 +31,11 @@ G_BEGIN_DECLS
 
 #define GDK_TYPE_PAINTABLE               (gdk_paintable_get_type ())
 
+/**
+ * GdkPaintable:
+ *
+ * Interface for paintable objects.
+ */
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_INTERFACE (GdkPaintable, gdk_paintable, GDK, PAINTABLE, GObject)
 
@@ -74,11 +79,13 @@ typedef enum {
  *     this function should return the aspect ratio computed from those.
  *
  * The list of functions that can be implemented for the #GdkPaintable interface.
- * Note that apart from the first function, no function is mandatory to implement,
- * though it is a good idea to implement #GdkPaintableInterface.get_current_image()
- * for non-static paintables and #GdkPaintableInterface.get_flags() if the image
- * is not dynamic as the default implementation returns no flags and that will
- * make the implementation likely quite slow.
+ *
+ * Note that apart from the #GdkPaintableInterface.snapshot() function, no virtual
+ * function of this interface is mandatory to implement, though it is a good idea
+ * to implement #GdkPaintableInterface.get_current_image() for non-static paintables
+ * and #GdkPaintableInterface.get_flags() if the image is not dynamic as the default
+ * implementation returns no flags and that will make the implementation likely
+ * quite slow.
  */
 struct _GdkPaintableInterface
 {

From 1057189ea2a54728ee9a78b9956caeb0308a35cd Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 13:47:56 +0000
Subject: [PATCH 08/26] docs: Annotate GdkMemoryTexture

---
 gdk/gdkmemorytexture.h | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/gdk/gdkmemorytexture.h b/gdk/gdkmemorytexture.h
index b24e8c6796..d4161d60de 100644
--- a/gdk/gdkmemorytexture.h
+++ b/gdk/gdkmemorytexture.h
@@ -94,6 +94,11 @@ typedef enum {
 #define GDK_MEMORY_TEXTURE(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), GDK_TYPE_MEMORY_TEXTURE, GdkMemoryTexture))
 #define GDK_IS_MEMORY_TEXTURE(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GDK_TYPE_MEMORY_TEXTURE))
 
+/**
+ * GdkMemoryTexture:
+ *
+ * A #GdkTexture representing image data in memory.
+ */
 typedef struct _GdkMemoryTexture        GdkMemoryTexture;
 typedef struct _GdkMemoryTextureClass   GdkMemoryTextureClass;
 

From b9a1827da71d2f72becb13321d84b064bf277914 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 13:48:07 +0000
Subject: [PATCH 09/26] docs: Annotate GdkGLTexture

---
 gdk/gdkgltexture.h | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/gdk/gdkgltexture.h b/gdk/gdkgltexture.h
index 54e4fee7e7..bdc70a0cad 100644
--- a/gdk/gdkgltexture.h
+++ b/gdk/gdkgltexture.h
@@ -33,6 +33,11 @@ G_BEGIN_DECLS
 #define GDK_GL_TEXTURE(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), GDK_TYPE_GL_TEXTURE, GdkGLTexture))
 #define GDK_IS_GL_TEXTURE(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GDK_TYPE_GL_TEXTURE))
 
+/**
+ * GdkGLTexture:
+ *
+ * A #GdkTexture representing a GL texture object.
+ */
 typedef struct _GdkGLTexture            GdkGLTexture;
 typedef struct _GdkGLTextureClass       GdkGLTextureClass;
 

From b5313dbd4d91ea4dfcda319b9034793f9c157e2c Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 13:50:25 +0000
Subject: [PATCH 10/26] docs: Annotate GdkDeviceTool

---
 gdk/gdkdevicetool.h | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/gdk/gdkdevicetool.h b/gdk/gdkdevicetool.h
index 1a6a90d756..16f5b3b30b 100644
--- a/gdk/gdkdevicetool.h
+++ b/gdk/gdkdevicetool.h
@@ -32,6 +32,11 @@ G_BEGIN_DECLS
 #define GDK_DEVICE_TOOL(o)      (G_TYPE_CHECK_INSTANCE_CAST ((o), GDK_TYPE_DEVICE_TOOL, GdkDeviceTool))
 #define GDK_IS_DEVICE_TOOL(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GDK_TYPE_DEVICE_TOOL))
 
+/**
+ * GdkDeviceTool:
+ *
+ * A physical tool associated to a #GdkDevice.
+ */
 typedef struct _GdkDeviceTool GdkDeviceTool;
 
 /**

From c524b72d130cdc8578da72643ed1a36b5e9a0647 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 14:01:02 +0000
Subject: [PATCH 11/26] docs: Annotate structure types used by GskRenderNodes

---
 gsk/gskrendernode.h | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/gsk/gskrendernode.h b/gsk/gskrendernode.h
index dba436afda..f55fd67a30 100644
--- a/gsk/gskrendernode.h
+++ b/gsk/gskrendernode.h
@@ -40,12 +40,28 @@ typedef struct _GskRenderNode           GskRenderNode;
 typedef struct _GskColorStop            GskColorStop;
 typedef struct _GskShadow               GskShadow;
 
+/**
+ * GskColorStop:
+ * @offset: the offset of the color stop
+ * @color: the color at the given offset
+ *
+ * A color stop in a gradient node.
+ */
 struct _GskColorStop
 {
   float offset;
   GdkRGBA color;
 };
 
+/**
+ * GskShadow:
+ * @color: the color of the shadow
+ * @dx: the horizontal offset of the shadow
+ * @dy: the vertical offset of the shadow
+ * @radius: the radius of the shadow
+ *
+ * The shadow parameters in a shadow node.
+ */
 struct _GskShadow
 {
   GdkRGBA color;
@@ -56,6 +72,16 @@ struct _GskShadow
 
 typedef struct _GskParseLocation GskParseLocation;
 
+/**
+ * GskParseLocation:
+ * @bytes: the offset of the location in the parse buffer, as bytes
+ * @chars: the offset of the location in the parse buffer, as characters
+ * @lines: the line of the location in the parse buffer
+ * @line_bytes: the position in the line, as bytes
+ * @line_chars: the position in the line, as characters
+ *
+ * A location in a parse buffer.
+ */
 struct _GskParseLocation
 {
   gsize bytes;

From 0f62ab6c4250513f40ff84b02571b0d2355eae6f Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 14:16:28 +0000
Subject: [PATCH 12/26] docs: Annotate all render node types

---
 gsk/gskrendernodeimpl.c | 123 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)

diff --git a/gsk/gskrendernodeimpl.c b/gsk/gskrendernodeimpl.c
index e5228d88c9..5fcc723446 100644
--- a/gsk/gskrendernodeimpl.c
+++ b/gsk/gskrendernodeimpl.c
@@ -51,6 +51,11 @@ rectangle_init_from_graphene (cairo_rectangle_int_t *cairo,
 
 /*** GSK_COLOR_NODE ***/
 
+/**
+ * GskColorNode:
+ *
+ * A render node for a solid color.
+ */
 struct _GskColorNode
 {
   GskRenderNode render_node;
@@ -134,6 +139,17 @@ gsk_color_node_new (const GdkRGBA         *rgba,
 
 /*** GSK_LINEAR_GRADIENT_NODE ***/
 
+/**
+ * GskRepeatingLinearGradientNode:
+ *
+ * A render node for a repeating linear gradient.
+ */
+
+/**
+ * GskLinearGradientNode:
+ *
+ * A render node for a linear gradient.
+ */
 struct _GskLinearGradientNode
 {
   GskRenderNode render_node;
@@ -392,6 +408,17 @@ gsk_linear_gradient_node_get_color_stops (GskRenderNode *node,
 
 /*** GSK_RADIAL_GRADIENT_NODE ***/
 
+/**
+ * GskRepeatingRadialGradientNode:
+ *
+ * A render node for a repeating radial gradient.
+ */
+
+/**
+ * GskRadialGradientNode:
+ *
+ * A render node for a radial gradient.
+ */
 struct _GskRadialGradientNode
 {
   GskRenderNode render_node;
@@ -743,6 +770,11 @@ gsk_radial_gradient_node_get_end (GskRenderNode *node)
 
 /*** GSK_BORDER_NODE ***/
 
+/**
+ * GskBorderNode:
+ *
+ * A render node for a border.
+ */
 struct _GskBorderNode
 {
   GskRenderNode render_node;
@@ -1027,6 +1059,11 @@ gsk_border_node_get_uniform (GskRenderNode *self)
 
 /*** GSK_TEXTURE_NODE ***/
 
+/**
+ * GskTextureNode:
+ *
+ * A render node for a #GdkTexture.
+ */
 struct _GskTextureNode
 {
   GskRenderNode render_node;
@@ -1138,6 +1175,11 @@ gsk_texture_node_new (GdkTexture            *texture,
 
 /*** GSK_INSET_SHADOW_NODE ***/
 
+/**
+ * GskInsetShadowNode:
+ *
+ * A render node for an inset shadow.
+ */
 struct _GskInsetShadowNode
 {
   GskRenderNode render_node;
@@ -1697,6 +1739,11 @@ gsk_inset_shadow_node_get_blur_radius (GskRenderNode *node)
 
 /*** GSK_OUTSET_SHADOW_NODE ***/
 
+/**
+ * GskOutsetShadowNode:
+ *
+ * A render node for an outset shadow.
+ */
 struct _GskOutsetShadowNode
 {
   GskRenderNode render_node;
@@ -2006,6 +2053,11 @@ gsk_outset_shadow_node_get_blur_radius (GskRenderNode *node)
 
 /*** GSK_CAIRO_NODE ***/
 
+/**
+ * GskCairoNode:
+ *
+ * A render node for a Cairo surface.
+ */
 struct _GskCairoNode
 {
   GskRenderNode render_node;
@@ -2137,6 +2189,11 @@ gsk_cairo_node_get_draw_context (GskRenderNode *node)
 
 /**** GSK_CONTAINER_NODE ***/
 
+/**
+ * GskContainerNode:
+ *
+ * A render node that can contain other render nodes.
+ */
 struct _GskContainerNode
 {
   GskRenderNode render_node;
@@ -2324,6 +2381,11 @@ gsk_container_node_get_child (GskRenderNode *node,
 
 /*** GSK_TRANSFORM_NODE ***/
 
+/**
+ * GskTransformNode:
+ *
+ * A render node applying a #GskTransform to its single child node.
+ */
 struct _GskTransformNode
 {
   GskRenderNode render_node;
@@ -2517,6 +2579,11 @@ gsk_transform_node_get_transform (GskRenderNode *node)
 
 /*** GSK_OPACITY_NODE ***/
 
+/**
+ * GskOpacityNode:
+ *
+ * A render node controlling the opacity of its single child node.
+ */
 struct _GskOpacityNode
 {
   GskRenderNode render_node;
@@ -2640,6 +2707,11 @@ gsk_opacity_node_get_opacity (GskRenderNode *node)
 
 /*** GSK_COLOR_MATRIX_NODE ***/
 
+/**
+ * GskColorMatrixNode:
+ *
+ * A render node controlling the color matrix of its single child node.
+ */
 struct _GskColorMatrixNode
 {
   GskRenderNode render_node;
@@ -2861,6 +2933,11 @@ gsk_color_matrix_node_get_color_offset (GskRenderNode *node)
 
 /*** GSK_REPEAT_NODE ***/
 
+/**
+ * GskRepeatNode:
+ *
+ * A render node repeating its single child node.
+ */
 struct _GskRepeatNode
 {
   GskRenderNode render_node;
@@ -2993,6 +3070,11 @@ gsk_repeat_node_get_child_bounds (GskRenderNode *node)
 
 /*** GSK_CLIP_NODE ***/
 
+/**
+ * GskClipNode:
+ *
+ * A render node applying a rectangular clip to its single child node.
+ */
 struct _GskClipNode
 {
   GskRenderNode render_node;
@@ -3123,6 +3205,11 @@ gsk_clip_node_get_clip (GskRenderNode *node)
 
 /*** GSK_ROUNDED_CLIP_NODE ***/
 
+/**
+ * GskRoundedClipNode:
+ *
+ * A render node applying a rounded rectangle clip to its single child.
+ */
 struct _GskRoundedClipNode
 {
   GskRenderNode render_node;
@@ -3253,6 +3340,11 @@ gsk_rounded_clip_node_get_clip (GskRenderNode *node)
 
 /*** GSK_SHADOW_NODE ***/
 
+/**
+ * GskShadowNode:
+ *
+ * A render node drawing one or more shadows behind its single child node.
+ */
 struct _GskShadowNode
 {
   GskRenderNode render_node;
@@ -3492,6 +3584,11 @@ gsk_shadow_node_get_n_shadows (GskRenderNode *node)
 
 /*** GSK_BLEND_NODE ***/
 
+/**
+ * GskBlendNode:
+ *
+ * A render node applying a blending function between its two child nodes.
+ */
 struct _GskBlendNode
 {
   GskRenderNode render_node;
@@ -3684,6 +3781,11 @@ gsk_blend_node_get_blend_mode (GskRenderNode *node)
 
 /*** GSK_CROSS_FADE_NODE ***/
 
+/**
+ * GskCrossFadeNode:
+ *
+ * A render node cross fading between two child nodes.
+ */
 struct _GskCrossFadeNode
 {
   GskRenderNode render_node;
@@ -3833,6 +3935,11 @@ gsk_cross_fade_node_get_progress (GskRenderNode *node)
 
 /*** GSK_TEXT_NODE ***/
 
+/**
+ * GskTextNode:
+ *
+ * A render node drawing a set of glyphs.
+ */
 struct _GskTextNode
 {
   GskRenderNode render_node;
@@ -4098,6 +4205,11 @@ gsk_text_node_get_offset (GskRenderNode *node)
 
 /*** GSK_BLUR_NODE ***/
 
+/**
+ * GskBlurNode:
+ *
+ * A render node applying a blur effect to its single child.
+ */
 struct _GskBlurNode
 {
   GskRenderNode render_node;
@@ -4410,6 +4522,12 @@ gsk_blur_node_get_radius (GskRenderNode *node)
 
 /*** GSK_DEBUG_NODE ***/
 
+/**
+ * GskDebugNode:
+ *
+ * A render node that emits a debugging message when drawing its
+ * child node.
+ */
 struct _GskDebugNode
 {
   GskRenderNode render_node;
@@ -4530,6 +4648,11 @@ gsk_debug_node_get_message (GskRenderNode *node)
 
 /*** GSK_GL_SHADER_NODE ***/
 
+/**
+ * GskGLShaderNode:
+ *
+ * A render node using a GL shader when drawing its children nodes.
+ */
 struct _GskGLShaderNode
 {
   GskRenderNode render_node;

From 8b898818c2aa43f2b01480d2d211115a931ed6e5 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 14:16:45 +0000
Subject: [PATCH 13/26] docs: Annotate the GL shader objects

---
 gsk/gskglshader.h | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/gsk/gskglshader.h b/gsk/gskglshader.h
index 57bf941730..2e98e5cb12 100644
--- a/gsk/gskglshader.h
+++ b/gsk/gskglshader.h
@@ -32,10 +32,20 @@ G_BEGIN_DECLS
 
 #define GSK_TYPE_SHADER_ARGS_BUILDER    (gsk_shader_args_builder_get_type ())
 
+/**
+ * GskShaderArgsBuilder:
+ *
+ * An object to build the uniforms data for a #GskGLShader.
+ */
 typedef struct _GskShaderArgsBuilder GskShaderArgsBuilder;
 
 #define GSK_TYPE_GL_SHADER (gsk_gl_shader_get_type ())
 
+/**
+ * GskGLShader:
+ *
+ * An object representing a GL shader program.
+ */
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_FINAL_TYPE (GskGLShader, gsk_gl_shader, GSK, GL_SHADER, GObject)
 

From 37f11ab77d3c3a962d099a84760abb94982b6c0d Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 14:17:59 +0000
Subject: [PATCH 14/26] docs: Annotate GskRenderer

---
 gsk/gskrenderer.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/gsk/gskrenderer.h b/gsk/gskrenderer.h
index 70f05a7180..00b0eaecf1 100644
--- a/gsk/gskrenderer.h
+++ b/gsk/gskrenderer.h
@@ -33,6 +33,12 @@ G_BEGIN_DECLS
 #define GSK_RENDERER(obj)               (G_TYPE_CHECK_INSTANCE_CAST ((obj), GSK_TYPE_RENDERER, GskRenderer))
 #define GSK_IS_RENDERER(obj)            (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GSK_TYPE_RENDERER))
 
+/**
+ * GskRenderer:
+ *
+ * Base type for the object managing the rendering pipeline
+ * for a #GdkSurface.
+ */
 typedef struct _GskRendererClass        GskRendererClass;
 
 GDK_AVAILABLE_IN_ALL

From eba8f36d4f20c958a68917601e91c27f535f4251 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 14:44:28 +0000
Subject: [PATCH 15/26] docs: Fix annotations in GtkCenterLayout

Missing ':' separator.
---
 gtk/gtkcenterlayout.c | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/gtk/gtkcenterlayout.c b/gtk/gtkcenterlayout.c
index d9be591c5a..f7b77458e5 100644
--- a/gtk/gtkcenterlayout.c
+++ b/gtk/gtkcenterlayout.c
@@ -613,13 +613,15 @@ gtk_center_layout_set_baseline_position (GtkCenterLayout     *self,
 GtkBaselinePosition
 gtk_center_layout_get_baseline_position (GtkCenterLayout *self)
 {
+  g_return_val_if_fail (GTK_IS_CENTER_LAYOUT (self), GTK_BASELINE_POSITION_TOP);
+
   return self->baseline_pos;
 }
 
 /**
  * gtk_center_layout_set_start_widget:
  * @self: a #GtkCenterLayout
- * @widget (nullable): the new start widget
+ * @widget: (nullable): the new start widget
  *
  * Sets the new start widget of @self.
  *
@@ -643,13 +645,15 @@ gtk_center_layout_set_start_widget (GtkCenterLayout *self,
 GtkWidget *
 gtk_center_layout_get_start_widget (GtkCenterLayout *self)
 {
+  g_return_val_if_fail (GTK_IS_CENTER_LAYOUT (self), NULL);
+
   return self->start_widget;
 }
 
 /**
  * gtk_center_layout_set_center_widget:
  * @self: a #GtkCenterLayout
- * @widget (nullable): the new center widget
+ * @widget: (nullable): the new center widget
  *
  * Sets the new center widget of @self.
  *

From c13e164f25c71ddcb9d73621acf639018e42b446 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 14:45:01 +0000
Subject: [PATCH 16/26] Make GtkCenterLayout accessors more idiomatic

Add argument validation, and emit a layout-changed signal whenever the
start, center, and end widgets change.
---
 gtk/gtkcenterlayout.c | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/gtk/gtkcenterlayout.c b/gtk/gtkcenterlayout.c
index f7b77458e5..f9fa988ca7 100644
--- a/gtk/gtkcenterlayout.c
+++ b/gtk/gtkcenterlayout.c
@@ -563,6 +563,8 @@ void
 gtk_center_layout_set_orientation (GtkCenterLayout *self,
                                    GtkOrientation   orientation)
 {
+  g_return_if_fail (GTK_IS_CENTER_LAYOUT (self));
+
   if (orientation != self->orientation)
     {
       self->orientation = orientation;
@@ -581,6 +583,8 @@ gtk_center_layout_set_orientation (GtkCenterLayout *self,
 GtkOrientation
 gtk_center_layout_get_orientation (GtkCenterLayout *self)
 {
+  g_return_val_if_fail (GTK_IS_CENTER_LAYOUT (self), GTK_ORIENTATION_HORIZONTAL);
+
   return self->orientation;
 }
 
@@ -595,6 +599,8 @@ void
 gtk_center_layout_set_baseline_position (GtkCenterLayout     *self,
                                          GtkBaselinePosition  baseline_position)
 {
+  g_return_if_fail (GTK_IS_CENTER_LAYOUT (self));
+
   if (baseline_position != self->baseline_pos)
     {
       self->baseline_pos = baseline_position;
@@ -631,7 +637,14 @@ void
 gtk_center_layout_set_start_widget (GtkCenterLayout *self,
                                     GtkWidget       *widget)
 {
+  g_return_if_fail (GTK_IS_CENTER_LAYOUT (self));
+  g_return_if_fail (widget == NULL || GTK_IS_WIDGET (widget));
+
+  if (self->start_widget == widget)
+    return;
+
   self->start_widget = widget;
+  gtk_layout_manager_layout_changed (GTK_LAYOUT_MANAGER (self));
 }
 
 /**
@@ -663,7 +676,14 @@ void
 gtk_center_layout_set_center_widget (GtkCenterLayout *self,
                                      GtkWidget       *widget)
 {
+  g_return_if_fail (GTK_IS_CENTER_LAYOUT (self));
+  g_return_if_fail (widget == NULL || GTK_IS_WIDGET (widget));
+
+  if (self->center_widget == widget)
+    return;
+
   self->center_widget = widget;
+  gtk_layout_manager_layout_changed (GTK_LAYOUT_MANAGER (self));
 }
 
 /**
@@ -677,6 +697,8 @@ gtk_center_layout_set_center_widget (GtkCenterLayout *self,
 GtkWidget *
 gtk_center_layout_get_center_widget (GtkCenterLayout *self)
 {
+  g_return_val_if_fail (GTK_IS_CENTER_LAYOUT (self), NULL);
+
   return self->center_widget;
 }
 
@@ -693,7 +715,14 @@ void
 gtk_center_layout_set_end_widget (GtkCenterLayout *self,
                                   GtkWidget       *widget)
 {
+  g_return_if_fail (GTK_IS_CENTER_LAYOUT (self));
+  g_return_if_fail (widget == NULL || GTK_IS_WIDGET (widget));
+
+  if (self->end_widget == widget)
+    return;
+
   self->end_widget = widget;
+  gtk_layout_manager_layout_changed (GTK_LAYOUT_MANAGER (self));
 }
 
 /**
@@ -707,5 +736,7 @@ gtk_center_layout_set_end_widget (GtkCenterLayout *self,
 GtkWidget *
 gtk_center_layout_get_end_widget (GtkCenterLayout *self)
 {
+  g_return_val_if_fail (GTK_IS_CENTER_LAYOUT (self), NULL);
+
   return self->end_widget;
 }

From 4f67be1c8e7f44d0fbf1f99ca049f3be5ce0260f Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 15:04:09 +0000
Subject: [PATCH 17/26] docs: Add missing annotations for GtkTextTagTable

---
 gtk/gtktexttagtable.c | 9 +++++++++
 gtk/gtktexttagtable.h | 9 +++++++++
 2 files changed, 18 insertions(+)

diff --git a/gtk/gtktexttagtable.c b/gtk/gtktexttagtable.c
index 70980e3d8f..1435e7375c 100644
--- a/gtk/gtktexttagtable.c
+++ b/gtk/gtktexttagtable.c
@@ -126,6 +126,8 @@ gtk_text_tag_table_class_init (GtkTextTagTableClass *klass)
    * @texttagtable: the object which received the signal.
    * @tag: the changed tag.
    * @size_changed: whether the change affects the #GtkTextView layout.
+   *
+   * Emitted every time a tag in the #GtkTextTagTable changes.
    */
   signals[TAG_CHANGED] =
     g_signal_new (I_("tag-changed"),
@@ -146,6 +148,8 @@ gtk_text_tag_table_class_init (GtkTextTagTableClass *klass)
    * GtkTextTagTable::tag-added:
    * @texttagtable: the object which received the signal.
    * @tag: the added tag.
+   *
+   * Emitted every time a new tag is added in the #GtkTextTagTable.
    */
   signals[TAG_ADDED] =
     g_signal_new (I_("tag-added"),
@@ -162,6 +166,11 @@ gtk_text_tag_table_class_init (GtkTextTagTableClass *klass)
    * GtkTextTagTable::tag-removed:
    * @texttagtable: the object which received the signal.
    * @tag: the removed tag.
+   *
+   * Emitted every time a tag is removed from the #GtkTextTagTable.
+   *
+   * The @tag is still valid by the time the signal is emitted, but
+   * it is not associated with a tag table any more.
    */
   signals[TAG_REMOVED] =
     g_signal_new (I_("tag-removed"),  
diff --git a/gtk/gtktexttagtable.h b/gtk/gtktexttagtable.h
index 3602f17cf0..8076c77a68 100644
--- a/gtk/gtktexttagtable.h
+++ b/gtk/gtktexttagtable.h
@@ -37,6 +37,9 @@ G_BEGIN_DECLS
  * GtkTextTagTableForeach:
  * @tag: the #GtkTextTag
  * @data: (closure): data passed to gtk_text_tag_table_foreach()
+ *
+ * A function used with gtk_text_tag_table_foreach(), to iterate over every
+ * #GtkTextTag inside a #GtkTextTagTable.
  */
 typedef void (* GtkTextTagTableForeach) (GtkTextTag *tag, gpointer data);
 
@@ -44,6 +47,12 @@ typedef void (* GtkTextTagTableForeach) (GtkTextTag *tag, gpointer data);
 #define GTK_TEXT_TAG_TABLE(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_TEXT_TAG_TABLE, GtkTextTagTable))
 #define GTK_IS_TEXT_TAG_TABLE(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_TEXT_TAG_TABLE))
 
+/**
+ * GtkTextTagTable:
+ *
+ * An object holding all the #GtkTextTag instances for a #GtkTextBuffer.
+ */
+
 GDK_AVAILABLE_IN_ALL
 GType          gtk_text_tag_table_get_type (void) G_GNUC_CONST;
 

From d46fe31f544c29a829028bfc262f457a908195f1 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 15:21:44 +0000
Subject: [PATCH 18/26] docs: Ignore more files

---
 docs/reference/gtk/meson.build | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index 75f4b8fb67..4fc1acb80c 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -223,7 +223,9 @@ private_headers = [
   'gtkwin32themeprivate.h',
   'gtkwindowprivate.h',
   'gtk-text-input-client-protocol.h',
-  'roaring.h',
+
+  'roaring',
+  'a11y',
 ]
 
 images = [
@@ -471,6 +473,7 @@ if get_option('gtk_doc')
                ],
                mkdb_args: [
                  '--default-includes=gtk/gtk.h',
+                 '--ignore-files=' + ' '.join(private_headers),
                ],
                fixxref_args: [
                  '--html-dir=@0@'.format(docpath),

From 95400e645155981c413abc3e47588b7c52e03c93 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 17:16:05 +0000
Subject: [PATCH 19/26] docs: Annotate GtkAppChooserButton::changed

---
 gtk/gtkappchooserbutton.c | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/gtk/gtkappchooserbutton.c b/gtk/gtkappchooserbutton.c
index 7e81e2c925..bc7bbb6876 100644
--- a/gtk/gtkappchooserbutton.c
+++ b/gtk/gtkappchooserbutton.c
@@ -715,6 +715,13 @@ gtk_app_chooser_button_class_init (GtkAppChooserButtonClass *klass)
                           G_PARAM_READWRITE|G_PARAM_CONSTRUCT|G_PARAM_STATIC_STRINGS|G_PARAM_EXPLICIT_NOTIFY);
   g_object_class_install_properties (oclass, NUM_PROPERTIES, properties);
 
+  /**
+   * GtkAppChooserButton::changed:
+   * @self: the object which received the signal
+   *
+   * Emitted when the active application on the #GtkAppChooserButton
+   * changes.
+   */
   signals[SIGNAL_CHANGED] =
     g_signal_new (I_("changed"),
                   G_OBJECT_CLASS_TYPE (klass),

From 67f45940cef7676b27ed9cedab425c30d0db0ddd Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 17:18:23 +0000
Subject: [PATCH 20/26] docs: Annotate GtkAssistant::escape action signal

---
 gtk/gtkassistant.c | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/gtk/gtkassistant.c b/gtk/gtkassistant.c
index fdc02fae73..d60ace776c 100644
--- a/gtk/gtkassistant.c
+++ b/gtk/gtkassistant.c
@@ -560,6 +560,12 @@ gtk_assistant_class_init (GtkAssistantClass *class)
                   NULL,
                   G_TYPE_NONE, 0);
 
+  /**
+   * GtkAssistant::escape
+   * @assistant: the #GtkAssistant
+   *
+   * The action signal for the Escape binding.
+   */
   signals[ESCAPE] =
     g_signal_new_class_handler (I_("escape"),
                                 G_TYPE_FROM_CLASS (gobject_class),

From 3e8d15711850816d255537643819caf1efbf28f3 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 17:18:38 +0000
Subject: [PATCH 21/26] docs: Hide GtkBitsetIter fields

---
 gtk/gtkbitset.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/gtk/gtkbitset.h b/gtk/gtkbitset.h
index ad865a4e05..419b4df8d1 100644
--- a/gtk/gtkbitset.h
+++ b/gtk/gtkbitset.h
@@ -143,6 +143,7 @@ typedef struct _GtkBitsetIter GtkBitsetIter;
 
 struct _GtkBitsetIter
 {
+  /*< private >*/
   gpointer private_data[10];
 };
 

From d820fea7a4b53521aaade5e24b7338d569b21a09 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 17:21:45 +0000
Subject: [PATCH 22/26] docs: Annotate GtkBuildableParser

---
 gtk/gtkbuildable.h | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/gtk/gtkbuildable.h b/gtk/gtkbuildable.h
index 84008c9ff5..058845caba 100644
--- a/gtk/gtkbuildable.h
+++ b/gtk/gtkbuildable.h
@@ -39,6 +39,15 @@ typedef struct _GtkBuildableIface GtkBuildableIface;
 typedef struct _GtkBuildableParseContext      GtkBuildableParseContext;
 typedef struct _GtkBuildableParser GtkBuildableParser;
 
+/**
+ * GtkBuildableParser:
+ * @start_element: function called for open elements
+ * @end_element: function called for close elements
+ * @text: function called for character data
+ * @error: function called on error
+ *
+ * A sub-parser for #GtkBuildable implementations.
+ */
 struct _GtkBuildableParser
 {
   /* Called for open tags <foo bar="baz"> */
@@ -70,6 +79,7 @@ struct _GtkBuildableParser
                           GError                   *error,
                           gpointer                 user_data);
 
+  /*< private >*/
   gpointer padding[4];
 };
 
@@ -158,7 +168,7 @@ struct _GtkBuildableIface
    * @builder: a #GtkBuilder used to construct this object
    * @child: (nullable): child object or %NULL for non-child tags
    * @tagname: name of tag
-   * @parser: (out): a #GMarkupParser to fill in
+   * @parser: (out): a #GtkBuildableParser to fill in
    * @data: (out): return location for user data that will be passed in
    *   to parser functions
    *

From 516f71bbdccb6daf401a5c6f327b628a6f3be128 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 17:26:34 +0000
Subject: [PATCH 23/26] Use the appropriate prefix for GtkBuilderClosureFlags

Facilitate the job of glib-mkenums, and ensure that the enumeration
nicknames are computed reliably.
---
 gtk/gtkbuilderscope.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/gtk/gtkbuilderscope.h b/gtk/gtkbuilderscope.h
index 2b987f3822..7d0ae96320 100644
--- a/gtk/gtkbuilderscope.h
+++ b/gtk/gtkbuilderscope.h
@@ -44,7 +44,7 @@ G_DECLARE_INTERFACE (GtkBuilderScope, gtk_builder_scope, GTK, BUILDER_SCOPE, GOb
  * values and raise a %GTK_BUILDER_ERROR_INVALID_ATTRIBUTE error when they
  * encounter one.
  */
-typedef enum {
+typedef enum { /*< prefix=GTK_BUILDER_CLOSURE >*/
   GTK_BUILDER_CLOSURE_SWAPPED = (1 << 0)
 } GtkBuilderClosureFlags;
 

From 69b1b19315acc369b705926fbe777145232d7823 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 17:28:16 +0000
Subject: [PATCH 24/26] docs: Annotate missing symbols

---
 gtk/gtkexpression.h | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/gtk/gtkexpression.h b/gtk/gtkexpression.h
index 2eb9650142..0862f8dd54 100644
--- a/gtk/gtkexpression.h
+++ b/gtk/gtkexpression.h
@@ -154,6 +154,12 @@ GtkExpression *         gtk_cclosure_expression_new             (GType
 
 /* GObject integration, so we can use GtkBuilder */
 
+/**
+ * GTK_VALUE_HOLDS_EXPRESSION:
+ * @value: a #GValue
+ *
+ * Evaluates to %TRUE if @value was initialized with %GTK_TYPE_EXPRESSION.
+ */
 #define GTK_VALUE_HOLDS_EXPRESSION(value)       (G_VALUE_HOLDS ((value), GTK_TYPE_EXPRESSION))
 
 GDK_AVAILABLE_IN_ALL
@@ -171,6 +177,11 @@ GtkExpression * gtk_value_dup_expression        (const GValue  *value);
 #define GTK_PARAM_SPEC_EXPRESSION(obj)          (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_PARAM_SPEC_EXPRESSION, GtkParamSpecExpression))
 #define GTK_IS_PARAM_SPEC_EXPRESSION(obj)       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_PARAM_SPEC_EXPRESSION))
 
+/**
+ * GtkParamSpecExpression:
+ *
+ * A #GParamSpec for properties holding a #GtkExpression.
+ */
 typedef struct {
   /*< private >*/
   GParamSpec parent_instance;

From ef36028526c19a0e73f58d8b82d0cbffb80f8bb5 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 18:01:33 +0000
Subject: [PATCH 25/26] docs: Ignore more private files

---
 docs/reference/gtk/meson.build | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index 4fc1acb80c..d0073f9445 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -146,6 +146,7 @@ private_headers = [
   'gtkimageprivate.h',
   'gtkimcontextsimpleprivate.h',
   'gtkimmoduleprivate.h',
+  'gtkintl.h',
   'gtkkineticscrollingprivate.h',
   'gtklabelprivate.h',
   'gtklistbaseprivate.h',
@@ -183,6 +184,10 @@ private_headers = [
   'gtkrendernodepaintableprivate.h',
   'gtkroundedboxprivate.h',
   'gtkscalerprivate.h',
+  'gtksearchengine.h',
+  'gtksearchenginemodel.h',
+  'gtksearchenginequartz.h',
+  'gtksearchenginetracker3.h',
   'gtksearchentryprivate.h',
   'gtksettingsprivate.h',
   'gtkshortcutcontrollerprivate.h',
@@ -224,8 +229,9 @@ private_headers = [
   'gtkwindowprivate.h',
   'gtk-text-input-client-protocol.h',
 
-  'roaring',
   'a11y',
+  'inspector',
+  'roaring',
 ]
 
 images = [

From cdad68e858e6abd446b6a41e52f05fd516095ccf Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Tue, 1 Dec 2020 18:03:31 +0000
Subject: [PATCH 26/26] docs: Ignore generated Wayland protocol file

---
 docs/reference/gtk/meson.build | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index d0073f9445..eb641e4cfd 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -227,7 +227,8 @@ private_headers = [
   'gtkwin32drawprivate.h',
   'gtkwin32themeprivate.h',
   'gtkwindowprivate.h',
-  'gtk-text-input-client-protocol.h',
+
+  'text-input-unstable-v3-client-protocol.h',
 
   'a11y',
   'inspector',