21 files changed, 57 insertions, 71 deletions

diff --git a/docs/reference/gdk/gdk4-docs.xml b/docs/reference/gdk/gdk4-docs.xml
index a7291c3ffd..3e1ed5f974 100644
--- a/docs/reference/gdk/gdk4-docs.xml
+++ b/docs/reference/gdk/gdk4-docs.xml
@@ -33,6 +33,7 @@
     <xi:include href="xml/gdksurface.xml" />
     <xi:include href="xml/gdktoplevel.xml" />
     <xi:include href="xml/gdktoplevellayout.xml" />
+    <xi:include href="xml/gdktoplevelsize.xml" />
     <xi:include href="xml/gdkpopup.xml" />
     <xi:include href="xml/gdkpopuplayout.xml" />
     <xi:include href="xml/gdkframeclock.xml" />
diff --git a/docs/reference/gdk/gdk4-sections.txt b/docs/reference/gdk/gdk4-sections.txt
index 5cff88eb65..c08651d9e6 100644
--- a/docs/reference/gdk/gdk4-sections.txt
+++ b/docs/reference/gdk/gdk4-sections.txt
@@ -345,7 +345,6 @@ GdkAxisUse
 GdkAxisFlags
 GdkDeviceTool
 GdkDeviceToolType
-GdkDeviceType
 
 <SUBSECTION>
 gdk_device_get_name
@@ -684,6 +683,8 @@ gdk_toplevel_get_type
 <TITLE>Textures</TITLE>
 <FILE>textures</FILE>
 GdkTexture
+GdkMemoryTexture
+GdkGLTexture
 gdk_texture_new_for_pixbuf
 gdk_texture_new_from_resource
 gdk_texture_new_from_file
@@ -847,6 +848,8 @@ gdk_x11_surface_move_to_desktop
 gdk_x11_surface_get_desktop
 gdk_x11_surface_set_utf8_property
 gdk_x11_surface_set_frame_sync_enabled
+gdk_x11_surface_set_group
+gdk_x11_surface_get_group
 gdk_x11_keymap_get_group_for_state
 gdk_x11_keymap_key_is_modifier
 gdk_x11_visual_get_xvisual
@@ -1290,4 +1293,3 @@ GDK_CONTENT_DESERIALIZER
 GDK_IS_CONTENT_DESERIALIZER
 gdk_content_deserializer_get_type
 </SECTION>
-
diff --git a/gdk/gdk.c b/gdk/gdk.c
index c874d15260..ae3194bb59 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -319,9 +319,8 @@ gdk_pre_parse (void)
  *
  * Opens the default display specified by command line arguments or
  * environment variables, sets it as the default display, and returns
- * it. gdk_parse_args() must have been called first. If the default
- * display has previously been set, simply returns that. An internal
- * function that should not be used by applications.
+ * it. If the default display has previously been set, simply returns
+ * that. An internal function that should not be used by applications.
  *
  * Returns: (nullable) (transfer none): the default display, if it
  *   could be opened, otherwise %NULL.
diff --git a/gdk/gdkcontentformats.c b/gdk/gdkcontentformats.c
index ec0ac53876..e677e68808 100644
--- a/gdk/gdkcontentformats.c
+++ b/gdk/gdkcontentformats.c
@@ -20,7 +20,7 @@
  * @Title: Content Formats
  * @Short_description: Advertising and negotiating of content
  *     exchange formats
- * @See_also: #GdkDragContext, #GdkClipboard, #GdkContentProvider
+ * @See_also: #GdkDrag, #GdkDrop, #GdkClipboard, #GdkContentProvider
  *
  * This section describes the #GdkContentFormats structure that is used to
  * advertise and negotiate the format of content passed between different
diff --git a/gdk/gdkdevicepad.c b/gdk/gdkdevicepad.c
index 05b620a52b..7e108e9c97 100644
--- a/gdk/gdkdevicepad.c
+++ b/gdk/gdkdevicepad.c
@@ -32,14 +32,12 @@
  * and gdk_device_pad_get_feature_group() can be combined to find out the
  * number of buttons/rings/strips the device has, and how are they grouped.
  *
