; 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'.

1 files changed, 47 insertions, 42 deletions

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 33592e75041..9f7666ac63c 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.