diff --git a/docs/reference/gtk/images/popup-anchors.png b/docs/reference/gdk/images/popup-anchors.png
similarity index 100%
rename from docs/reference/gtk/images/popup-anchors.png
rename to docs/reference/gdk/images/popup-anchors.png
diff --git a/docs/reference/gtk/images/popup-flip.png b/docs/reference/gdk/images/popup-flip.png
similarity index 100%
rename from docs/reference/gtk/images/popup-flip.png
rename to docs/reference/gdk/images/popup-flip.png
diff --git a/docs/reference/gtk/images/popup-slide.png b/docs/reference/gdk/images/popup-slide.png
similarity index 100%
rename from docs/reference/gtk/images/popup-slide.png
rename to docs/reference/gdk/images/popup-slide.png
diff --git a/docs/reference/gdk/meson.build b/docs/reference/gdk/meson.build
index c895131a3d..cdd018def9 100644
--- a/docs/reference/gdk/meson.build
+++ b/docs/reference/gdk/meson.build
@@ -146,6 +146,9 @@ images = [
   'images/nwse_resize_cursor.png',
   'images/zoom_in_cursor.png',
   'images/zoom_out_cursor.png',
+  'images/popup-anchors.png',
+  'images/popup-flip.png',
+  'images/popup-slide.png',
 ]
 
 src_dir = [ gdkinc ]
diff --git a/docs/reference/gtk/images/popup-at.svg b/docs/reference/gdk/popup-at.svg
similarity index 100%
rename from docs/reference/gtk/images/popup-at.svg
rename to docs/reference/gdk/popup-at.svg
diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index cdd53d61e8..a2e28b586f 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -413,10 +413,6 @@ images = [
   'images/password-entry.png',
   'images/picture.png',
   'images/popover.png',
-  'images/popup-anchors.png',
-  'images/popup-at.svg',
-  'images/popup-flip.png',
-  'images/popup-slide.png',
   'images/printdialog.png',
   'images/progressbar.png',
   'images/right-center.png',
diff --git a/gdk/gdkdrawcontext.c b/gdk/gdkdrawcontext.c
index 3c74267b57..d0ea519e18 100644
--- a/gdk/gdkdrawcontext.c
+++ b/gdk/gdkdrawcontext.c
@@ -280,7 +280,7 @@ gdk_draw_context_get_surface (GdkDrawContext *context)
  * implementation must use gdk_draw_context_get_frame_region() to query the
  * region that must be drawn.
  *
- * When using GTK+, the widget system automatically places calls to
+ * When using GTK, the widget system automatically places calls to
  * gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the
  * use of #GskRenderers, so application code does not need to call these
  * functions explicitly.
diff --git a/gdk/gdkpopuplayout.c b/gdk/gdkpopuplayout.c
index 0542bec811..bff14a935c 100644
--- a/gdk/gdkpopuplayout.c
+++ b/gdk/gdkpopuplayout.c
@@ -30,6 +30,32 @@
  * Popups are positioned relative to their parent surface.
  * The GdkPopupLayout struct contains information that is
  * necessary to do so.
+ *
+ * The positioning requires a negotiation with the windowing system,
+ * since it depends on external constraints, such as the position of
+ * the parent surface, and the screen dimensions.
+ *
+ * The basic ingredients are a rectangle on the parent surface,
+ * and the anchor on both that rectangle and the popup. The anchors
+ * specify a side or corner to place next to each other.
+ *
+ * ![Popup anchors](popup-anchors.png)
+ *
+ * For cases where placing the anchors next to each other would make
+ * the popup extend offscreen, the layout includes some hints for how
+ * to resolve this problem. The hints may suggest to flip the anchor
+ * position to the other side, or to 'slide' the popup along a side,
+ * or to resize it.
+ *
+ * ![Flipping popups](popup-flip.png)
+ *
+ * ![Sliding popups](popup-slide.png)
+ *
+ * These hints may be combined, but it is ultimatively up to the windowing
+ * system to determine the position and size of the popup. You can learn
+ * about the result by calling gdk_popup_get_position_x(),
+ * gdk_popup_get_position_y(), gdk_popup_get_rect_anchor() and
+ * gdk_popup_get_surface_anchor() after the popup has been presented.
  */
 
 struct _GdkPopupLayout