[gtk/dnd-gestures-2: 6/6] docs: Expand the GDK dnd docs

[Matthias Clasen <matthiasc src gnome org>]

commit ac05730e0fe1df84fdeb16fa6cea38aaed9592d4
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Jan 7 02:15:22 2020 -0500

    docs: Expand the GDK dnd docs

 gdk/gdkdrag.c    | 22 ++++++++++++++++------
 gdk/gdksurface.c |  8 +++++++-
 2 files changed, 23 insertions(+), 7 deletions(-)
---
diff --git a/gdk/gdkdrag.c b/gdk/gdkdrag.c
index acf7a7bede..b99d9dc06f 100644
--- 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 7158c253f5..8424576238 100644
--- 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.