Improve DND documentation

* doc/lispref/frames.texi (Drag and Drop):
* src/xfns.c (Fx_begin_drag): Document that x-begin-drag may
return immediately if no mouse buttons are held down.

2 files changed, 9 insertions, 2 deletions

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index e8765cf958e..e87e2474967 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -4067,7 +4067,9 @@ drag-and-drop operation ends, either because the drop was successful,
 or because the drop was rejected.  The drop occurs when all mouse
 buttons are released on top of an X window other than @var{frame} (the
 @dfn{drop target}), or any X window if @var{allow-current-frame} is
-non-@code{nil}.
+non-@code{nil}.  If no mouse buttons are held down when the
+drag-and-drop operation begins, this function may immediately return
+@code{nil}.
 
 @var{targets} is a list of strings describing selection targets, much
 like the @var{data-type} argument to @code{gui-get-selection}, that
diff --git a/src/xfns.c b/src/xfns.c
index 47321a1d6b2..4b5d30bca25 100644
--- a/src/xfns.c
+++ b/src/xfns.c
@@ -6827,7 +6827,12 @@ instead.
 
 If ALLOW-CURRENT-FRAME is not specified or nil, then the drop target
 is allowed to be FRAME.  Otherwise, no action will be taken if the
-mouse buttons are released on top of FRAME.  */)
+mouse buttons are released on top of FRAME.
+
+This function will sometimes return immediately if no mouse buttons
+are currently held down, and should only be called in situations where
+it is known that some are being held down down, such as immediately
+after a `down-mouse-1' event.  */)
   (Lisp_Object targets, Lisp_Object action, Lisp_Object frame,
    Lisp_Object return_frame, Lisp_Object allow_current_frame)
 {