changeset 41071:cb1ebde1c4c9

Documentation fixes.

--- a/lisp/vc.el	Thu Nov 15 10:30:09 2001 +0000
+++ b/lisp/vc.el	Thu Nov 15 10:31:17 2001 +0000
@@ -6,7 +6,7 @@
 ;; Maintainer: Andre Spiegel <[e-mail]>
 ;; Keywords: tools
 
-;; $Id: vc.el,v 1.318 2001/11/09 14:55:52 spiegel Exp $
+;; $Id: vc.el,v 1.319 2001/11/12 23:01:17 sds Exp $
 
 ;; This file is part of GNU Emacs.
 
@@ -36,10 +36,10 @@
 ;;   Martin Lorentzson <[e-mail]>
 ;;   Dave Love <[e-mail]>
 ;;   Stefan Monnier <[e-mail]>
-;;   John David Smith <[e-mail]>
+;;   J.D. Smith <[e-mail]>
 ;;   Andre Spiegel <[e-mail]>
 ;;   Richard Stallman <[e-mail]>
-;;   [e-mail]
+;;   Thien-Thi Nguyen <[e-mail]>
 
 ;;; Commentary:
 
@@ -484,7 +484,7 @@
   :version "20.3")
 
 (defcustom vc-directory-exclusion-list '("SCCS" "RCS" "CVS")
-  "*List of directory names to be ignored while recursively walking file trees."
+  "*List of directory names to be ignored when walking directory trees."
   :type '(repeat string)
   :group 'vc)
 
@@ -508,14 +508,14 @@
 
 ;;;###autoload
 (defcustom vc-checkout-hook nil
-  "*Normal hook (list of functions) run after a file has been checked out.
+  "*Normal hook (list of functions) run after checking out a file.
 See `run-hooks'."
   :type 'hook
   :group 'vc
   :version "21.1")
 
 (defcustom vc-annotate-display-mode nil
-  "Which mode to color the annotations with by default."
+  "Which mode to color the output of \\[vc-annotate] with by default."
   :type '(choice (const :tag "Default" nil)
 		 (const :tag "Scale to Oldest" scale)
 		 (const :tag "Scale Oldest->Newest" fullscale)
@@ -533,7 +533,7 @@
 
 ;;;###autoload
 (defcustom vc-before-checkin-hook nil
-  "*Normal hook (list of functions) run before a file gets checked in.
+  "*Normal hook (list of functions) run before a file is checked in.
 See `run-hooks'."
   :type 'hook
   :group 'vc)
@@ -564,14 +564,14 @@
     (300. . "#00EEFF")
     (320. . "#00B6FF")
     (340. . "#007EFF"))
-  "*ASSOCIATION list of age versus color, for \\[vc-annotate].
+  "*Association list of age versus color, for \\[vc-annotate].
 Ages are given in units of fractional days.  Default is eighteen steps
 using a twenty day increment."
   :type 'alist
   :group 'vc)
 
 (defcustom vc-annotate-very-old-color "#0046FF"
-  "*Color for lines older than CAR of last cons in `vc-annotate-color-map'."
+  "*Color for lines older than the current color range in \\[vc-annotate]]."
   :type 'string
   :group 'vc)
 
@@ -615,7 +615,7 @@
 
 (defcustom vc-comment-alist
   '((nroff-mode ".\\\"" ""))
-  "*Special comment delimiters to be used in generating vc headers only.
+  "*Special comment delimiters for generating VC headers.
 Add an entry in this list if you need to override the normal `comment-start'
 and `comment-end' variables.  This will only be necessary if the mode language
 is sensitive to blank lines."
@@ -625,12 +625,12 @@
 		       (string :tag "Comment End")))
   :group 'vc)
 
-;; Default is to be extra careful for super-user.
-;; TODO: This variable is no longer used; the corresponding checks
-;;       are always done now.  If that turns out to be fast enough,
-;;       the variable can be obsoleted.
 (defcustom vc-checkout-carefully (= (user-uid) 0)
-  "*Non-nil means be extra-careful in checkout.
+  "*This variable is obsolete
+The corresponding checks are always done now.
+From the old doc string:
+
+Non-nil means be extra-careful in checkout.
 Verify that the file really is not locked
 and that its contents match what the master file says."
   :type 'boolean
@@ -722,10 +722,10 @@
   (setq vc-comment-ring (make-ring vc-maximum-comment-ring-size)))
 
 (defmacro with-vc-properties (file form settings)
-  "Execute FORM, then set per-file properties for FILE,
-but only those that have not been set during the execution of FORM.
-SETTINGS is a list of two-element lists, each of which has the
-  form (PROPERTY . VALUE)."
+  "Execute FORM, then maybe set per-file properties for FILE.
+SETTINGS is an association list of property/value pairs.  After
+executing FORM, set those properties from SETTINGS that have not yet
+been updated to their corresponding values."
   `(let ((vc-touched-properties (list t))
 	 (filename ,file))
      ,form
@@ -739,13 +739,14 @@
 ;; Random helper functions
 
 (defsubst vc-editable-p (file)
+  "Return non-nil if FILE can be edited."
   (or (eq (vc-checkout-model file) 'implicit)
       (memq (vc-state file) '(edited needs-merge))))
 
 ;; Two macros for elisp programming
 ;;;###autoload
 (defmacro with-vc-file (file comment &rest body)
-  "Check out a writable copy of FILE if necessary and execute the body.
+  "Check out a writable copy of FILE if necessary, then execute BODY.
 Check in FILE with COMMENT (a string) after BODY has been executed.
 FILE is passed through `expand-file-name'; BODY executed within
 `save-excursion'.  If FILE is not under version control, or locked by
@@ -803,7 +804,7 @@
 	(set-marker (process-mark p) (point))))))
 
 (defun vc-setup-buffer (&optional buf)
-  "Prepare BUF for executing a VC command and make it the current buffer.
+  "Prepare BUF for executing a VC command and make it current.
 BUF defaults to \"*vc*\", can be a string and will be created if necessary."
   (unless buf (setq buf "*vc*"))
   (let ((camefrom (current-buffer))
@@ -847,11 +848,11 @@
 (defvar vc-post-command-functions nil
   "Hook run at the end of `vc-do-command'.
 Each function is called inside the buffer in which the command was run
-and is passed 3 argument: the COMMAND, the FILE and the FLAGS.")
+and is passed 3 arguments: the COMMAND, the FILE and the FLAGS.")
 
 ;;;###autoload
 (defun vc-do-command (buffer okstatus command file &rest flags)
-  "Execute a version control command, notifying user and checking for errors.
+  "Execute a VC command, notifying user and checking for errors.
 Output from COMMAND goes to BUFFER, or *vc* if BUFFER is nil or the
 current buffer if BUFFER is t.  If the destination buffer is not
 already current, set it up properly and erase it.  The command is
@@ -922,7 +923,8 @@
 			  (min (point-max) (+ posn 100)))))
 
 (defun vc-find-position-by-context (context)
-  "Return the position of CONTEXT in the current buffer, or nil if not found."
+  "Return the position of CONTEXT in the current buffer.
+If CONTEXT cannot be found, return nil."
   (let ((context-string (nth 2 context)))
     (if (equal "" context-string)
 	(point-max)
@@ -1018,8 +1020,8 @@
            (if new-mark (set-mark new-mark))))))
 
 (defun vc-revert-buffer1 (&optional arg no-confirm)
-  "Revert buffer, trying to keep point and mark where user expects them.
-Tries to be clever in the face of changes due to expanded version control
+  "Revert buffer, keeping point and mark where user expects them.
+Try to be clever in the face of changes due to expanded version control
 key words.  This is important for typeahead to work as expected.
 ARG and NO-CONFIRM are passed on to `revert-buffer'."
   (interactive "P")
@@ -1047,7 +1049,7 @@
 	  (error "Aborted")))))
 
 (defun vc-workfile-unchanged-p (file)
-  "Has FILE changed since last checkout?"
+  "Return non-nil if FILE has not changed since the last checkout."
   (let ((checkout-time (vc-file-getprop file 'vc-checkout-time))
         (lastmod (nth 5 (file-attributes file))))
     (if checkout-time
@@ -1057,12 +1059,14 @@
         unchanged))))
 
 (defun vc-default-workfile-unchanged-p (backend file)
-  "Default check whether FILE is unchanged: diff against master version."
+  "Check if FILE is unchanged by diffing against the master version.
+Return non-nil if FILE is unchanged."
   (zerop (vc-call diff file (vc-workfile-version file))))
 
 (defun vc-default-latest-on-branch-p (backend file)
-  "Default check whether the current workfile version of FILE is the
-latest on its branch."
+  "Return non-nil if FILE is the latest on its branch.
+This default implementation always returns non-nil, which means that
+editing non-current versions is not supported by default."
   t)
 
 (defun vc-recompute-state (file)
@@ -1072,7 +1076,7 @@
   (vc-file-setprop file 'vc-state (vc-call state file)))
 
 (defun vc-next-action-on-file (file verbose &optional comment)
-  "Do The Right Thing for a given version-controlled FILE.
+  "Do The Right Thing for a given FILE under version control.
 If COMMENT is specified, it will be used as an admin or checkin comment.
 If VERBOSE is non-nil, query the user rather than using default parameters."
   (let ((visited (get-file-buffer file))
@@ -1229,7 +1233,7 @@
 
 ;;;###autoload
 (defun vc-next-action (verbose)
-  "Do the next logical checkin or checkout operation on the current file.
+  "Do the next logical version control operation on the current file.
 
 If you call this from within a VC dired buffer with no files marked,
 it will operate on the file in the current line.
@@ -1557,12 +1561,13 @@
    'vc-checkin-hook))
 
 (defun vc-comment-to-change-log (&optional whoami file-name)
-  "Enter last VC comment into change log file for current buffer's file.
-Optional arg (interactive prefix) non-nil means prompt for user name and site.
-Second arg is file name of change log.  \
-If nil, uses `change-log-default-name'.
+  "Enter last VC comment into the change log for the current file.
+WHOAMI (interactive prefix) non-nil means prompt for user name
+and site.  FILE-NAME is the name of the change log; if nil, use
+`change-log-default-name'.
 
-May be useful as a `vc-checkin-hook' to update change logs automatically."
+This may be useful as a `vc-checkin-hook' to update change logs
+automatically."
   (interactive (if current-prefix-arg
 		   (list current-prefix-arg
 			 (prompt-for-change-log-name))))
@@ -1604,7 +1609,11 @@
 	(insert "\n"))))
 
 (defun vc-finish-logentry (&optional nocomment)
-  "Complete the operation implied by the current log entry."
+  "Complete the operation implied by the current log entry.
+Use the contents of the current buffer as a check-in or registration
+comment.  If the optional arg NOCOMMENT is non-nil, then don't check
+the buffer contents as a comment, and don't add it to
+`vc-comment-ring'."
   (interactive)
   ;; Check and record the comment, if any.
   (unless nocomment
@@ -1658,6 +1667,8 @@
 ;; Code for access to the comment ring
 
 (defun vc-new-comment-index (stride len)
+  "Return the comment index STRIDE elements from the current one.
+LEN is the length of `vc-comment-ring'."
   (mod (cond
 	(vc-comment-ring-index (+ vc-comment-ring-index stride))
 	;; Initialize the index on the first use of this command
@@ -1668,7 +1679,8 @@
        len))
 
 (defun vc-previous-comment (arg)
-  "Cycle backwards through comment history."
+  "Cycle backwards through comment history.
+With a numeric prefix ARG, go back ARG comments."
   (interactive "*p")
   (let ((len (ring-length vc-comment-ring)))
     (if (<= len 0)
@@ -1679,12 +1691,15 @@
       (insert (ring-ref vc-comment-ring vc-comment-ring-index)))))
 
 (defun vc-next-comment (arg)
-  "Cycle forwards through comment history."
+  "Cycle forwards through comment history.
+With a numeric prefix ARG, go forward ARG comments."
   (interactive "*p")
   (vc-previous-comment (- arg)))
 
 (defun vc-comment-search-reverse (str &optional stride)
-  "Search backwards through comment history for substring match."
+  "Search backwards through comment history for substring match of STR.
+If the optional argument STRIDE is present, that is a step-width to use
+when going through the comment ring."
   ;; Why substring rather than regexp ?   -sm
   (interactive
    (list (read-string "Comment substring: " nil nil vc-last-comment-match)))
@@ -1702,7 +1717,7 @@
     (vc-previous-comment 0)))
 
 (defun vc-comment-search-forward (str)
-  "Search forwards through comment history for substring match."
+  "Search forwards through comment history for a substring match of STR."
   (interactive
    (list (read-string "Comment substring: " nil nil vc-last-comment-match)))
   (vc-comment-search-reverse str -1))
@@ -1712,10 +1727,12 @@
 ;;;###autoload
 (defun vc-diff (historic &optional not-urgent)
   "Display diffs between file versions.
-Normally this compares the current file and buffer with the most recent
-checked in version of that file.  This uses no arguments.
-With a prefix argument, it reads the file name to use
-and two version designators specifying which versions to compare."
+Normally this compares the current file and buffer with the most
+recent checked in version of that file.  This uses no arguments.  With
+a prefix argument HISTORIC, it reads the file name to use and two
+version designators specifying which versions to compare.  The
+optional argument NOT-URGENT non-nil means it is ok to say no to
+saving the buffer."
   (interactive (list current-prefix-arg t))
   (if historic
       (call-interactively 'vc-version-diff)
@@ -1727,9 +1744,11 @@
 	(vc-version-diff file nil nil)))))
 
 (defun vc-version-diff (file rel1 rel2)
-  "For FILE, report diffs between two stored versions REL1 and REL2 of it.
-If FILE is a directory, generate diffs between versions for all registered
-files in or below it."
+  "List the differences between FILE's versions REL1 and REL2.
+If REL1 is empty or nil it means to use the current workfile version;
+REL2 empty or nil means the current file contents.  FILE may also be
+a directory, in that case, generate diffs between the correponding
+versions of all registered files in or below it."
   (interactive
    (let ((file (expand-file-name
                 (read-file-name (if buffer-file-name
@@ -1832,8 +1851,7 @@
       (vc-call diff file rel1 rel2))))
 
 (defmacro vc-diff-switches-list (backend)
-  "Make a list of `diff-switches', `vc-diff-switches',
-and `vc-BACKEND-diff-switches'."
+  "Return the list of switches to use for executing diff under BACKEND."
   `(append
     (if (listp diff-switches) diff-switches (list diff-switches))
     (if (listp vc-diff-switches) vc-diff-switches (list vc-diff-switches))
@@ -1843,7 +1861,7 @@
       (if (listp backend-switches) backend-switches (list backend-switches)))))
 
 (defun vc-default-diff-tree (backend dir rel1 rel2)
-  "Default implementation for diffing an entire tree at and below DIR.
+  "List differences for all registered files at and below DIR.
 The meaning of REL1 and REL2 is the same as for `vc-version-diff'."
   ;; This implementation does an explicit tree walk, and calls
   ;; vc-BACKEND-diff directly for each file.  An optimization
@@ -1877,9 +1895,9 @@
 
 ;;;###autoload
 (defun vc-version-other-window (rev)
-  "Visit version REV of the current buffer in another window.
-If the current buffer is named `F', the version is named `F.~REV~'.
-If `F.~REV~' already exists, it is used instead of being re-created."
+  "Visit version REV of the current file in another window.
+If the current file is named `F', the version is named `F.~REV~'.
+If `F.~REV~' already exists, use it instead of checking it out again."
   (interactive "sVersion to visit (default is workfile version): ")
   (vc-ensure-vc-buffer)
   (let* ((file buffer-file-name)
@@ -1898,7 +1916,7 @@
 
 ;;;###autoload
 (defun vc-insert-headers ()
-  "Insert headers in a file for use with your version control system.
+  "Insert headers into a file for use with a version control system.
 Headers desired are inserted at point, and are pulled from
 the variable `vc-BACKEND-header'."
   (interactive)
@@ -1929,7 +1947,7 @@
 
 (defun vc-clear-headers (&optional file)
   "Clear all version headers in the current buffer (or FILE).
-I.e. reset them to the non-expanded form."
+The headers are reset to their non-expanded form."
   (let* ((filename (or file buffer-file-name))
 	 (visited (find-buffer-visiting filename))
 	 (backend (vc-backend filename)))
@@ -2343,7 +2361,7 @@
 ;; Named-configuration entry points
 
 (defun vc-snapshot-precondition (dir)
-  "Scan the tree below DIR, looking for non-uptodate files.
+  "Scan the tree below DIR, looking for files not up-to-date.
 If any file is not up-to-date, return the name of the first such file.
 \(This means, neither snapshot creation nor retrieval is allowed.\)
 If one or more of the files are currently visited, return `visited'.
@@ -2457,7 +2475,7 @@
         (set-buffer-modified-p nil)))))
 
 (defun vc-default-comment-history (backend file)
-  "Return a string with all log entries that were made under BACKEND for FILE."
+  "Return a string with all log entries stored in BACKEND for FILE."
   (if (vc-find-backend-function backend 'print-log)
       (with-temp-buffer
 	(vc-call print-log file)
@@ -2486,7 +2504,7 @@
 
 ;;;###autoload
 (defun vc-revert-buffer ()
-  "Revert the current buffer's file back to the version it was based on.
+  "Revert the current buffer's file to the version it was based on.
 This asks for confirmation if the buffer contents are not identical
 to that version.  This function does not automatically pick up newer
 changes found in the master file; use \\[universal-argument] \\[vc-next-action] to do so."
@@ -2713,7 +2731,7 @@
 	   templates)))
     (if (or (file-symlink-p oldmaster)
 	    (file-symlink-p (file-name-directory oldmaster)))
-	(error "This unsafe in the presence of symbolic links"))
+	(error "This is unsafe in the presence of symbolic links"))
     (rename-file
      oldmaster
      (catch 'found
@@ -2872,7 +2890,7 @@
   (cdr (assoc buffer vc-annotate-buffers)))
 
 (define-derived-mode vc-annotate-mode fundamental-mode "Annotate"
-  "Major mode for buffers displaying output from the `annotate' command.
+  "Major mode for output buffers of the `vc-annotate' command.
 
 You can use the mode-specific menu to alter the time-span of the used
 colors.  See variable `vc-annotate-menu-elements' for customizing the
@@ -2880,8 +2898,9 @@
   (vc-annotate-add-menu))
 
 (defun vc-annotate-display-default (&optional ratio)
-  "Use the default color spectrum for VC Annotate mode, scaling the
-colormap by RATIO, if present.  Use the current time as offset."
+  "Display the output of \\[vc-annotate] using the default color range.
+The color range is given by `vc-annotate-color-map', scaled by RATIO
+if present.  The current time is used as the offset."
   (interactive "e")
   (message "Redisplaying annotation...")
   (vc-annotate-display
@@ -2889,9 +2908,10 @@
   (message "Redisplaying annotation...done"))
 
 (defun vc-annotate-display-autoscale (&optional full)
-  "Re-display annotation using colormap scaled from the current time
-to the oldest annotation in the buffer, or, with argument FULL set, to
-cover the full time range, from oldest to newest."
+  "Highlight the output of \\[vc-annotate]] using an autoscaled color map.
+Autoscaling means that the map is scaled from the current time to the
+oldest annotation in the buffer, or, with argument FULL non-nil, to
+cover the range from the oldest annotation to the newest."
   (interactive)
   (let ((newest 0.0)
 	(oldest 999999.)		;Any CVS users at the founding of Rome?
@@ -2970,9 +2990,11 @@
 			  "VC Annotate Display Menu" menu-def))))
 
 (defun vc-annotate-display-select (&optional buffer mode)
-  "Do the default or chosen annotation display as specified in the
-customizable variable `vc-annotate-display-mode'."
-		   (interactive)
+  "Highlight the output of \\[vc-annotate].
+By default, the current buffer is highlighted, unless overridden by
+BUFFER.  `vc-annotate-display-mode' specifies the highlighting mode to
+use; you may override this using the second optional arg MODE."
+  (interactive)
   (if mode (setq vc-annotate-display-mode mode))
   (when buffer
     (set-buffer buffer)
@@ -3063,7 +3085,7 @@
     (car (car a-list))))
 
 (defun vc-annotate-time-span (a-list span &optional quantize)
-  "Apply factor SPAN  to the time-span of association list A-LIST.
+  "Apply factor SPAN to the time-span of association list A-LIST.
 Return the new alist.
 Optionally quantize to the factor of QUANTIZE."
   ;; Apply span to each car of every cons
@@ -3075,9 +3097,9 @@
 					     a-list) span quantize))))
 
 (defun vc-annotate-compcar (threshold a-list)
-  "Test successive cons cells of association list A-LIST against THRESHOLD.
-Return the first cons cell which car is not less than THRESHOLD,
-nil otherwise"
+  "Test successive cons cells of A-LIST against THRESHOLD.
+Return the first cons cell with a car that is not less than THRESHOLD,
+nil if no such cell exists."
  (let ((i 1)
        (tmp-cons (car a-list)))
    (while (and tmp-cons (< (car tmp-cons) threshold))
@@ -3086,17 +3108,16 @@
    tmp-cons))				; Return the appropriate value
 
 (defun vc-annotate-convert-time (time)
-  "Convert high/low times, as returned by `current-time' and
-`encode-time', to a single floating point value in units of days.
-TIME is list, only the first two elements of TIME are considered,
-comprising the high 16 and low 16 bits of the number of seconds since
-Jan 1, 1970."
+  "Convert a time value to a floating-point number of days.
+The argument TIME is a list as returned by `current-time' or
+`encode-time', only the first two elements of that list are considered."
   (/ (+ (* (float (car time)) (lsh 1 16)) (cadr time)) 24 3600))
 
 (defun vc-annotate-difference (&optional offset)
-   "Calculate the difference, in days, from the current time and the
-time returned from the backend function annotate-time.  If OFFSET is
-set, use it as the time base instead of the current time."
+  "Return the time span in days to the next annotation.
+This calls the backend function annotate-time, and returns the
+difference in days between the time returned and the current time,
+or OFFSET if present."
    (let ((next-time (vc-call-backend vc-annotate-backend 'annotate-time)))
      (if next-time
 	 (- (or offset
@@ -3108,10 +3129,13 @@
   (vc-annotate-convert-time (current-time)))
 
 (defun vc-annotate-display (&optional color-map offset)
-  "Do the VC-Annotate display in BUFFER using COLOR-MAP, and time
-offset OFFSET (defaults to the present time).  You probably want
-`vc-annotate-select' instead, after setting
-`vc-annotate-display-mode'"
+  "Highlight `vc-annotate' output in the current buffer.
+COLOR-MAP, if present, overrides `vc-annotate-color-map'.  The
+annotations are relative to the current time, unless overridden by
+OFFSET.
+
+This function is obsolete, and has been replaced by
+`vc-annotate-select'."
   (save-excursion
   (goto-char (point-min))		; Position at the top of the buffer.
   ;; Delete old overlays