[Emacs-diffs] /srv/bzr/emacs/trunk r112366: Doc fixes related to vc-print-log

[Glenn Morris]

------------------------------------------------------------
revno: 112366
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2013-04-24 00:52:00 -0700
message:
  Doc fixes related to vc-print-log
  
  * vc/vc-bzr.el (vc-bzr-print-log):
  * vc/vc-cvs.el (vc-cvs-print-log):
  * vc/vc-git.el (vc-git-print-log):
  * vc/vc-hg.el (vc-hg-print-log):
  * vc/vc-mtn.el (vc-mtn-print-log):
  * vc/vc-rcs.el (vc-rcs-print-log):
  * vc/vc-sccs.el (vc-sccs-print-log):
  * vc/vc-svn.el (vc-svn-print-log):
  * vc/vc.el (vc-print-log-internal): Doc fixes.
modified:
  lisp/ChangeLog
  lisp/vc/vc-bzr.el
  lisp/vc/vc-cvs.el
  lisp/vc/vc-git.el
  lisp/vc/vc-hg.el
  lisp/vc/vc-mtn.el
  lisp/vc/vc-rcs.el
  lisp/vc/vc-sccs.el
  lisp/vc/vc-svn.el
  lisp/vc/vc.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2013-04-23 21:51:40 +0000
+++ b/lisp/ChangeLog    2013-04-24 07:52:00 +0000
@@ -1,3 +1,15 @@
+2013-04-24  Glenn Morris  <address@hidden>
+
+       * vc/vc-bzr.el (vc-bzr-print-log):
+       * vc/vc-cvs.el (vc-cvs-print-log):
+       * vc/vc-git.el (vc-git-print-log):
+       * vc/vc-hg.el (vc-hg-print-log):
+       * vc/vc-mtn.el (vc-mtn-print-log):
+       * vc/vc-rcs.el (vc-rcs-print-log):
+       * vc/vc-sccs.el (vc-sccs-print-log):
+       * vc/vc-svn.el (vc-svn-print-log):
+       * vc/vc.el (vc-print-log-internal): Doc fixes.
+
 2013-04-23  Glenn Morris  <address@hidden>
 
        * startup.el (normal-no-mouse-startup-screen, normal-about-screen):

