[Emacs-diffs] emacs-26 72d07d1: Ediff: add some missing documentation

[Philipp Stephani]

branch: emacs-26
commit 72d07d1950a88f9f08d8ad5f45cdf0f3353e1500
Author: Philipp Stephani <address@hidden>
Commit: Philipp Stephani <address@hidden>

    Ediff: add some missing documentation
    
    * vc/ediff.el (ediff-files, ediff-files3, ediff-buffers)
    (ediff-buffers3, ediff-merge-directories)
    (ediff-merge-directories-with-ancestor)
    (ediff-merge-directory-revisions)
    (ediff-merge-directory-revisions-with-ancestor)
    (ediff-windows-wordwise, ediff-windows-linewise)
    (ediff-regions-wordwise, ediff-regions-linewise)
    (ediff-merge-files, ediff-merge-files-with-ancestor)
    (ediff-merge-buffers, ediff-merge-buffers-with-ancestor)
    (ediff-merge-revisions, ediff-merge-revisions-with-ancestor)
    (ediff-patch-file, ediff-revision): Document missing arguments.
    (ediff-patch-buffer, ediff-revision): Add second space after
    period.
    (ediff-files-command, ediff3-files-command, ediff-merge-command)
    (ediff-merge-with-ancestor-command, ediff-directories-command)
    (ediff-directories3-command, ediff-merge-directories-command): Add
    documentation for the command line functions.
---
 lisp/vc/ediff.el | 125 ++++++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 100 insertions(+), 25 deletions(-)

