docs: Expand the GDK dnd docs

diff --git a/gdk/gdkdrag.c b/gdk/gdkdrag.c
index acf7a7bede697ce9d1cb1a97ee7584edc39c1333..b99d9dc06fb03241c9315e55ff3c19f2e824771b 100644 (file)
--- a/gdk/gdkdrag.c
+++ b/gdk/gdkdrag.c
@@ -90,19 +90,29 @@ G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GdkDrag, gdk_drag, G_TYPE_OBJECT)
 
 /**
  * SECTION:dnd
- * @title: Drag And Drop
- * @short_description: Functions for controlling drag and drop handling
+ * @Title: Drag And Drop
+ * @Short_description: Functions for controlling drag and drop handling
  *
- * These functions provide a low level interface for drag and drop.
+ * These functions provide a low-level interface for drag and drop.
  *
  * The GdkDrag object represents the source side of an ongoing DND operation.
  * It is created when a drag is started, and stays alive for duration of
- * the DND operation.
+ * the DND operation. After a drag has been started with gdk_drag_begin(),
+ * the caller gets informed about the status of the ongoing drag operation
+ * with signals on the #GtkDrag object.
  *
  * The GdkDrop object represents the target side of an ongoing DND operation.
+ * 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().
+ *
+ * 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(),
+ * gdk_drop_read_value_async() or gdk_read_text_async().
  * 
- * GTK+ provides a higher level abstraction based on top of these functions,
- * and so they are not normally needed in GTK+ applications. See the
+ * GTK provides a higher level abstraction based on top of these functions,
+ * and so they are not normally needed in GTK applications. See the
  * [Drag and Drop][gtk4-Drag-and-Drop] section of the GTK+ documentation
  * for more information.
  */

diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c
index 7158c253f5d11c0a2c3910144c613159183d5f5e..8424576238bcbce2db3258b0d2650a210e2cf538 100644 (file)
--- a/gdk/gdksurface.c
+++ b/gdk/gdksurface.c
@@ -3583,7 +3583,13 @@ gdk_surface_register_dnd (GdkSurface *surface)
  *
  * Starts a drag and creates a new drag context for it.
  *
- * This function is called by the drag source.
+ * This function is called by the drag source. After this call, you
+ * probably want to set up the drag icon using the surface returned
+ * by gdk_drag_get_drag_surface().
+ *
+ * Note: if @actions include %GDK_ACTION_MOVE, you need to listen for
+ * the #GdkDrag::dnd-finished signal and delete the data at the source
+ * if gdk_drag_get_selected_action() returns %GDK_ACTION_MOVE.
  *
  * Returns: (transfer full) (nullable): a newly created #GdkDrag or
  *     %NULL on error.