=== modified file 'lisp/vc/vc-bzr.el'
--- a/lisp/vc/vc-bzr.el 2013-03-28 03:26:37 +0000
+++ b/lisp/vc/vc-bzr.el 2013-04-24 07:52:00 +0000
@@ -694,7 +694,10 @@
                   ("^ *timestamp: \\(.*\\)" (1 'change-log-date-face)))))))
 
 (defun vc-bzr-print-log (files buffer &optional shortlog start-revision limit)
-  "Get bzr change log for FILES into specified BUFFER."
+  "Print commit log associated with FILES into specified BUFFER.
+If SHORTLOG is non-nil, use --line format.
+If START-REVISION is non-nil, it is the newest revision to show.
+If LIMIT is non-nil, show no more than this many entries."
   ;; `vc-do-command' creates the buffer, but we need it before running
   ;; the command.
   (vc-setup-buffer buffer)

=== modified file 'lisp/vc/vc-cvs.el'
--- a/lisp/vc/vc-cvs.el 2013-04-20 16:24:04 +0000
+++ b/lisp/vc/vc-cvs.el 2013-04-24 07:52:00 +0000
@@ -503,7 +503,8 @@
 (declare-function vc-rcs-print-log-cleanup "vc-rcs" ())
 
 (defun vc-cvs-print-log (files buffer &optional _shortlog _start-revision 
limit)
-  "Get change logs associated with FILES."
+  "Print commit log associated with FILES into specified BUFFER.
+Remaining arguments are ignored."
   (require 'vc-rcs)
   ;; It's just the catenation of the individual logs.
   (vc-cvs-command

=== modified file 'lisp/vc/vc-git.el'
--- a/lisp/vc/vc-git.el 2013-02-01 17:19:24 +0000
+++ b/lisp/vc/vc-git.el 2013-04-24 07:52:00 +0000
@@ -732,9 +732,11 @@
 ;;; HISTORY FUNCTIONS
 
 (defun vc-git-print-log (files buffer &optional shortlog start-revision limit)
-  "Get change log associated with FILES.
-Note that using SHORTLOG requires at least Git version 1.5.6,
-for the --graph option."
+  "Print commit log associated with FILES into specified BUFFER.
+If SHORTLOG is non-nil, use a short format based on `vc-git-root-log-format'.
+\(This requires at least Git version 1.5.6, for the --graph option.)
+If START-REVISION is non-nil, it is the newest revision to show.
+If LIMIT is non-nil, show no more than this many entries."
   (let ((coding-system-for-read vc-git-commits-coding-system))
     ;; `vc-do-command' creates the buffer, but we need it before running
     ;; the command.

=== modified file 'lisp/vc/vc-hg.el'
--- a/lisp/vc/vc-hg.el  2013-04-17 00:50:44 +0000
+++ b/lisp/vc/vc-hg.el  2013-04-24 07:52:00 +0000
@@ -152,7 +152,7 @@
      (2 'change-log-list)
      (3 'change-log-name)
      (4 'change-log-date)))
-  "Mercurial log template for `vc-print-root-log'.
+  "Mercurial log template for `vc-hg-print-log' short format.
 This should be a list (TEMPLATE REGEXP KEYWORDS), where TEMPLATE
 is the \"--template\" argument string to pass to Mercurial,
 REGEXP is a regular expression matching the resulting Mercurial
@@ -246,7 +246,10 @@
   :group 'vc-hg)
 
 (defun vc-hg-print-log (files buffer &optional shortlog start-revision limit)
-  "Get change log associated with FILES."
+  "Print commit log associated with FILES into specified BUFFER.
+If SHORTLOG is non-nil, use a short format based on `vc-hg-root-log-format'.
+If START-REVISION is non-nil, it is the newest revision to show.
+If LIMIT is non-nil, show no more than this many entries."
   ;; `vc-do-command' creates the buffer, but we need it before running
   ;; the command.
   (vc-setup-buffer buffer)

=== modified file 'lisp/vc/vc-mtn.el'
--- a/lisp/vc/vc-mtn.el 2013-02-01 17:19:24 +0000
+++ b/lisp/vc/vc-mtn.el 2013-04-24 07:52:00 +0000
@@ -202,6 +202,10 @@
 ;;   )
 
 (defun vc-mtn-print-log (files buffer &optional _shortlog start-revision limit)
+  "Print commit logs associated with FILES into specified BUFFER.
+_SHORTLOG is ignored.
+If START-REVISION is non-nil, it is the newest revision to show.
+If LIMIT is non-nil, show no more than this many entries."
   (apply 'vc-mtn-command buffer 0 files "log"
         (append
          (when start-revision (list "--from" (format "%s" start-revision)))

=== modified file 'lisp/vc/vc-rcs.el'
--- a/lisp/vc/vc-rcs.el 2013-01-01 09:11:05 +0000
+++ b/lisp/vc/vc-rcs.el 2013-04-24 07:52:00 +0000
@@ -567,10 +567,14 @@
     (when (looking-at "[\b\t\n\v\f\r ]+")
       (delete-char (- (match-end 0) (match-beginning 0))))))
 
-(defun vc-rcs-print-log (files buffer &optional shortlog 
start-revision-ignored limit)
-  "Get change log associated with FILE.  If FILE is a
-directory the operation is applied to all registered files beneath it."
-  (vc-do-command (or buffer "*vc*") 0 "rlog" (mapcar 'vc-name (vc-expand-dirs 
files)))
+(defun vc-rcs-print-log (files buffer &optional shortlog
+                               start-revision-ignored limit)
+  "Print commit log associated with FILES into specified BUFFER.
+Remaining arguments are ignored.
+If FILE is a directory the operation is applied to all registered
+files beneath it."
+  (vc-do-command (or buffer "*vc*") 0 "rlog"
+                 (mapcar 'vc-name (vc-expand-dirs files)))
   (with-current-buffer (or buffer "*vc*")
     (vc-rcs-print-log-cleanup))
   (when limit 'limit-unsupported))

=== modified file 'lisp/vc/vc-sccs.el'
--- a/lisp/vc/vc-sccs.el        2013-01-01 09:11:05 +0000
+++ b/lisp/vc/vc-sccs.el        2013-04-24 07:52:00 +0000
@@ -350,7 +350,8 @@
 ;;;
 
 (defun vc-sccs-print-log (files buffer &optional shortlog 
start-revision-ignored limit)
-  "Get change log associated with FILES."
+  "Print commit log associated with FILES into specified BUFFER.
+Remaining arguments are ignored."
   (setq files (vc-expand-dirs files))
   (vc-sccs-do-command buffer 0 "prs" (mapcar 'vc-name files))
   (when limit 'limit-unsupported))

=== modified file 'lisp/vc/vc-svn.el'
--- a/lisp/vc/vc-svn.el 2013-02-11 01:07:05 +0000
+++ b/lisp/vc/vc-svn.el 2013-04-24 07:52:00 +0000
@@ -494,7 +494,10 @@
   (set (make-local-variable 'log-view-per-file-logs) nil))
 
 (defun vc-svn-print-log (files buffer &optional shortlog start-revision limit)
-  "Get change log(s) associated with FILES."
+  "Print commit log associated with FILES into specified BUFFER.
+SHORTLOG is ignored.
+If START-REVISION is non-nil, it is the newest revision to show.
+If LIMIT is non-nil, show no more than this many entries."
   (save-current-buffer
     (vc-setup-buffer buffer)
     (let ((inhibit-read-only t))

=== modified file 'lisp/vc/vc.el'
--- a/lisp/vc/vc.el     2013-04-21 00:37:54 +0000
+++ b/lisp/vc/vc.el     2013-04-24 07:52:00 +0000
@@ -356,9 +356,11 @@
 ;;   If LIMIT is true insert only insert LIMIT log entries.  If the
 ;;   backend does not support limiting the number of entries to show
 ;;   it should return `limit-unsupported'.
-;;   If START-REVISION is given, then show the log starting from the
-;;   revision.  At this point START-REVISION is only required to work
-;;   in conjunction with LIMIT = 1.
+;;   If START-REVISION is given, then show the log starting from that
+;;   revision ("starting" in the sense of it being the _newest_
+;;   revision shown, rather than the working revision, which is normally
+;;   the case).  Not all backends support this.  At present, this is
+;;   only ever used with LIMIT = 1 (by vc-annotate-show-log-revision-at-line).
 ;;
 ;; * log-outgoing (backend remote-location)
 ;;
@@ -2111,14 +2113,11 @@
                                       &optional is-start-revision limit)
   "For specified BACKEND and FILES, show the VC log.
 Leave point at WORKING-REVISION, if it is non-nil.
-If IS-START-REVISION is non-nil, start the log from WORKING-REVISION.
-Show up to LIMIT entries (non-nil means unlimited).
-\(IS-START-REVISION non-nil might not work correctly if LIMIT is not 1.)"
-  ;; The parenthetical remark is based on the commentary of vc.el for
-  ;; "print log": "At this point START-REVISION is only required to work
-  ;; in conjunction with LIMIT = 1."  The only thing that passes
-  ;; IS-START-REVISION non-nil is vc-annotate-show-log-revision-at-line,
-  ;; which sets LIMIT = 1.
+If IS-START-REVISION is non-nil, start the log from WORKING-REVISION
+\(not all backends support this); i.e., show only WORKING-REVISION and
+earlier revisions.  Show up to LIMIT entries (non-nil means unlimited)."
+  ;; As of 2013/04 the only thing that passes IS-START-REVISION non-nil
+  ;; is vc-annotate-show-log-revision-at-line, which sets LIMIT = 1.
 
   ;; Don't switch to the output buffer before running the command,
   ;; so that any buffer-local settings in the vc-controlled