diff --git a/docs/reference/gdk/gdk4-docs.xml b/docs/reference/gdk/gdk4-docs.xml
index 58ac4eddde..31dd72f96c 100644
--- a/docs/reference/gdk/gdk4-docs.xml
+++ b/docs/reference/gdk/gdk4-docs.xml
@@ -27,6 +27,7 @@
     <xi:include href="xml/gdkmonitor.xml" />
     <xi:include href="xml/regions.xml" />
     <xi:include href="xml/textures.xml" />
+    <xi:include href="xml/gdkpaintable.xml" />
     <xi:include href="xml/rgba_colors.xml" />
     <xi:include href="xml/cursors.xml" />
     <xi:include href="xml/gdksurface.xml" />
diff --git a/docs/reference/gdk/gdk4-sections.txt b/docs/reference/gdk/gdk4-sections.txt
index a01d39f1e7..2948955fb8 100644
--- a/docs/reference/gdk/gdk4-sections.txt
+++ b/docs/reference/gdk/gdk4-sections.txt
@@ -698,20 +698,27 @@ gdk_event_get_type
 </SECTION>
 
 <SECTION>
-<TITLE>Paintable</TITLE>
-<FILE>paintable</FILE>
+<FILE>gdkpaintable</FILE>
+<TITLE>GdkPaintable/TITLE>
 GdkPaintable
-gdk_paintable_snapshot
+GdkPaintableFlags
 gdk_paintable_get_current_image
+gdk_paintable_snapshot
 gdk_paintable_get_flags
 gdk_paintable_get_intrinsic_width
 gdk_paintable_get_intrinsic_height
 gdk_paintable_get_intrinsic_aspect_ratio
 gdk_paintable_compute_concrete_size
+
+<SUBSECTION>
 gdk_paintable_invalidate_contents
 gdk_paintable_invalidate_size
 gdk_paintable_new_empty
-<SECTION>
+
+<SUBSECTION Private>
+GDK_TYPE_PAINTABLE
+gdk_paintable_get_type
+</SECTION>
 
 <SECTION>
 <TITLE>Textures</TITLE>
@@ -1318,3 +1325,4 @@ GDK_CONTENT_DESERIALIZER
 GDK_IS_CONTENT_DESERIALIZER
 gdk_content_deserializer_get_type
 </SECTION>