- * Each of those groups have different modes, which may be used to map
- * each individual pad feature to multiple actions. Only one mode is
- * effective (current) for each given group, different groups may have
- * different current modes. The number of available modes in a group can
- * be found out through gdk_device_pad_get_group_n_modes(), and the current
- * mode for a given group will be notified through the #GdkEventPadGroupMode
- * event.
- *
+ * Each of those groups have different modes, which may be used to map each
+ * individual pad feature to multiple actions. Only one mode is effective
+ * (current) for each given group, different groups may have different
+ * current modes. The number of available modes in a group can be found
+ * out through gdk_device_pad_get_group_n_modes(), and the current mode for
+ * a given group will be notified through events of type #GDK_PAD_GROUP_MODE.
  */
 
 /**
diff --git a/gdk/gdkdisplay.c b/gdk/gdkdisplay.c
index c353c9de50..d4944cdc58 100644
--- a/gdk/gdkdisplay.c
+++ b/gdk/gdkdisplay.c
@@ -54,7 +54,7 @@
  * gdk_display_get_default_seat() and gdk_display_list_seats().
  *
  * Output devices are represented by #GdkMonitor objects, which can be accessed
- * with gdk_display_get_monitor() and similar APIs.
+ * with gdk_display_get_monitor_at_surface() and similar APIs.
  */
 
 /**
@@ -957,9 +957,9 @@ gdk_display_beep (GdkDisplay *display)
  * Flushes any requests queued for the windowing system and waits until all
  * requests have been handled. This is often used for making sure that the
  * display is synchronized with the current state of the program. Calling
- * gdk_display_sync() before gdk_error_trap_pop() makes sure that any errors
- * generated from earlier requests are handled before the error trap is
- * removed.
+ * gdk_display_sync() before gdk_x11_display_error_trap_pop() makes sure
+ * that any errors generated from earlier requests are handled before the
+ * error trap is removed.
  *
  * This is most useful for X11. On windowing systems where requests are
  * handled synchronously, this function will do nothing.
@@ -1320,9 +1320,6 @@ gdk_display_set_composited (GdkDisplay *display,
  * provide appropriate display. Use gdk_display_is_composited()
  * to check if that is the case.
  *
- * For setting an overall opacity for a top-level surface, see
- * gdk_surface_set_opacity().
- *
  * On modern displays, this value is always %TRUE.
  *
  * Returns: %TRUE if surfaces are created with an alpha channel or
diff --git a/gdk/gdkdisplaymanager.c b/gdk/gdkdisplaymanager.c
index bfd5bb8b3c..0635645123 100644
--- a/gdk/gdkdisplaymanager.c
+++ b/gdk/gdkdisplaymanager.c
@@ -296,9 +296,7 @@ static GdkBackend gdk_backends[] = {
  * with multiple backends). Applications can use gdk_set_allowed_backends()
  * to limit what backends can be used.
  *
- * Returns: (transfer none): The global #GdkDisplayManager singleton;
- *     gdk_parse_args(), gdk_init(), or gdk_init_check() must have
- *     been called first.
+ * Returns: (transfer none): The global #GdkDisplayManager singleton
  **/
 GdkDisplayManager*
 gdk_display_manager_get (void)
diff --git a/gdk/gdkdrag.c b/gdk/gdkdrag.c
index 01314f9602..2870d346d6 100644
--- a/gdk/gdkdrag.c
+++ b/gdk/gdkdrag.c
@@ -105,7 +105,7 @@ G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GdkDrag, gdk_drag, G_TYPE_OBJECT)
  * Possible drop sites get informed about the status of the ongoing drag operation
  * with events of type %GDK_DRAG_ENTER, %GDK_DRAG_LEAVE, %GDK_DRAG_MOTION and
  * %GDK_DROP_START. The #GdkDrop object can be obtained from these #GdkEvents
- * using gdk_event_get_drop().
+ * using gdk_dnd_event_get_drop().
  *
  * The actual data transfer is initiated from the target side via an async
  * read, using one of the GdkDrop functions for this purpose: gdk_drop_read_async()
diff --git a/gdk/gdkdrop.c b/gdk/gdkdrop.c
index f5b85c1993..8b2a8b33af 100644
--- a/gdk/gdkdrop.c
+++ b/gdk/gdkdrop.c
@@ -482,7 +482,7 @@ gdk_drop_get_surface (GdkDrop *self)
  * returns %FALSE for the result - gdk_drop_finish() must choose
  * the action to use when accepting the drop. This will only
  * happen if you passed %GDK_ACTION_ASK as one of the possible
