master dc7623a59e: ; Improve documentation of new drag-and-drop APIs

[Eli Zaretskii]

branch: master
commit dc7623a59e5e90d310cb1c338790a3df5f90e891
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Improve documentation of new drag-and-drop APIs
    
    * lisp/dnd.el (dnd-begin-text-drag, dnd-begin-file-drag):
    * doc/lispref/frames.texi (Drag and Drop): Improve wording of
    documentation of 'dnd-begin-text-drag' and 'dnd-begin-file-drag'.
---
 doc/lispref/frames.texi | 89 ++++++++++++++++++++++++++-----------------------
 lisp/dnd.el             | 40 +++++++++++-----------
 2 files changed, 67 insertions(+), 62 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 33592e7504..9f7666ac63 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -4094,36 +4094,19 @@ specific drag-n-drop protocol being used.  Plain text 
may be
   On capable window systems, Emacs also supports dragging contents
 from its frames to windows of other applications.
 
+@cindex drop target, in drag-and-drop operations
 @defun dnd-begin-text-drag text &optional frame action allow-same-frame
 This function begins dragging text from @var{frame} to another program
-(the drop target), and returns until it is dropped or the
-drag-and-drop operation is cancelled.
-
-The return value is the action that the drop target actually
-performed, which can be one of the following symbols:
-
-@table @code
-@item copy
-The drop target inserted @var{text}.
-
-@item move
-The drop target inserted @var{text}, but in addition the caller should
-delete @var{text} from wherever it originated, such as a buffer.
-
-@item private
-The drop target performed an unspecified action.
-@end table
-
-@code{nil} can also be returned if the drag-and-drop operation was
-cancelled.
-
-@var{text} is the text that will be inserted by the drop target.
+(known as the @dfn{drop target}), and returns the result of
+drag-and-drop operation when the text is dropped or the drag-and-drop
+operation is canceled.  @var{text} is the text that will be inserted
+by the drop target.
 
 @var{action} must be one of the symbols @code{copy} or @code{move},
 where @code{copy} means that @var{text} should be inserted by the drop
 target, and @code{move} means the same as @code{copy}, but in addition
 the caller may have to delete @var{text} from its source as explained
-above.
+below.
 
 @var{frame} is the frame where the mouse is currently held down, or
 @code{nil}, which means to use the selected frame.  This function may
@@ -4133,13 +4116,46 @@ only called immediately after a @code{down-mouse-1} or 
similar event
 event was generated (@pxref{Click Events}).
 
 @var{allow-same-frame} specifies whether or not drops on top of
-@var{frame} itself won't be ignored.
+@var{frame} itself are to be ignored.
+
+The return value specifies the action that the drop target actually
+performed, and optionally what the caller should do.  It can be one of
+the following symbols:
+
+@table @code
+@item copy
+The drop target inserted the dropped text.
+
+@item move
+The drop target inserted the dropped text, but in addition the caller
+should delete @var{text} from wherever it originated, such as its
+buffer.
+
+@item private
+The drop target performed some other unspecified action.
+
+@item nil
+The drag-and-drop operation was canceled.
+@end table
+
 @end defun
 
 @defun dnd-begin-file-drag file &optional frame action allow-same-frame
 This function begins dragging @var{file} from @var{frame} to another
-program, and returns until it is dropped or the drag-and-drop
-operation is cancelled.
+program, and returns the result of the drag-and-drop operation when
+the file is dropped or the drag-and-drop operation is canceled.
+
+If @var{file} is a remote file, then a temporary copy will be made.
+
+@var{action} must be one of the symbols @code{copy}, @code{move} or
+@code{link}, where @code{copy} means that @var{file} should be opened
+or copied by the drop target, @code{move} means the drop target should
+move the file to another location, and @code{link} means the drop
+target should create a symbolic link to @var{file}.  It is an error to
+specify @code{link} as the action if @var{file} is a remote file.
+
+@var{frame} and @var{allow-same-frame} have the same meaning as in
+@code{dnd-begin-text-drag}.
 
 The return value is the action that the drop target actually
 performed, which can be one of the following symbols:
@@ -4156,23 +4172,12 @@ The drop target (usually a file manager) created a 
symbolic link to
 @var{file}.
 
 @item private
-The drop target performed an unspecified action.
-@end table
+The drop target performed some other unspecified action.
 