+
diff --git a/gdk/gdkpaintable.c b/gdk/gdkpaintable.c
index 24ee62225a..082ff9b5c0 100644
--- a/gdk/gdkpaintable.c
+++ b/gdk/gdkpaintable.c
@@ -30,7 +30,7 @@ void            gtk_snapshot_push_debug                 (GdkSnapshot
 void            gtk_snapshot_pop                        (GdkSnapshot            *snapshot);
 
 /**
- * SECTION:paintable
+ * SECTION:gdkpaintable
  * @Title: GdkPaintable
  * @Short_description: An interface for a paintable region
  * @See_also: #ClutterContent, #GtkImage, #GdkTexture, #GtkSnapshot
@@ -71,6 +71,12 @@ void            gtk_snapshot_pop                        (GdkSnapshot
  * #GdkPaintable::invalidate-size signal.
  * And just like for contents, if a paintable is known to never change its size,
  * it will set the %GDK_PAINTABLE_STATIC_SIZE flag.
+ *
+ * Besides API for applications, there are some functions that are only
+ * useful for implementing subclasses and should not be used by applications:
+ * gdk_paintable_invalidate_contents(),
+ * gdk_paintable_invalidate_size(),
+ * gdk_paintable_new_empty().
  */
 
 G_DEFINE_INTERFACE (GdkPaintable, gdk_paintable, G_TYPE_OBJECT)
@@ -149,8 +155,6 @@ gdk_paintable_default_init (GdkPaintableInterface *iface)
    *
    * Examples for such an event would be videos changing to the next frame or
    * the icon theme for an icon changing.
-   *
-   * Since: 4.0
    */
   signals[INVALIDATE_CONTENTS] =
     g_signal_new ("invalidate-contents",
@@ -172,8 +176,6 @@ gdk_paintable_default_init (GdkPaintableInterface *iface)
    *
    * Examples for such an event would be a paintable displaying the contents of a toplevel
    * surface being resized.
-   *
-   * Since: 4.0
    */
   signals[INVALIDATE_SIZE] =
     g_signal_new ("invalidate-size",
@@ -195,9 +197,7 @@ gdk_paintable_default_init (GdkPaintableInterface *iface)
  * Snapshots the given paintable with the given @width and @height at the
  * current (0,0) offset of the @snapshot. If @width and @height are not larger
  * than zero, this function will do nothing.
- *
- * Since: 4.0
- **/
+ */
 void
 gdk_paintable_snapshot (GdkPaintable *paintable,
                         GdkSnapshot  *snapshot,
@@ -240,7 +240,7 @@ gdk_paintable_is_immutable (GdkPaintable *paintable)
  *
  * Returns: (transfer full): An immutable paintable for the current
  *     contents of @paintable.
- **/
+ */
 GdkPaintable *
 gdk_paintable_get_current_image (GdkPaintable *paintable)
 {
@@ -264,7 +264,7 @@ gdk_paintable_get_current_image (GdkPaintable *paintable)
  * See #GdkPaintableFlags for the flags and what they mean.
  *
  * Returns: The #GdkPaintableFlags for this paintable.
- **/
+ */
 GdkPaintableFlags
 gdk_paintable_get_flags (GdkPaintable *paintable)
 {
@@ -291,7 +291,7 @@ gdk_paintable_get_flags (GdkPaintable *paintable)
  * values are never returned.
  *
  * Returns: the intrinsic width of @paintable or 0 if none.
- **/
+ */
 int
 gdk_paintable_get_intrinsic_width (GdkPaintable *paintable)
 {
@@ -318,7 +318,7 @@ gdk_paintable_get_intrinsic_width (GdkPaintable *paintable)
  * values are never returned.
  *
  * Returns: the intrinsic height of @paintable or 0 if none.
- **/
+ */
 int
 gdk_paintable_get_intrinsic_height (GdkPaintable *paintable)
 {
@@ -351,7 +351,7 @@ gdk_paintable_get_intrinsic_height (GdkPaintable *paintable)
  * Negative values are never returned.
  *
  * Returns: the intrinsic aspect ratio of @paintable or 0.0 if none.
- **/
+ */
 double
 gdk_paintable_get_intrinsic_aspect_ratio (GdkPaintable *paintable)
 {
@@ -375,7 +375,7 @@ gdk_paintable_get_intrinsic_aspect_ratio (GdkPaintable *paintable)
  *
  * If a @paintable reports the %GDK_PAINTABLE_STATIC_CONTENTS flag,
  * it must not call this function.
- **/
+ */
 void
 gdk_paintable_invalidate_contents (GdkPaintable *paintable)
 {
@@ -397,7 +397,7 @@ gdk_paintable_invalidate_contents (GdkPaintable *paintable)
  *
  * If a @paintable reports the %GDK_PAINTABLE_STATIC_SIZE flag,
  * it must not call this function.
- **/
+ */
 void
 gdk_paintable_invalidate_size (GdkPaintable *paintable)
 {
@@ -636,7 +636,7 @@ gdk_empty_paintable_init (GdkEmptyPaintable *self)
  * #GtkMediaStream before receiving the first frame).
  *
  * Returns: (transfer full): a #GdkPaintable
- **/
+ */
 GdkPaintable *
 gdk_paintable_new_empty (int intrinsic_width,
                          int intrinsic_height)
diff --git a/gdk/gdkpaintable.h b/gdk/gdkpaintable.h
index 751e04af05..7686286c87 100644
--- a/gdk/gdkpaintable.h
+++ b/gdk/gdkpaintable.h
@@ -52,7 +52,7 @@ typedef enum {
 } GdkPaintableFlags;
 
 /**
- * GdkPaintableIface:
+ * GdkPaintableInterface:
  * @snapshot: Snapshot the paintable. The given @width and @height are
  *     guaranteed to be larger than 0.0. The resulting snapshot must modify
  *     only the area in the rectangle from (0,0) to (width, height).