- * actions in gdk_drag_status(). %GDK_ACTION_ASK itself will not
+ * actions in gdk_drop_status(). %GDK_ACTION_ASK itself will not
  * be included in the actions returned by this function.
  *
  * This value may change over the lifetime of the #GdkDrop both
diff --git a/gdk/gdkevents.c b/gdk/gdkevents.c
index 147c47e11b..c6ee0decb8 100644
--- a/gdk/gdkevents.c
+++ b/gdk/gdkevents.c
@@ -945,9 +945,9 @@ gdk_event_get_axis (GdkEvent   *event,
  * gdk_event_triggers_context_menu:
  * @event: a #GdkEvent, currently only button events are meaningful values
  *
- * This function returns whether a #GdkEventButton should trigger a
- * context menu, according to platform conventions. The right mouse
- * button always triggers context menus.
+ * This function returns whether a #GdkEvent should trigger a
+ * context menu, according to platform conventions. The right
+ * mouse button always triggers context menus.
  *
  * This function should always be used instead of simply checking for
  * event->button == %GDK_BUTTON_SECONDARY.
diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h
index 0d4888cb6d..3e8dff15db 100644
--- a/gdk/gdkevents.h
+++ b/gdk/gdkevents.h
@@ -252,7 +252,7 @@ typedef enum
  * @GDK_SCROLL_LEFT: the surface is scrolled to the left.
  * @GDK_SCROLL_RIGHT: the surface is scrolled to the right.
  * @GDK_SCROLL_SMOOTH: the scrolling is determined by the delta values
- *   in scroll events. See gdk_event_get_scroll_deltas()
+ *   in scroll events. See gdk_scroll_event_get_deltas()
  *
  * Specifies the direction for scroll events.
  */
diff --git a/gdk/gdkframeclock.c b/gdk/gdkframeclock.c
index cd10511545..612a3c07ad 100644
--- a/gdk/gdkframeclock.c
+++ b/gdk/gdkframeclock.c
@@ -208,8 +208,8 @@ gdk_frame_clock_class_init (GdkFrameClockClass *klass)
    * This signal is emitted as the third step of toolkit and
    * application processing of the frame. The frame is
    * repainted. GDK normally handles this internally and
-   * produces expose events, which are turned into GTK
-   * #GtkWidget::draw signals.
+   * emits #GdkSurface::render which are turned into
+   * #GtkWidget::snapshot signals by GTK.
    */
   signals[PAINT] =
     g_signal_new (g_intern_static_string ("paint"),
diff --git a/gdk/gdkpaintable.c b/gdk/gdkpaintable.c
index 56b13bcd95..1397bbe707 100644
--- a/gdk/gdkpaintable.c
+++ b/gdk/gdkpaintable.c
@@ -56,11 +56,11 @@ void            gtk_snapshot_pop                        (GdkSnapshot
  * A #GdkPaintable may change its contents, meaning that it will now produce a
  * different output with the same snpashot. Once that happens, it will call
  * gdk_paintable_invalidate_contents() which will emit the
- * #GdkPaintable::invalidate-contents signal.  
- * If a paintable is known to never change its contents, it will set the
- * %GDK_PAINTABLE_STATIC_CONTENTS flag. If a consumer cannot deal with changing
- * contents, it may call gdk_paintable_get_static_image() which will return a
- * static paintable and use that.
+ * #GdkPaintable::invalidate-contents signal. If a paintable is known to never
+ * change its contents, it will set the %GDK_PAINTABLE_STATIC_CONTENTS flag.
+ * If a consumer cannot deal with changing contents, it may call
+ * gdk_paintable_get_current_image() which will return a static paintable and
+ * use that.
  *
  * A paintable can report an intrinsic (or preferred) size or aspect ratio it
  * wishes to be rendered at, though it doesn't have to. Consumers of the interface
diff --git a/gdk/gdkpopuplayout.c b/gdk/gdkpopuplayout.c
index 25f16c5e8a..e22017045d 100644
--- a/gdk/gdkpopuplayout.c
+++ b/gdk/gdkpopuplayout.c
@@ -55,13 +55,12 @@ G_DEFINE_BOXED_TYPE (GdkPopupLayout, gdk_popup_layout,
  * @rect_anchor: the point on @anchor_rect to align with @surface's anchor point
  * @surface_anchor: the point on @surface to align with @rect's anchor point
  *
- * Create a popup layout description. Used together with
- * gdk_surface_present_popup() to describe how a popup surface should be placed
- * and behave on-screen.
+ * Create a popup layout description. Used together with gdk_popup_present()
+ * to describe how a popup surface should be placed and behave on-screen.
  *
  * @anchor_rect is relative to the top-left corner of the surface's parent.
- * @rect_anchor and @surface_anchor determine anchor points on @anchor_rect and
- * surface to pin together.
+ * @rect_anchor and @surface_anchor determine anchor points on @anchor_rect
+ * and surface to pin together.
  *
  * The position of @anchor_rect's anchor point can optionally be offset using
  * gdk_popup_layout_set_offset(), which is equivalent to offsetting the
diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c
index 75c35d6d50..7049d3c560 100644
--- a/gdk/gdksurface.c
+++ b/gdk/gdksurface.c
@@ -839,8 +839,8 @@ gdk_surface_new_temp (GdkDisplay         *display,
  *
  * Create a new popup surface.
  *
- * The surface will be attached to @parent and can be positioned relative to it
- * using gdk_surface_show_popup() or later using gdk_surface_layout_popup().
+ * The surface will be attached to @parent and can be positioned
+ * relative to it using gdk_popup_present().
  *
  * Returns: (transfer full): a new #GdkSurface
  */
@@ -1021,8 +1021,8 @@ gdk_surface_is_destroyed (GdkSurface *surface)
  * gdk_surface_get_mapped:
  * @surface: a #GdkSurface
  *
- * Checks whether the surface has been mapped (with gdk_surface_show() or
- * gdk_surface_show_unraised()).
+ * Checks whether the surface has been mapped (with gdk_toplevel_present()
+ * or gdk_popup_present()).
  *
  * Returns: %TRUE if the surface is mapped
  **/
@@ -2024,7 +2024,7 @@ gdk_surface_get_root_coords (GdkSurface *surface,
  * and the input region controls where the surface is
  * “clickable”.
  *
- * Use gdk_display_support_input_shapes() to find out if
+ * Use gdk_display_supports_input_shapes() to find out if
  * a particular backend supports input regions.
  */
 void
diff --git a/gdk/wayland/gdkdisplay-wayland.c b/gdk/wayland/gdkdisplay-wayland.c
index f6cac82264..6d19b8dad5 100644
--- a/gdk/wayland/gdkdisplay-wayland.c
+++ b/gdk/wayland/gdkdisplay-wayland.c
@@ -881,7 +881,7 @@ gdk_wayland_display_get_startup_notification_id (GdkDisplay  *display)
  *
  * The startup ID is also what is used to signal that the startup is
  * complete (for example, when opening a window or when calling
- * gdk_notify_startup_complete()).
+ * gdk_display_notify_startup_complete()).
  **/
 void
 gdk_wayland_display_set_startup_notification_id (GdkDisplay *display,
diff --git a/gdk/win32/gdkdisplay-win32.c b/gdk/win32/gdkdisplay-win32.c
index 788d03870b..0d4f4f97f8 100644
--- a/gdk/win32/gdkdisplay-win32.c
+++ b/gdk/win32/gdkdisplay-win32.c
@@ -336,12 +336,10 @@ _gdk_win32_display_init_monitors (GdkWin32Display *win32_display)
  * should be taken.
  *
  * If the windowing system supports it, existing cursors created
- * with gdk_cursor_new(), gdk_cursor_new_for_display() and
- * gdk_cursor_new_from_name() are updated to reflect the theme
- * change. Custom cursors constructed with
- * gdk_cursor_new_from_texture() will have to be handled
- * by the application (GTK+ applications can learn about
- * cursor theme changes by listening for change notification
+ * with gdk_cursor_new_from_name() are updated to reflect the theme
+ * change. Custom cursors constructed with gdk_cursor_new_from_texture()
+ * will have to be handled by the application (GTK applications can
+ * learn about cursor theme changes by listening for change notification
  * for the corresponding #GtkSetting).
  */
 void
diff --git a/gdk/x11/gdkcursor-x11.c b/gdk/x11/gdkcursor-x11.c
index 3e99403954..cdf304a393 100644
--- a/gdk/x11/gdkcursor-x11.c
+++ b/gdk/x11/gdkcursor-x11.c
@@ -269,12 +269,10 @@ gdk_x11_cursor_create_for_name (GdkDisplay  *display,
  * should be taken.
  *
  * If the windowing system supports it, existing cursors created
- * with gdk_cursor_new(), gdk_cursor_new_for_display() and
- * gdk_cursor_new_from_name() are updated to reflect the theme
- * change. Custom cursors constructed with
- * gdk_cursor_new_from_texture() will have to be handled
- * by the application (GTK+ applications can learn about
- * cursor theme changes by listening for change notification
+ * with gdk_cursor_new_from_name() are updated to reflect the theme
+ * change. Custom cursors constructed with gdk_cursor_new_from_texture()
+ * will have to be handled by the application (GTK applications can learn
+ * about cursor theme changes by listening for change notification
  * for the corresponding #GtkSetting).
  */
 void
diff --git a/gdk/x11/gdkdisplay-x11.c b/gdk/x11/gdkdisplay-x11.c
index a2bcefa67d..414d6dc63e 100644
--- a/gdk/x11/gdkdisplay-x11.c
+++ b/gdk/x11/gdkdisplay-x11.c
@@ -1836,7 +1836,7 @@ gdk_x11_display_has_pending (GdkDisplay *display)
  *
  * Returns the default group leader surface for all toplevel surfaces
  * on @display. This surface is implicitly created by GDK.
- * See gdk_surface_set_group().
+ * See gdk_x11_surface_set_group().
  *
  * Returns: (transfer none): The default group leader surface
  * for @display
@@ -2359,7 +2359,7 @@ gdk_x11_display_get_startup_notification_id (GdkDisplay *display)
  *
  * The startup ID is also what is used to signal that the startup is
  * complete (for example, when opening a window or when calling
- * gdk_notify_startup_complete()).
+ * gdk_display_notify_startup_complete()).
  **/
 void
 gdk_x11_display_set_startup_notification_id (GdkDisplay  *display,
@@ -2542,8 +2542,6 @@ delete_outdated_error_traps (GdkX11Display *display_x11)
  * the application. Use gdk_x11_display_error_trap_pop() or
  * gdk_x11_display_error_trap_pop_ignored()to lift a trap pushed
  * with this function.
- *
- * See also gdk_error_trap_push() to push a trap on all displays.
  */
 void
 gdk_x11_display_error_trap_push (GdkDisplay *display)
@@ -2695,9 +2693,6 @@ gdk_x11_display_set_surface_scale (GdkDisplay *display,
  * If you don’t need to use the return value,
  * gdk_x11_display_error_trap_pop_ignored() would be more efficient.
  *
- * See gdk_error_trap_pop() for the all-displays-at-once
- * equivalent.
- *
  * Returns: X error code or 0 on success
  */
 int
@@ -2716,9 +2711,6 @@ gdk_x11_display_error_trap_pop (GdkDisplay *display)
  * Does not block to see if an error occurred; merely records the
  * range of requests to ignore errors for, and ignores those errors
  * if they arrive asynchronously.
- *
- * See gdk_error_trap_pop_ignored() for the all-displays-at-once
- * equivalent.
  */
 void
 gdk_x11_display_error_trap_pop_ignored (GdkDisplay *display)
diff --git a/gdk/x11/gdkmonitor-x11.c b/gdk/x11/gdkmonitor-x11.c
index 3227e0bd1b..ae58621116 100644
--- a/gdk/x11/gdkmonitor-x11.c
+++ b/gdk/x11/gdkmonitor-x11.c
@@ -117,6 +117,10 @@ gdk_x11_monitor_class_init (GdkX11MonitorClass *class)
 /**
  * gdk_x11_monitor_get_output:
  * @monitor: (type GdkX11Monitor): a #GdkMonitor
+ *
+ * Returns the XID of the Output corresponding to @monitor.
+ *
+ * Returns: the XID of @monitor
  */
 XID
 gdk_x11_monitor_get_output (GdkMonitor *monitor)
diff --git a/gdk/x11/gdkselection-x11.c b/gdk/x11/gdkselection-x11.c
index 26e1b589b5..606901ac61 100644
--- a/gdk/x11/gdkselection-x11.c
+++ b/gdk/x11/gdkselection-x11.c
@@ -43,7 +43,7 @@
  * @length: The number of items to transform
  * @list: location to store an  array of strings in
  *    the encoding of the current locale. This array should be
- *    freed using gdk_free_text_list().
+ *    freed using gdk_x11_free_text_list().
  *
  * Convert a text string from the encoding as it is stored
  * in a property into an array of strings in the encoding of