Move VC diff ASYNC argument to the fifth position

* lisp/vc/vc-svn.el (vc-svn-diff):
* lisp/vc/vc-src.el (vc-src-diff):
* lisp/vc/vc-sccs.el (vc-sccs-diff):
* lisp/vc/vc-rcs.el (vc-rcs-diff):
* lisp/vc/vc-mtn.el (vc-mtn-diff):
* lisp/vc/vc-hg.el (vc-hg-diff):
* lisp/vc/vc-git.el (vc-git-diff):
* lisp/vc/vc-dav.el (vc-dav-diff):
* lisp/vc/vc-cvs.el (vc-cvs-diff):
* lisp/vc/vc-bzr.el (vc-bzr-diff):
* lisp/obsolete/vc-arch.el (vc-arch-diff): Move ASYNC argument to the end.

* lisp/vc/vc.el (vc-diff-internal): Pass `async' argument to the
backend `diff' command in the last position.

13 files changed, 37 insertions, 16 deletions

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 37f637b503a..cb43a9b732f 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,24 @@
+2014-12-14  Dmitry Gutov  <dgutov@yandex.ru>
+
+        Move ASYNC argument to the `diff' VC command to the fifth
+        position, for better compatibility with existing third-party code,
+        and document it.
+
+        * vc/vc.el (vc-diff-internal): Pass `async' argument to the
+        backend `diff' command in the last position.
+
+        * vc/vc-svn.el (vc-svn-diff):
+        * vc/vc-src.el (vc-src-diff):
+        * vc/vc-sccs.el (vc-sccs-diff):
+        * vc/vc-rcs.el (vc-rcs-diff):
+        * vc/vc-mtn.el (vc-mtn-diff):
+        * vc/vc-hg.el (vc-hg-diff):
+        * vc/vc-git.el (vc-git-diff):
+        * vc/vc-dav.el (vc-dav-diff):
+        * vc/vc-cvs.el (vc-cvs-diff):
+        * vc/vc-bzr.el (vc-bzr-diff):
+        * obsolete/vc-arch.el (vc-arch-diff): Move ASYNC argument to the end.
+
 2014-12-13  Andreas Schwab  <schwab@linux-m68k.org>
 
         * net/shr.el (shr-next-link): Don't error out at eob.
diff --git a/lisp/obsolete/vc-arch.el b/lisp/obsolete/vc-arch.el
index d1344f2b1cc..c1ac505270c 100644
--- a/lisp/obsolete/vc-arch.el
+++ b/lisp/obsolete/vc-arch.el
@@ -448,7 +448,7 @@ CALLBACK expects (ENTRIES &optional MORE-TO-COME); see
     (vc-arch-command nil 0 files "commit" "-s" summary "-L" comment "--"
                      (vc-switches 'Arch 'checkin))))
 
-(defun vc-arch-diff (files &optional async oldvers newvers buffer)
+(defun vc-arch-diff (files &optional oldvers newvers buffer async)
   "Get a difference report using Arch between two versions of FILES."
   ;; FIXME: This implementation only works for singleton filesets.  To make
   ;; it work for more cases, we have to either call `file-diffs' manually on