-@code{nil} can also be returned if the drag-and-drop operation was
-cancelled.
-
-If @var{file} is a remote file, then a temporary copy will be made.
-
-@var{action} must be one of the symbols @code{copy}, @code{move} or
-@code{link}, where @code{copy} means that @var{file} should be opened
-or copied by the drop target, @code{move} means the drop target should
-move the file to another location, and @code{link} means the drop
-target should create a symbolic link to @var{file}.  It is an error to
-specify @code{link} as the action if @var{file} is a remote file.
+@item nil
+The drag-and-drop operation was canceled.
+@end table
 
-@var{frame} and @var{allow-same-frame} mean the same as in
-@code{dnd-begin-text-drag}.
 @end defun
 
 @defun dnd-begin-drag-files files &optional frame action allow-same-frame
@@ -4184,7 +4189,7 @@ dropping multiple files, then the first file will be used 
instead.
 @cindex initiating drag-and-drop, low-level
   The high-level interfaces described above are implemented on top of
 a lower-level primitive.  If you need to drag content other than files
-or text, the low-level interface @code{x-begin-drag} can be used
+or text, use the low-level interface @code{x-begin-drag}
 instead.  However, using it will require detailed knowledge of the
 data types and actions used by the programs to transfer content via
 drag-and-drop on each platform you want to support.
diff --git a/lisp/dnd.el b/lisp/dnd.el
index c5d5788dc4..14d80ac6c5 100644
--- a/lisp/dnd.el
+++ b/lisp/dnd.el
@@ -313,10 +313,10 @@ in that list instead."
   "Begin dragging TEXT from FRAME.
 Initate a drag-and-drop operation allowing the user to drag text
 from Emacs to another program (the drop target), then block until
-the drop happens or is cancelled.
+the drop is completed or is cancelled.
 
-Return the action that the drop target actually performed, which
-can be one of the following symbols:
+If the drop completed, return the action that the drop target
+actually performed, which can be one of the following symbols:
 
   - `copy', which means TEXT was inserted by the drop target.
 
@@ -331,13 +331,13 @@ Return nil if the drop was cancelled.
 
 TEXT is a string containing text that will be inserted by the
 program where the drop happened.  FRAME is the frame where the
-mouse is currently held down, or nil (which means to use the
-current frame).  ACTION is one of the symbols `copy' or `move',
+mouse is currently held down, or nil, which stands for the
+current frame.  ACTION is one of the symbols `copy' or `move',
 where `copy' means that the text should be inserted by the drop
-target, and `move' means the the same as copy, but in addition
+target, and `move' means the the same as `copy', but in addition
 the caller might have to delete TEXT from its source after this
-function returns.  If ALLOW-SAME-FRAME is nil, any drops on FRAME
-itself will be ignored.
+function returns.  If ALLOW-SAME-FRAME is nil, ignore any drops
+on FRAME itself.
 
 This function might return immediately if no mouse buttons are
 currently being held down.  It should only be called upon a
@@ -367,7 +367,7 @@ currently being held down.  It should only be called upon a
 
 (defun dnd-begin-file-drag (file &optional frame action allow-same-frame)
   "Begin dragging FILE from FRAME.
-Initate a drag-and-drop operation allowing the user to drag files
+Initate a drag-and-drop operation allowing the user to drag a file
 from Emacs to another program (the drop target), then block until
 the drop happens or is cancelled.
 
@@ -387,17 +387,17 @@ can be one of the following symbols:
 
 Return nil if the drop was cancelled.
 
-FILE is the file name that will be inserted by the program where
-the drop happened.  If it is a remote file, a temporary copy will
-be made.  FRAME is the frame where the mouse is currently held
-down, or nil (which means to use the current frame).  ACTION is
-one of the symbols `copy', `move' or `link', where `copy' means
-that the file should be opened or copied by the drop target,
-`move' means the drop target should move the file to another
-location, and `link' means the drop target should create a
-symbolic link to FILE.  It is an error to specify `link' as the
-action if FILE is a remote file.  If ALLOW-SAME-FRAME is nil, any
-drops on FRAME itself will be ignored.
+FILE is the file name that will be sent to the program where the
+drop happened.  If it is a remote file, Emacs will make a
+temporary copy and pass that.  FRAME is the frame where the mouse
+is currently held down, or nil (which means to use the current
+frame).  ACTION is one of the symbols `copy', `move' or `link',
+where `copy' means that the file should be opened or copied by
+the drop target, `move' means the drop target should move the
+file to another location, and `link' means the drop target should
+create a symbolic link to FILE.  It is an error to specify `link'
+as the action if FILE is a remote file.  If ALLOW-SAME-FRAME is
+nil, any drops on FRAME itself will be ignored.
 
 This function might return immediately if no mouse buttons are
 currently being held down.  It should only be called upon a