diff --git a/lisp/vc/ediff.el b/lisp/vc/ediff.el
index d0f8e63..0adf513 100644
--- a/lisp/vc/ediff.el
+++ b/lisp/vc/ediff.el
@@ -185,7 +185,9 @@
 
 ;;;###autoload
 (defun ediff-files (file-A file-B &optional startup-hooks)
-  "Run Ediff on a pair of files, FILE-A and FILE-B."
+  "Run Ediff on a pair of files, FILE-A and FILE-B.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
   (interactive
    (let ((dir-A (if ediff-use-last-dir
                    ediff-last-dir-A
@@ -221,7 +223,9 @@
 
 ;;;###autoload
 (defun ediff-files3 (file-A file-B file-C &optional startup-hooks)
-  "Run Ediff on three files, FILE-A, FILE-B, and FILE-C."
+  "Run Ediff on three files, FILE-A, FILE-B, and FILE-C.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
   (interactive
    (let ((dir-A (if ediff-use-last-dir
                    ediff-last-dir-A
@@ -419,7 +423,14 @@ If this file is a backup, `ediff' it with its original."
 
 ;;;###autoload
 (defun ediff-buffers (buffer-A buffer-B &optional startup-hooks job-name)
-  "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B."
+  "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers.  JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-buffers', but can also be one of
+`ediff-merge-files-with-ancestor', `ediff-last-dir-ancestor',
+`ediff-last-dir-C', `ediff-buffers3', `ediff-merge-buffers', or
+`ediff-merge-buffers-with-ancestor'."
   (interactive
    (let (bf)
      (list (setq bf (read-buffer "Buffer A to compare: "
@@ -441,7 +452,14 @@ If this file is a backup, `ediff' it with its original."
 ;;;###autoload
 (defun ediff-buffers3 (buffer-A buffer-B buffer-C
                                 &optional startup-hooks job-name)
-  "Run Ediff on three buffers, BUFFER-A, BUFFER-B, and BUFFER-C."
+  "Run Ediff on three buffers, BUFFER-A, BUFFER-B, and BUFFER-C.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers.  JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-buffers3', but can also be one of
+`ediff-merge-files-with-ancestor', `ediff-last-dir-ancestor',
+`ediff-last-dir-C', `ediff-buffers', `ediff-merge-buffers', or
+`ediff-merge-buffers-with-ancestor'."
   (interactive
    (let (bf bff)
      (list (setq bf (read-buffer "Buffer A to compare: "
@@ -637,7 +655,8 @@ regular expression; only file names that match the regexp 
are considered."
 (defun ediff-merge-directories (dir1 dir2 regexp &optional merge-autostore-dir)
   "Run Ediff on a pair of directories, DIR1 and DIR2, merging files that have
 the same name in both.  The third argument, REGEXP, is nil or a regular
-expression; only file names that match the regexp are considered."
+expression; only file names that match the regexp are considered.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
   (interactive
    (let ((dir-A (ediff-get-default-directory-name))
         (default-regexp (eval ediff-default-filtering-regexp))
@@ -674,7 +693,8 @@ expression; only file names that match the regexp are 
considered."
 Ediff merges files that have identical names in DIR1, DIR2.  If a pair of files
 in DIR1 and DIR2 doesn't have an ancestor in ANCESTOR-DIR, Ediff will merge
 without ancestor.  The fourth argument, REGEXP, is nil or a regular expression;
-only file names that match the regexp are considered."
+only file names that match the regexp are considered.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
   (interactive
    (let ((dir-A (ediff-get-default-directory-name))
         (default-regexp (eval ediff-default-filtering-regexp))
@@ -710,7 +730,8 @@ only file names that match the regexp are considered."
                                             &optional merge-autostore-dir)
   "Run Ediff on a directory, DIR1, merging its files with their revisions.
 The second argument, REGEXP, is a regular expression that filters the file
-names.  Only the files that are under revision control are taken into account."
+names.  Only the files that are under revision control are taken into account.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
   (interactive
    (let ((dir-A (ediff-get-default-directory-name))
         (default-regexp (eval ediff-default-filtering-regexp))
@@ -740,7 +761,8 @@ names.  Only the files that are under revision control are 
taken into account."
                                                           merge-autostore-dir)
   "Run Ediff on a directory, DIR1, merging its files with their revisions and 
ancestors.
 The second argument, REGEXP, is a regular expression that filters the file
-names.  Only the files that are under revision control are taken into account."
+names.  Only the files that are under revision control are taken into account.
+MERGE-AUTOSTORE-DIR is the directory in which to store merged files."
   (interactive
    (let ((dir-A (ediff-get-default-directory-name))
         (default-regexp (eval ediff-default-filtering-regexp))
@@ -908,7 +930,9 @@ names.  Only the files that are under revision control are 
taken into account."
 With prefix argument, DUMB-MODE, or on a non-windowing display, works as
 follows:
 If WIND-A is nil, use selected window.
-If WIND-B is nil, use window next to WIND-A."
+If WIND-B is nil, use window next to WIND-A.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
   (interactive "P")
   (ediff-windows dumb-mode wind-A wind-B
                 startup-hooks 'ediff-windows-wordwise 'word-mode))
@@ -919,7 +943,9 @@ If WIND-B is nil, use window next to WIND-A."
 With prefix argument, DUMB-MODE, or on a non-windowing display, works as
 follows:
 If WIND-A is nil, use selected window.
-If WIND-B is nil, use window next to WIND-A."
+If WIND-B is nil, use window next to WIND-A.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
   (interactive "P")
   (ediff-windows dumb-mode wind-A wind-B
                 startup-hooks 'ediff-windows-linewise nil))
@@ -963,9 +989,12 @@ If WIND-B is nil, use window next to WIND-A."
 ;;;###autoload
 (defun ediff-regions-wordwise (buffer-A buffer-B &optional startup-hooks)
   "Run Ediff on a pair of regions in specified buffers.
+BUFFER-A and BUFFER-B are the buffers to be compared.
 Regions (i.e., point and mark) can be set in advance or marked interactively.
 This function is effective only for relatively small regions, up to 200
-lines.  For large regions, use `ediff-regions-linewise'."
+lines.  For large regions, use `ediff-regions-linewise'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
   (interactive
    (let (bf)
      (list (setq bf (read-buffer "Region's A buffer: "
@@ -1003,10 +1032,13 @@ lines.  For large regions, use 
`ediff-regions-linewise'."
 ;;;###autoload
 (defun ediff-regions-linewise (buffer-A buffer-B &optional startup-hooks)
   "Run Ediff on a pair of regions in specified buffers.
+BUFFER-A and BUFFER-B are the buffers to be compared.
 Regions (i.e., point and mark) can be set in advance or marked interactively.
 Each region is enlarged to contain full lines.
 This function is effective for large regions, over 100-200
-lines.  For small regions, use `ediff-regions-wordwise'."
+lines.  For small regions, use `ediff-regions-wordwise'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
   (interactive
    (let (bf)
      (list (setq bf (read-buffer "Region A's buffer: "
@@ -1127,7 +1159,11 @@ lines.  For small regions, use `ediff-regions-wordwise'."
                                 ;; MERGE-BUFFER-FILE is the file to be
                                 ;; associated with the merge buffer
                                 &optional startup-hooks merge-buffer-file)
-  "Merge two files without ancestor."
+  "Merge two files without ancestor.
+FILE-A and FILE-B are the names of the files to be merged.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers.  MERGE-BUFFER-FILE
+is the name of the file to be associated with the merge buffer.."
   (interactive
    (let ((dir-A (if ediff-use-last-dir
                    ediff-last-dir-A
@@ -1171,7 +1207,12 @@ lines.  For small regions, use `ediff-regions-wordwise'."
                                               ;; to be associated with the
                                               ;; merge buffer
                                               merge-buffer-file)
-  "Merge two files with ancestor."
+  "Merge two files with ancestor.
+FILE-A and FILE-B are the names of the files to be merged, and
+FILE-ANCESTOR is the name of the ancestor file.  STARTUP-HOOKS is
+a list of functions that Emacs calls without arguments after
+setting up the Ediff buffers.  MERGE-BUFFER-FILE is the name of
+the file to be associated with the merge buffer."
   (interactive
    (let ((dir-A (if ediff-use-last-dir
                    ediff-last-dir-A
@@ -1229,7 +1270,16 @@ lines.  For small regions, use `ediff-regions-wordwise'."
                                     ;; MERGE-BUFFER-FILE is the file to be
                                     ;; associated with the merge buffer
                                     startup-hooks job-name merge-buffer-file)
-  "Merge buffers without ancestor."
+  "Merge buffers without ancestor.
+BUFFER-A and BUFFER-B are the buffers to be merged.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers.  JOB-NAME is a
+symbol describing the Ediff job type; it defaults to
+`ediff-merge-buffers', but can also be one of
+`ediff-merge-files-with-ancestor', `ediff-last-dir-ancestor',
+`ediff-last-dir-C', `ediff-buffers', `ediff-buffers3', or
+`ediff-merge-buffers-with-ancestor'.  MERGE-BUFFER-FILE is the
+name of the file to be associated with the merge buffer."
   (interactive
    (let (bf)
      (list (setq bf (read-buffer "Buffer A to merge: "
@@ -1256,7 +1306,16 @@ lines.  For small regions, use `ediff-regions-wordwise'."
                                                   ;; file to be associated
                                                   ;; with the merge buffer
                                                   merge-buffer-file)
-  "Merge buffers with ancestor."
+  "Merge buffers with ancestor.
+BUFFER-A and BUFFER-B are the buffers to be merged, and
+BUFFER-ANCESTOR is their ancestor.  STARTUP-HOOKS is a list of
+functions that Emacs calls without arguments after setting up the
+Ediff buffers.  JOB-NAME is a symbol describing the Ediff job
+type; it defaults to `ediff-merge-buffers-with-ancestor', but can
+also be one of `ediff-merge-files-with-ancestor',
+`ediff-last-dir-ancestor', `ediff-last-dir-C', `ediff-buffers',
+`ediff-buffers3', or `ediff-merge-buffers'.  MERGE-BUFFER-FILE is
+the name of the file to be associated with the merge buffer."
   (interactive
    (let (bf bff)
      (list (setq bf (read-buffer "Buffer A to merge: "
@@ -1287,8 +1346,11 @@ lines.  For small regions, use `ediff-regions-wordwise'."
 (defun ediff-merge-revisions (&optional file startup-hooks merge-buffer-file)
   ;; MERGE-BUFFER-FILE is the file to be associated with the merge buffer
   "Run Ediff by merging two revisions of a file.
-The file is the optional FILE argument or the file visited by the current
-buffer."
+The file is the optional FILE argument or the file visited by the
+current buffer.  STARTUP-HOOKS is a list of functions that Emacs
+calls without arguments after setting up the Ediff buffers.
+MERGE-BUFFER-FILE is the name of the file to be associated with
+the merge buffer."
   (interactive)
   (if (stringp file) (find-file file))
   (let (rev1 rev2)
@@ -1319,8 +1381,11 @@ buffer."
                                            ;; buffer
                                            merge-buffer-file)
   "Run Ediff by merging two revisions of a file with a common ancestor.
-The file is the optional FILE argument or the file visited by the current
-buffer."
+The file is the optional FILE argument or the file visited by the
+current buffer.  STARTUP-HOOKS is a list of functions that Emacs
+calls without arguments after setting up the Ediff buffers.
+MERGE-BUFFER-FILE is the name of the file to be associated with
+the merge buffer."
   (interactive)
   (if (stringp file) (find-file file))
   (let (rev1 rev2 ancestor-rev)
@@ -1360,8 +1425,8 @@ buffer."
   "Query for a file name, and then run Ediff by patching that file.
 If optional PATCH-BUF is given, use the patch in that buffer
 and don't ask the user.
-If prefix argument, then: if even argument, assume that the patch is in a
-buffer. If odd -- assume it is in a file."
+If prefix argument ARG, then: if even argument, assume that the
+patch is in a buffer.  If odd -- assume it is in a file."
   (interactive "P")
   (let (source-dir source-file)
     (require 'ediff-ptch)
@@ -1394,7 +1459,7 @@ prompts for the buffer or a file, depending on the answer.
 With ARG=1, assumes the patch is in a file and prompts for the file.
 With ARG=2, assumes the patch is in a buffer and prompts for the buffer.
 PATCH-BUF is an optional argument, which specifies the buffer that contains the
-patch. If not given, the user is prompted according to the prefix argument."
+patch.  If not given, the user is prompted according to the prefix argument."
   (interactive "P")
   (require 'ediff-ptch)
   (setq patch-buf
@@ -1421,7 +1486,9 @@ patch. If not given, the user is prompted according to 
the prefix argument."
   "Run Ediff by comparing versions of a file.
 The file is an optional FILE argument or the file entered at the prompt.
 Default: the file visited by the current buffer.
-Uses `vc.el' or `rcs.el' depending on `ediff-version-control-package'."
+Uses `vc.el' or `rcs.el' depending on `ediff-version-control-package'.
+STARTUP-HOOKS is a list of functions that Emacs calls without
+arguments after setting up the Ediff buffers."
   ;; if buffer is non-nil, use that buffer instead of the current buffer
   (interactive "P")
   (if (not (stringp file))
@@ -1434,7 +1501,7 @@ Uses `vc.el' or `rcs.el' depending on 
`ediff-version-control-package'."
                                'no-dirs)))
   (find-file file)
   (if (and (buffer-modified-p)
-          (y-or-n-p (format "Buffer %s is modified. Save buffer? "
+          (y-or-n-p (format "Buffer %s is modified.  Save buffer? "
                              (buffer-name))))
       (save-buffer (current-buffer)))
   (let (rev1 rev2)
@@ -1517,6 +1584,7 @@ With optional NODE, goes to that node."
 
 ;;;###autoload
 (defun ediff-files-command ()
+  "Call `ediff-files' with the next two command line arguments."
   (let ((file-a (nth 0 command-line-args-left))
        (file-b (nth 1 command-line-args-left)))
     (setq command-line-args-left (nthcdr 2 command-line-args-left))
@@ -1524,6 +1592,7 @@ With optional NODE, goes to that node."
 
 ;;;###autoload
 (defun ediff3-files-command ()
+  "Call `ediff3-files' with the next three command line arguments."
   (let ((file-a (nth 0 command-line-args-left))
        (file-b (nth 1 command-line-args-left))
        (file-c (nth 2 command-line-args-left)))
@@ -1532,6 +1601,7 @@ With optional NODE, goes to that node."
 
 ;;;###autoload
 (defun ediff-merge-command ()
+  "Call `ediff-merge-files' with the next two command line arguments."
   (let ((file-a (nth 0 command-line-args-left))
        (file-b (nth 1 command-line-args-left)))
     (setq command-line-args-left (nthcdr 2 command-line-args-left))
@@ -1539,6 +1609,7 @@ With optional NODE, goes to that node."
 
 ;;;###autoload
 (defun ediff-merge-with-ancestor-command ()
+  "Call `ediff-merge-files-with-ancestor' with the next three command line 
arguments."
   (let ((file-a (nth 0 command-line-args-left))
        (file-b (nth 1 command-line-args-left))
        (ancestor (nth 2 command-line-args-left)))
@@ -1547,6 +1618,7 @@ With optional NODE, goes to that node."
 
 ;;;###autoload
 (defun ediff-directories-command ()
+  "Call `ediff-directories' with the next three command line arguments."
   (let ((file-a (nth 0 command-line-args-left))
        (file-b (nth 1 command-line-args-left))
        (regexp (nth 2 command-line-args-left)))
@@ -1555,6 +1627,7 @@ With optional NODE, goes to that node."
 
 ;;;###autoload
 (defun ediff-directories3-command ()
+  "Call `ediff-directories3' with the next four command line arguments."
   (let ((file-a (nth 0 command-line-args-left))
        (file-b (nth 1 command-line-args-left))
        (file-c (nth 2 command-line-args-left))
@@ -1564,6 +1637,7 @@ With optional NODE, goes to that node."
 
 ;;;###autoload
 (defun ediff-merge-directories-command ()
+  "Call `ediff-merge-directories' with the next three command line arguments."
   (let ((file-a (nth 0 command-line-args-left))
        (file-b (nth 1 command-line-args-left))
        (regexp (nth 2 command-line-args-left)))
@@ -1572,6 +1646,7 @@ With optional NODE, goes to that node."
 
 ;;;###autoload
 (defun ediff-merge-directories-with-ancestor-command ()
+  "Call `ediff-merge-directories-with-ancestor' with the next four command 
line arguments."
   (let ((file-a (nth 0 command-line-args-left))
        (file-b (nth 1 command-line-args-left))
        (ancestor (nth 2 command-line-args-left))