master 3c5fbfe4ac: Improve DND documentation

[Po Lu]

branch: master
commit 3c5fbfe4ac52fb951918f0b0e6a10bade7590fa5
Author: Po Lu <luangruo@yahoo.com>
Commit: Po Lu <luangruo@yahoo.com>

    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.
---
 doc/lispref/frames.texi | 4 +++-
 src/xfns.c              | 7 ++++++-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index e8765cf958..e87e247496 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 47321a1d6b..4b5d30bca2 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)
 {