diff --git a/lisp/vc/vc-bzr.el b/lisp/vc/vc-bzr.el
index 1963f4e39ac..de101649802 100644
--- a/lisp/vc/vc-bzr.el
+++ b/lisp/vc/vc-bzr.el
@@ -767,7 +767,7 @@ If LIMIT is non-nil, show no more than this many entries."
 
 (autoload 'vc-switches "vc")
 
-(defun vc-bzr-diff (files &optional async rev1 rev2 buffer)
+(defun vc-bzr-diff (files &optional rev1 rev2 buffer async)
   "VC bzr backend for diff."
   (let* ((switches (vc-switches 'bzr 'diff))
          (args
diff --git a/lisp/vc/vc-cvs.el b/lisp/vc/vc-cvs.el
index a5b50c16e09..c1d32cea605 100644
--- a/lisp/vc/vc-cvs.el
+++ b/lisp/vc/vc-cvs.el
@@ -569,7 +569,7 @@ Remaining arguments are ignored."
 (autoload 'vc-version-backup-file "vc")
 (declare-function vc-coding-system-for-diff "vc" (file))
 
-(defun vc-cvs-diff (files &optional async oldvers newvers buffer)
+(defun vc-cvs-diff (files &optional oldvers newvers buffer async)
   "Get a difference report using CVS between two revisions of FILE."
   (let* (process-file-side-effects
          (async (and async (vc-cvs-stay-local-p files)))
diff --git a/lisp/vc/vc-dav.el b/lisp/vc/vc-dav.el
index 4c3fe6abff7..f107764f404 100644
--- a/lisp/vc/vc-dav.el
+++ b/lisp/vc/vc-dav.el
@@ -117,7 +117,7 @@ only needs to update the status of URL within the backend.
   "Insert the revision log of URL into the *vc* buffer."
   )
 
-(defun vc-dav-diff (url &optional async rev1 rev2)
+(defun vc-dav-diff (url &optional rev1 rev2 buffer async)
   "Insert the diff for URL into the *vc-diff* buffer.
 If REV1 and REV2 are non-nil report differences from REV1 to REV2.
 If REV1 is nil, use the current workfile version as the older version.
diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el
index c41dde1b3db..65f683c7808 100644
--- a/lisp/vc/vc-git.el
+++ b/lisp/vc/vc-git.el
@@ -78,7 +78,7 @@
 ;; - show-log-entry (revision)                     OK
 ;; - comment-history (file)                        ??
 ;; - update-changelog (files)                      COULD BE SUPPORTED
-;; * diff (file &optional rev1 rev2 buffer)        OK
+;; * diff (file &optional rev1 rev2 buffer async)  OK
 ;; - revision-completion-table (files)             OK
 ;; - annotate-command (file buf &optional rev)     OK
 ;; - annotate-time ()                              OK
@@ -977,7 +977,7 @@ or BRANCH^ (where \"^\" can be repeated)."
 
 (autoload 'vc-switches "vc")
 
-(defun vc-git-diff (files &optional async rev1 rev2 buffer)
+(defun vc-git-diff (files &optional rev1 rev2 buffer async)
   "Get a difference report using Git between two revisions of FILES."
   (let (process-file-side-effects)
     (if vc-git-diff-switches
diff --git a/lisp/vc/vc-hg.el b/lisp/vc/vc-hg.el
index 0d9f9f182fa..e65009db2ef 100644
--- a/lisp/vc/vc-hg.el
+++ b/lisp/vc/vc-hg.el
@@ -313,7 +313,7 @@ If LIMIT is non-nil, show no more than this many entries."
 
 (autoload 'vc-switches "vc")
 
-(defun vc-hg-diff (files &optional async oldvers newvers buffer)
+(defun vc-hg-diff (files &optional oldvers newvers buffer async)
   "Get a difference report using hg between two revisions of FILES."
   (let* ((firstfile (car files))
          (working (and firstfile (vc-working-revision firstfile))))
diff --git a/lisp/vc/vc-mtn.el b/lisp/vc/vc-mtn.el
index 7d2f7349897..d1736a42a3d 100644
--- a/lisp/vc/vc-mtn.el
+++ b/lisp/vc/vc-mtn.el
@@ -236,7 +236,7 @@ If LIMIT is non-nil, show no more than this many entries."
 
 (autoload 'vc-switches "vc")
 
-(defun vc-mtn-diff (files &optional async rev1 rev2 buffer)
+(defun vc-mtn-diff (files &optional rev1 rev2 buffer async)
   "Get a difference report using monotone between two revisions of FILES."
   (apply 'vc-mtn-command (or buffer "*vc-diff*")
          (if async 'async 1)
diff --git a/lisp/vc/vc-rcs.el b/lisp/vc/vc-rcs.el
index 8866bdbad96..cb3d36f13fb 100644
--- a/lisp/vc/vc-rcs.el
+++ b/lisp/vc/vc-rcs.el
@@ -535,7 +535,7 @@ files beneath it."
     (vc-rcs-print-log-cleanup))
   (when limit 'limit-unsupported))
 
-(defun vc-rcs-diff (files &optional async oldvers newvers buffer)
+(defun vc-rcs-diff (files &optional oldvers newvers buffer async)
   "Get a difference report using RCS between two sets of files."
   (apply #'vc-do-command (or buffer "*vc-diff*")
          (if async 'async 1)
diff --git a/lisp/vc/vc-sccs.el b/lisp/vc/vc-sccs.el
index 63628647fd4..cfd3cccf9b1 100644
--- a/lisp/vc/vc-sccs.el
+++ b/lisp/vc/vc-sccs.el
@@ -316,7 +316,7 @@ Remaining arguments are ignored."
 (defvar w32-quote-process-args)
 
 ;; FIXME use sccsdiff if present?
-(defun vc-sccs-diff (files &optional _async oldvers newvers buffer)
+(defun vc-sccs-diff (files &optional oldvers newvers buffer _async)
   "Get a difference report using SCCS between two filesets."
   (setq files (vc-expand-dirs files 'SCCS))
   (setq oldvers (vc-sccs-lookup-triple (car files) oldvers))
diff --git a/lisp/vc/vc-src.el b/lisp/vc/vc-src.el
index 539437d185c..50c0a7ef1b0 100644
--- a/lisp/vc/vc-src.el
+++ b/lisp/vc/vc-src.el
@@ -288,7 +288,7 @@ If LIMIT is non-nil, show no more than this many entries."
               (when limit (list "-l" (format "%s" limit)))
               vc-src-log-switches)))))
 
-(defun vc-src-diff (files &optional _async oldvers newvers buffer)
+(defun vc-src-diff (files &optional oldvers newvers buffer _async)
   "Get a difference report using src between two revisions of FILES."
   (let* ((firstfile (car files))
          (working (and firstfile (vc-working-revision firstfile))))
diff --git a/lisp/vc/vc-svn.el b/lisp/vc/vc-svn.el
index 5db26767fda..eedccd81d4c 100644
--- a/lisp/vc/vc-svn.el
+++ b/lisp/vc/vc-svn.el
@@ -548,7 +548,7 @@ If LIMIT is non-nil, show no more than this many entries."
                  (if start-revision (format "-r%s" start-revision) "-rHEAD:0"))
                 (when limit (list "--limit" (format "%s" limit)))))))))
 
-(defun vc-svn-diff (files &optional async oldvers newvers buffer)
+(defun vc-svn-diff (files &optional oldvers newvers buffer async)
   "Get a difference report using SVN between two revisions of fileset FILES."
   (and oldvers
        (not newvers)
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index b8be3ff7df2..954b3cfeb02 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -362,10 +362,10 @@
 ;;   default implementation runs rcs2log, which handles RCS- and
 ;;   CVS-style logs.
 ;;
-;; * diff (files &optional async rev1 rev2 buffer)
+;; * diff (files &optional rev1 rev2 buffer async)
 ;;
 ;;   Insert the diff for FILE into BUFFER, or the *vc-diff* buffer if
-;;   BUFFER is nil.  If ASYNC is non-nil, run asynchronously.If REV1
+;;   BUFFER is nil.  If ASYNC is non-nil, run asynchronously.  If REV1
 ;;   and REV2 are non-nil, report differences from REV1 to REV2.  If
 ;;   REV1 is nil, use the working revision (as found in the
 ;;   repository) as the older revision; if REV2 is nil, use the
@@ -552,7 +552,7 @@
 ;;   revision been even possible, let alone sane.
 ;;
 ;;   INCOMPATIBLE CHANGE: In older versions of the API, vc-diff did
-;;   not take an async-mode flag as a first optional argument.  (This
+;;   not take an async-mode flag as a fourth optional argument.  (This
 ;;   change eliminated a particularly ugly global.)
 ;;
 ;; - INCOMPATIBLE CHANGE: The backend operation for non-distributed
@@ -1691,7 +1691,7 @@ Return t if the buffer had changes, nil otherwise."
                      (if async 'async 1) "diff" file
                      (append (vc-switches nil 'diff) '("/dev/null"))))))
         (setq files (nreverse filtered))))
-    (vc-call-backend (car vc-fileset) 'diff files async rev1 rev2 buffer)
+    (vc-call-backend (car vc-fileset) 'diff files rev1 rev2 buffer async)
     (set-buffer buffer)
     (diff-mode)
     (set (make-local-variable 'diff-vc-backend) (car vc-fileset))