[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master b2164df 1/4: ; More stylistic docfixes in vc/*.el found by checkd
|
From: |
Stefan Kangas |
|
Subject: |
master b2164df 1/4: ; More stylistic docfixes in vc/*.el found by checkdoc |
|
Date: |
Sat, 18 Sep 2021 03:41:23 -0400 (EDT) |
branch: master
commit b2164df86ba80cf4b7f3499596fbcf803395b6e7
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>
; More stylistic docfixes in vc/*.el found by checkdoc
---
lisp/vc/compare-w.el | 2 +-
lisp/vc/diff.el | 10 +--
lisp/vc/ediff-diff.el | 32 +++++-----
lisp/vc/ediff-help.el | 5 +-
lisp/vc/ediff-init.el | 164 +++++++++++++++++++++++++------------------------
lisp/vc/ediff-mult.el | 37 ++++++-----
lisp/vc/ediff-ptch.el | 25 ++++----
lisp/vc/ediff-util.el | 58 +++++++++--------
lisp/vc/ediff-wind.el | 58 +++++++++--------
lisp/vc/ediff.el | 15 +++--
lisp/vc/emerge.el | 124 ++++++++++++++++++++-----------------
lisp/vc/log-view.el | 2 +-
lisp/vc/pcvs.el | 12 ++--
lisp/vc/smerge-mode.el | 2 +-
lisp/vc/vc-dir.el | 12 ++--
lisp/vc/vc-git.el | 7 +--
lisp/vc/vc-hg.el | 13 ++--
17 files changed, 302 insertions(+), 276 deletions(-)
diff --git a/lisp/vc/compare-w.el b/lisp/vc/compare-w.el
index 7c2e125..29dfaa7 100644
--- a/lisp/vc/compare-w.el
+++ b/lisp/vc/compare-w.el
@@ -188,7 +188,7 @@ If both windows display the same buffer,
the mark is pushed twice in that buffer:
first in the other window, then in the selected window.
-A prefix arg means reverse the value of variable
+A prefix arg IGNORE-WHITESPACE, means reverse the value of variable
`compare-ignore-whitespace'. If `compare-ignore-whitespace' is
nil, then a prefix arg means ignore changes in whitespace. If
`compare-ignore-whitespace' is non-nil, then a prefix arg means
diff --git a/lisp/vc/diff.el b/lisp/vc/diff.el
index 7bb1151..352fa69 100644
--- a/lisp/vc/diff.el
+++ b/lisp/vc/diff.el
@@ -87,10 +87,10 @@ minibuffer. The default for NEW is the current buffer's
file
name, and the default for OLD is a backup file for NEW, if one
exists. If NO-ASYNC is non-nil, call diff synchronously.
-When called interactively with a prefix argument, prompt
+When called interactively with a prefix argument SWITCHES, prompt
interactively for diff switches. Otherwise, the switches
-specified in the variable `diff-switches' are passed to the
-diff command.
+specified in the variable `diff-switches' are passed to the diff
+command.
Non-interactively, OLD and NEW may each be a file or a buffer."
(interactive
@@ -229,7 +229,7 @@ returns the buffer used."
Uses the latest backup, if there are several numerical backups.
If this file is a backup, diff it with its original.
The backup file is the first file given to `diff'.
-With prefix arg, prompt for diff switches."
+With prefix arg SWITCHES, prompt for diff switches."
(interactive (list (read-file-name "Diff (file with backup): ")
(diff-switches)))
(let (bak ori)
@@ -243,7 +243,7 @@ With prefix arg, prompt for diff switches."
;;;###autoload
(defun diff-latest-backup-file (fn)
- "Return the latest existing backup of FILE, or nil."
+ "Return the latest existing backup of file FN, or nil."
(let ((handler (find-file-name-handler fn 'diff-latest-backup-file)))
(if handler
(funcall handler 'diff-latest-backup-file fn)
diff --git a/lisp/vc/ediff-diff.el b/lisp/vc/ediff-diff.el
index 0f90bef..68abea7 100644
--- a/lisp/vc/ediff-diff.el
+++ b/lisp/vc/ediff-diff.el
@@ -103,8 +103,8 @@ Use `setq-default' if setting it in .emacs")
GNU diff3 doesn't have such an option."
:type 'string)
-;; the actual options used in comparison
-(ediff-defvar-local ediff-actual-diff-options ediff-diff-options "")
+(ediff-defvar-local ediff-actual-diff-options ediff-diff-options
+ "The actual options used in comparison.")
(defcustom ediff-custom-diff-program ediff-diff-program
"Program to use for generating custom diff output for saving it in a file.
@@ -123,8 +123,8 @@ This output is not used by Ediff internally."
:set 'ediff-set-diff-options
:type 'string)
-;; the actual options used in comparison
-(ediff-defvar-local ediff-actual-diff3-options ediff-diff3-options "")
+(ediff-defvar-local ediff-actual-diff3-options ediff-diff3-options
+ "The actual options used in comparison.")
(defcustom ediff-diff3-ok-lines-regexp
"^\\([1-3]:\\|====\\| \\|.*Warning *:\\|.*No newline\\|.*missing
newline\\|^\C-m$\\)"
@@ -132,16 +132,16 @@ This output is not used by Ediff internally."
Lines that do not match are assumed to be error messages."
:type 'regexp)
-;; keeps the status of the current diff in 3-way jobs.
-;; the status can be =diff(A), =diff(B), or =diff(A+B)
-(ediff-defvar-local ediff-diff-status "" "")
+(ediff-defvar-local ediff-diff-status ""
+ "Keeps the status of the current diff in 3-way jobs.
+The status can be =diff(A), =diff(B), or =diff(A+B).")
;;; Fine differences
(ediff-defvar-local ediff-auto-refine (if (ediff-has-face-support-p) 'on 'nix)
"If `on', Ediff auto-highlights fine diffs for the current diff region.
-If `off', auto-highlighting is not used. If `nix', no fine diffs are shown
+If `off', auto-highlighting is not used. If `nix', no fine diffs are shown
at all, unless the user force-refines the region by hitting `*'.
This variable can be set either in .emacs or toggled interactively.
@@ -179,12 +179,12 @@ Lines that do not match are assumed to be error
messages.")
"Pattern to match lines produced by diff that describe differences.")
(ediff-defvar-local ediff-setup-diff-regions-function nil
- "value is a function symbol depending on the kind of job is to be done.
-For 2-way jobs and for ediff-merge, it should be `ediff-setup-diff-regions'.
+ "Value is a function symbol depending on the kind of job is to be done.
+For 2-way jobs and for `ediff-merge', it should be `ediff-setup-diff-regions'.
For jobs requiring diff3, it should be `ediff-setup-diff-regions3'.
The function should take three mandatory arguments, file-A, file-B, and
-file-C. It may ignore file C for diff2 jobs. It should also take
+file-C. It may ignore file C for diff2 jobs. It should also take
one optional arguments, diff-number to refine.")
@@ -823,13 +823,10 @@ one optional arguments, diff-number to refine.")
(setq overlay-list (cons overlay overlay-list))
(if (> (length diff-list) 1)
(setq diff-list (cdr (cdr diff-list)))
- (error "ediff-set-fine-overlays-for-combined-merge: corrupt list of
-delimiter regions"))
- )
+ (error "Corrupt list of delimiter regions")))
(setq overlay-list (reverse overlay-list))
(ediff-set-fine-diff-vector
- reg-num 'C (apply #'vector overlay-list))
- ))
+ reg-num 'C (apply #'vector overlay-list))))
;; Convert diff list to overlays for a given DIFF-REGION
@@ -1461,8 +1458,7 @@ affects only files whose names match the expression."
(message "Ignoring letter case is not supported by this diff program"))
(t
(sit-for 1)
- (ediff-update-diffs)))
- )
+ (ediff-update-diffs))))
(provide 'ediff-diff)
;;; ediff-diff.el ends here
diff --git a/lisp/vc/ediff-help.el b/lisp/vc/ediff-help.el
index 2f8f596..0450cd7 100644
--- a/lisp/vc/ediff-help.el
+++ b/lisp/vc/ediff-help.el
@@ -126,9 +126,9 @@ Normally, not a user option. See `ediff-help-message' for
details.")
(defconst ediff-brief-message-string
" Type ? for help"
"Contents of the brief help message.")
-;; The actual brief help message
(ediff-defvar-local ediff-brief-help-message ""
- "Normally, not a user option. See `ediff-help-message' for details.")
+ "The actual brief help message.
+Normally, not a user option. See `ediff-help-message' for details.")
(ediff-defvar-local ediff-brief-help-message-function nil
"The brief help message that the user can customize.
@@ -143,7 +143,6 @@ See `ediff-brief-help-message-function' for more.")
:type 'boolean
:group 'ediff-window)
-;; The actual help message.
(ediff-defvar-local ediff-help-message ""
"The actual help message.
Normally, the user shouldn't touch this. However, if you want Ediff to
diff --git a/lisp/vc/ediff-init.el b/lisp/vc/ediff-init.el
index 1d87b08..3ee27cd 100644
--- a/lisp/vc/ediff-init.el
+++ b/lisp/vc/ediff-init.el
@@ -81,39 +81,44 @@ that Ediff doesn't know about.")
;; commands) won't destroy Ediff control variables.
;;
;; Plagiarized from `emerge-defvar-local'.
-(defmacro ediff-defvar-local (var value doc)
- "Defines VAR as a local variable."
+(defmacro ediff-defvar-local (symbol value doc)
+ "Define SYMBOL as an advertised buffer-local variable.
+Run `defvar-local', setting the value of the variable to VALUE
+and its docstring to DOC.
+
+Then set the `permanent-local' property, so that
+`kill-all-local-variables' (called by major-mode setting
+commands) won't destroy Ediff control variables."
(declare (indent defun) (doc-string 3))
`(progn
- (defvar-local ,var ,value ,doc)
- (put ',var 'permanent-local t)))
+ (defvar-local ,symbol ,value ,doc)
+ (put ',symbol 'permanent-local t)))
;; Variables that control each Ediff session---local to the control buffer.
;; Mode variables
-;; The buffer in which the A variant is stored.
-(ediff-defvar-local ediff-buffer-A nil "")
-;; The buffer in which the B variant is stored.
-(ediff-defvar-local ediff-buffer-B nil "")
-;; The buffer in which the C variant is stored or where the merge buffer lives.
-(ediff-defvar-local ediff-buffer-C nil "")
-;; Ancestor buffer
-(ediff-defvar-local ediff-ancestor-buffer nil "")
-;; The Ediff control buffer
-(ediff-defvar-local ediff-control-buffer nil "")
+(ediff-defvar-local ediff-buffer-A nil
+ "The buffer in which the A variant is stored.")
+(ediff-defvar-local ediff-buffer-B nil
+ "The buffer in which the B variant is stored.")
+(ediff-defvar-local ediff-buffer-C nil
+ "The buffer in which the C variant is stored or where the merge buffer
lives.")
+(ediff-defvar-local ediff-ancestor-buffer nil
+ "Ancestor buffer.")
+(ediff-defvar-local ediff-control-buffer nil
+ "The Ediff control buffer.")
(ediff-defvar-local ediff-temp-indirect-buffer nil
"If t, the buffer is a temporary indirect buffer.
It needs to be killed when we quit the session.")
-
-;; Association between buff-type and ediff-buffer-*
(defconst ediff-buffer-alist
'((?A . ediff-buffer-A)
(?B . ediff-buffer-B)
- (?C . ediff-buffer-C)))
+ (?C . ediff-buffer-C))
+ "Association between `buff-type' and `ediff-buffer-*'.")
;;; Macros
(defsubst ediff-buffer-live-p (buf)
@@ -515,22 +520,22 @@ See the documentation string of
`ediff-hide-regexp-matches' for details.")
"Function to use in determining which regions to focus on.
See the documentation string of `ediff-focus-on-regexp-matches' for details.")
-;; Regexp that determines buf A regions to focus on when skipping to diff
-(ediff-defvar-local ediff-regexp-focus-A "" "")
-;; Regexp that determines buf B regions to focus on when skipping to diff
-(ediff-defvar-local ediff-regexp-focus-B "" "")
-;; Regexp that determines buf C regions to focus on when skipping to diff
-(ediff-defvar-local ediff-regexp-focus-C "" "")
+(ediff-defvar-local ediff-regexp-focus-A ""
+ "Regexp that determines buf A regions to focus on when skipping to diff.")
+(ediff-defvar-local ediff-regexp-focus-B ""
+ "Regexp that determines buf B regions to focus on when skipping to diff.")
+(ediff-defvar-local ediff-regexp-focus-C ""
+ "Regexp that determines buf C regions to focus on when skipping to diff.")
;; connective that determines whether to focus regions that match both or
;; one of the regexps
(ediff-defvar-local ediff-focus-regexp-connective 'and "")
-;; Regexp that determines buf A regions to ignore when skipping to diff
-(ediff-defvar-local ediff-regexp-hide-A "" "")
-;; Regexp that determines buf B regions to ignore when skipping to diff
-(ediff-defvar-local ediff-regexp-hide-B "" "")
-;; Regexp that determines buf C regions to ignore when skipping to diff
-(ediff-defvar-local ediff-regexp-hide-C "" "")
+(ediff-defvar-local ediff-regexp-hide-A ""
+ "Regexp that determines buf A regions to ignore when skipping to diff.")
+(ediff-defvar-local ediff-regexp-hide-B ""
+ "Regexp that determines buf B regions to ignore when skipping to diff.")
+(ediff-defvar-local ediff-regexp-hide-C ""
+ "Regexp that determines buf C regions to ignore when skipping to diff.")
;; connective that determines whether to hide regions that match both or
;; one of the regexps
(ediff-defvar-local ediff-hide-regexp-connective 'and "")
@@ -631,28 +636,28 @@ shown in brighter colors."
(put 'ediff-highlight-all-diffs 'permanent-local t)
-;; The suffix of the control buffer name.
-(ediff-defvar-local ediff-control-buffer-suffix nil "")
-;; Same as ediff-control-buffer-suffix, but without <,>.
-;; It's a number rather than string.
-(ediff-defvar-local ediff-control-buffer-number nil "")
+(ediff-defvar-local ediff-control-buffer-suffix nil
+ "The suffix of the control buffer name.")
+(ediff-defvar-local ediff-control-buffer-number nil
+ "Same as `ediff-control-buffer-suffix', but without \"<,>\".
+It's a number rather than string.")
-;; The original values of ediff-protected-variables for buffer A
-(ediff-defvar-local ediff-buffer-values-orig-A nil "")
-;; The original values of ediff-protected-variables for buffer B
-(ediff-defvar-local ediff-buffer-values-orig-B nil "")
-;; The original values of ediff-protected-variables for buffer C
-(ediff-defvar-local ediff-buffer-values-orig-C nil "")
-;; The original values of ediff-protected-variables for buffer Ancestor
-(ediff-defvar-local ediff-buffer-values-orig-Ancestor nil "")
+(ediff-defvar-local ediff-buffer-values-orig-A nil
+ "The original values of ediff-protected-variables for buffer A.")
+(ediff-defvar-local ediff-buffer-values-orig-B nil
+ "The original values of ediff-protected-variables for buffer B.")
+(ediff-defvar-local ediff-buffer-values-orig-C nil
+ "The original values of ediff-protected-variables for buffer C.")
+(ediff-defvar-local ediff-buffer-values-orig-Ancestor nil
+ "The original values of ediff-protected-variables for buffer Ancestor.")
-;; association between buff-type and ediff-buffer-values-orig-*
(defconst ediff-buffer-values-orig-alist
'((A . ediff-buffer-values-orig-A)
(B . ediff-buffer-values-orig-B)
(C . ediff-buffer-values-orig-C)
- (Ancestor . ediff-buffer-values-orig-Ancestor)))
+ (Ancestor . ediff-buffer-values-orig-Ancestor))
+ "Association between buff-type and `ediff-buffer-values-orig-*'.")
;; Buffer-local variables to be saved then restored during Ediff sessions
(defconst ediff-protected-variables '(
@@ -665,37 +670,37 @@ shown in brighter colors."
;; indicates the way a diff region was created in buffer C.
;; state-of-ancestor says if the corresponding region in ancestor buffer is
;; empty.
-(ediff-defvar-local ediff-state-of-merge nil "")
-
-;; The difference that is currently selected.
-(ediff-defvar-local ediff-current-difference -1 "")
-;; Number of differences found.
-(ediff-defvar-local ediff-number-of-differences nil "")
-
-;; Buffer containing the output of diff, which is used by Ediff to step
-;; through files.
-(ediff-defvar-local ediff-diff-buffer nil "")
-;; Like ediff-diff-buffer, but contains context diff. It is not used by
-;; Ediff, but it is saved in a file, if user requests so.
-(ediff-defvar-local ediff-custom-diff-buffer nil "")
-;; Buffer used for diff-style fine differences between regions.
-(ediff-defvar-local ediff-fine-diff-buffer nil "")
+(ediff-defvar-local ediff-state-of-merge nil)
+
+(ediff-defvar-local ediff-current-difference -1
+ "The difference that is currently selected.")
+(ediff-defvar-local ediff-number-of-differences nil
+ "Number of differences found.")
+
+(ediff-defvar-local ediff-diff-buffer nil
+ "Buffer containing the output of diff, which is used to step through files.")
+(ediff-defvar-local ediff-custom-diff-buffer nil
+ "Like `ediff-diff-buffer', but contains context diff.
+It is not used by Ediff, but it is saved in a file, if user
+requests so.")
+(ediff-defvar-local ediff-fine-diff-buffer nil
+ "Buffer used for diff-style fine differences between regions.")
(defconst ediff-tmp-buffer " *ediff-tmp*"
"Temporary buffer used for computing fine differences.")
(defconst ediff-msg-buffer " *ediff-message*"
"Buffer used for messages.")
-;; Buffer containing the output of diff when diff returns errors.
-(ediff-defvar-local ediff-error-buffer nil "")
-;; Buffer to display debug info
-(ediff-defvar-local ediff-debug-buffer "*ediff-debug*" "")
+(ediff-defvar-local ediff-error-buffer nil
+ "Buffer containing the output of diff when diff returns errors.")
+(ediff-defvar-local ediff-debug-buffer "*ediff-debug*"
+ "Buffer to display debug info.")
-;; List of ediff control panels associated with each buffer A/B/C/Ancestor.
-;; Not used any more, but may be needed in the future.
-(ediff-defvar-local ediff-this-buffer-ediff-sessions nil "")
+(ediff-defvar-local ediff-this-buffer-ediff-sessions nil
+ "List of ediff control panels associated with each buffer A/B/C/Ancestor.
+Not used any more, but may be needed in the future.")
;; to be deleted in due time
;; List of difference overlays disturbed by working with the current diff.
-(defvar ediff-disturbed-overlays nil "")
+(defvar ediff-disturbed-overlays nil)
(defcustom ediff-version-control-package 'vc
"Version control package used.
@@ -707,7 +712,7 @@ appropriate symbol: `rcs', `pcl-cvs', or `generic-sc' if
you so desire."
:group 'ediff)
(defcustom ediff-coding-system-for-read 'raw-text
- "The coding system for read to use when running the diff program as a
subprocess.
+ "Coding system for read to use when running the diff program as a subprocess.
In most cases, the default will do. However, under certain circumstances in
MS-Windows you might need to use something like `raw-text-dos' here.
So, if the output that your diff program sends to Emacs contains extra ^M's,
@@ -717,8 +722,9 @@ work."
:group 'ediff)
(defcustom ediff-coding-system-for-write 'emacs-internal
- "The coding system for write to use when writing out difference regions
-to temp files in buffer jobs and when Ediff needs to find fine differences."
+ "Coding system for write to use when writing out difference regions.
+This is used when writing to temp files in buffer jobs and when
+Ediff needs to find fine differences."
:type 'symbol
:group 'ediff)
@@ -789,7 +795,7 @@ to temp files in buffer jobs and when Ediff needs to find
fine differences."
(defun ediff-set-face-pixmap (face pixmap)
- "Set face pixmap on a monochrome display."
+ "Set stipple pixmap of FACE to PIXMAP on a monochrome display."
(if (and (ediff-window-display-p) (not (display-color-p)))
(condition-case nil
(set-face-background-pixmap face pixmap)
@@ -1232,8 +1238,8 @@ or `ediff-merge-directory-revisions'."
:group 'ediff-merge)
(make-variable-buffer-local 'ediff-autostore-merges)
-;; file where the result of the merge is to be saved. used internally
-(ediff-defvar-local ediff-merge-store-file nil "")
+(ediff-defvar-local ediff-merge-store-file nil
+ "File where the result of the merge is to be saved. Internal.")
(defcustom ediff-merge-filename-prefix "merge_"
"Prefix to be attached to saved merge buffers."
@@ -1266,12 +1272,12 @@ This default should work without changes."
(make-obsolete-variable 'ediff-H-glyph nil "28.1")
-;; Temporary file used for refining difference regions in buffer A.
-(ediff-defvar-local ediff-temp-file-A nil "")
-;; Temporary file used for refining difference regions in buffer B.
-(ediff-defvar-local ediff-temp-file-B nil "")
-;; Temporary file used for refining difference regions in buffer C.
-(ediff-defvar-local ediff-temp-file-C nil "")
+(ediff-defvar-local ediff-temp-file-A nil
+ "Temporary file used for refining difference regions in buffer A.")
+(ediff-defvar-local ediff-temp-file-B nil
+ "Temporary file used for refining difference regions in buffer B.")
+(ediff-defvar-local ediff-temp-file-C nil
+ "Temporary file used for refining difference regions in buffer C.")
(defun ediff-file-remote-p (file-name)
diff --git a/lisp/vc/ediff-mult.el b/lisp/vc/ediff-mult.el
index cfb5834..a26db3c 100644
--- a/lisp/vc/ediff-mult.el
+++ b/lisp/vc/ediff-mult.el
@@ -232,8 +232,8 @@ on `ediff-quit', `ediff-suspend', or
`ediff-quit-session-group-hook'."
(make-obsolete-variable 'ediff-before-session-group-setup-hooks nil "27.1")
(defcustom ediff-after-session-group-setup-hook nil
- "Hooks run just after a meta-buffer controlling a session group, such as
-ediff-directories, is run."
+ "Hooks run just after a meta-buffer controlling a session group is run.
+One example of this is `ediff-directories'."
:type 'hook)
(defcustom ediff-quit-session-group-hook nil
"Hooks run just before exiting a session group."
@@ -251,8 +251,8 @@ This means that you can set different bindings for
different kinds of meta
buffers."
:type 'hook)
-;; Buffer holding the multi-file patch. Local to the meta buffer
-(ediff-defvar-local ediff-meta-patchbufer nil "")
+(ediff-defvar-local ediff-meta-patchbufer nil
+ "Buffer holding the multi-file patch. Local to the meta buffer.")
;;; API for ediff-meta-list
@@ -366,8 +366,8 @@ buffers."
(ediff-defvar-local ediff-verbose-help-enabled nil
- "If t, display redundant help in ediff-directories and other meta buffers.
-Toggled by ediff-toggle-verbose-help-meta-buffer" )
+ "If t, display redundant help in `ediff-directories' and other meta buffers.
+Toggled by `ediff-toggle-verbose-help-meta-buffer'.")
;; Toggle verbose help in meta-buffers
;; TODO: Someone who understands all this can make it better.
@@ -459,7 +459,9 @@ Commands:
(defun ediff-next-meta-item (count)
"Move to the next item in Ediff registry or session group buffer.
-Moves in circular fashion. With numeric prefix arg, skip this many items."
+Moves in circular fashion.
+
+With numeric prefix arg COUNT, skip this many items."
(interactive "p")
(or count (setq count 1))
(let (overl)
@@ -487,7 +489,9 @@ Moves in circular fashion. With numeric prefix arg, skip
this many items."
(defun ediff-previous-meta-item (count)
"Move to the previous item in Ediff registry or session group buffer.
-Moves in circular fashion. With numeric prefix arg, skip this many items."
+Moves in circular fashion.
+
+With numeric prefix arg COUNT, skip this many items."
(interactive "p")
(or count (setq count 1))
(let (overl)
@@ -1530,7 +1534,9 @@ Useful commands:
(ediff-overlay-put overl 'ediff-meta-session-number session-number))))
(defun ediff-mark-for-hiding-at-pos (unmark)
- "Mark session for hiding. With prefix arg, unmark."
+ "Mark session for hiding.
+
+With prefix arg UNMARK, unmark instead."
(interactive "P")
(let* ((pos (ediff-event-point last-command-event))
(meta-buf (ediff-event-buffer last-command-event))
@@ -1540,10 +1546,9 @@ Useful commands:
(ediff-mark-session-for-hiding info unmark)
(ediff-next-meta-item 1)
(save-excursion
- (ediff-update-meta-buffer meta-buf nil session-number))
- ))
+ (ediff-update-meta-buffer meta-buf nil session-number))))
-;; Returns whether session was marked or unmarked
+;; Return whether session was marked or unmarked.
(defun ediff-mark-session-for-hiding (info unmark)
(let (ignore)
(cond ((eq unmark 'mark) (setq unmark nil))
@@ -1559,7 +1564,9 @@ Useful commands:
(defun ediff-mark-for-operation-at-pos (unmark)
- "Mark session for a group operation. With prefix arg, unmark."
+ "Mark session for a group operation.
+
+With prefix arg UNMARK, unmark instead."
(interactive "P")
(let* ((pos (ediff-event-point last-command-event))
(meta-buf (ediff-event-buffer last-command-event))
@@ -1588,7 +1595,9 @@ Useful commands:
(defun ediff-hide-marked-sessions (unhide)
- "Hide marked sessions. With prefix arg, unhide."
+ "Hide marked sessions.
+
+With prefix arg UNHIDE, unhide instead."
(interactive "P")
(let ((grp-buf (ediff-get-group-buffer ediff-meta-list))
(meta-list (cdr ediff-meta-list))
diff --git a/lisp/vc/ediff-ptch.el b/lisp/vc/ediff-ptch.el
index d52910e..4135e8b 100644
--- a/lisp/vc/ediff-ptch.el
+++ b/lisp/vc/ediff-ptch.el
@@ -128,18 +128,19 @@ You probably don't want to change that, unless you are
using an obscure patch
program."
:type 'regexp)
-;; The buffer of the patch file. Local to control buffer.
-(ediff-defvar-local ediff-patchbufer nil "")
-
-;; The buffer where patch displays its diagnostics.
-(ediff-defvar-local ediff-patch-diagnostics nil "")
-
-;; Map of patch buffer. Has the form:
-;; ((filename1 marker1 marker2) (filename2 marker1 marker2) ...)
-;; where filenames are files to which patch would have applied the patch;
-;; marker1 delimits the beginning of the corresponding patch and marker2 does
-;; it for the end.
-(ediff-defvar-local ediff-patch-map nil "")
+(ediff-defvar-local ediff-patchbufer nil
+ "The buffer of the patch file. Local to control buffer.")
+
+(ediff-defvar-local ediff-patch-diagnostics nil
+ "The buffer where patch displays its diagnostics.")
+
+(ediff-defvar-local ediff-patch-map nil
+ "Map of patch buffer.
+Has the form:
+ ((filename1 marker1 marker2) (filename2 marker1 marker2) ...)
+where filenames are files to which patch would have applied the patch;
+marker1 delimits the beginning of the corresponding patch and marker2 does
+it for the end.")
;; strip prefix from filename
;; returns /dev/null, if can't strip prefix
diff --git a/lisp/vc/ediff-util.el b/lisp/vc/ediff-util.el
index 74c6aba..d079711 100644
--- a/lisp/vc/ediff-util.el
+++ b/lisp/vc/ediff-util.el
@@ -513,7 +513,7 @@ to invocation.")
;; This function assumes that we are in the window where control buffer is
;; to reside.
(defun ediff-setup-control-buffer (ctl-buf)
- "Set up window for control buffer."
+ "Set up window for control buffer CTL-BUF."
(if (window-dedicated-p)
(set-buffer ctl-buf) ; we are in control frame but just in case
(switch-to-buffer ctl-buf))
@@ -661,7 +661,7 @@ if necessary."
(message "")
))
-;; Not bound to any key---to dangerous. A user can do it if necessary.
+;; Not bound to any key---too dangerous. A user can do it if necessary.
(defun ediff-revert-buffers-then-recompute-diffs (noconfirm)
"Revert buffers A, B and C. Then rerun Ediff on file A and file B."
(interactive "P")
@@ -696,11 +696,12 @@ if necessary."
(ediff-merge-buffers bufA bufB)))
(ediff-update-diffs))))
-
-;; optional NO-REHIGHLIGHT says to not rehighlight buffers
(defun ediff-recenter (&optional no-rehighlight)
"Bring the highlighted region of all buffers being compared into view.
-Reestablish the default window display."
+Reestablish the default window display.
+
+If optional NO-REHIGHLIGHT is non-nil, do not rehighlight
+buffers."
(interactive)
(ediff-barf-if-not-control-buffer)
(let (buffer-read-only)
@@ -965,7 +966,7 @@ Please report this bug to bug-gnu-emacs@gnu.org")
(message "Showing ancestor buffer")))
(defun ediff-make-or-kill-fine-diffs (arg)
- "Compute fine diffs. With negative prefix arg, kill fine diffs.
+ "Compute fine diffs. With negative prefix ARG, kill fine diffs.
In both cases, operates on the current difference region."
(interactive "P")
(ediff-barf-if-not-control-buffer)
@@ -1329,7 +1330,7 @@ To change the default, set the variable
`ediff-use-toolbar-p', which see."
;; Merging
(defun ediff-toggle-show-clashes-only ()
- "Toggle the mode that shows only the merge regions where both variants
differ from the ancestor."
+ "Toggle mode showing only merge regions where both variants differ from
ancestor."
(interactive)
(ediff-barf-if-not-control-buffer)
(if (not ediff-merge-with-ancestor-job)
@@ -1510,7 +1511,7 @@ the one half of the height of window-A."
(defun ediff-scroll-horizontally (&optional arg)
"Horizontally scroll buffers A, B (and C if appropriate).
-If an argument is given, that is how many columns are scrolled, else nearly
+With prefix argument ARG, scroll that many columns, else nearly
the width of the A/B/C windows."
(interactive "P")
(ediff-barf-if-not-control-buffer)
@@ -1678,7 +1679,7 @@ the width of the A/B/C windows."
(defun ediff-next-difference (&optional arg)
"Advance to the next difference.
-With a prefix argument, go forward that many differences."
+With a prefix argument ARG, go forward that many differences."
(interactive "p")
(ediff-barf-if-not-control-buffer)
(if (< ediff-current-difference ediff-number-of-differences)
@@ -1729,7 +1730,7 @@ With a prefix argument, go forward that many differences."
(defun ediff-previous-difference (&optional arg)
"Go to the previous difference.
-With a prefix argument, go back that many differences."
+With a prefix argument ARG, go back that many differences."
(interactive "p")
(ediff-barf-if-not-control-buffer)
(if (> ediff-current-difference -1)
@@ -1779,8 +1780,9 @@ With a prefix argument, go back that many differences."
;; The diff number is as perceived by the user (i.e., 1+ the internal
;; representation)
(defun ediff-jump-to-difference (difference-number)
- "Go to the difference specified as a prefix argument.
-If the prefix is negative, count differences from the end."
+ "Go to the difference specified as a prefix argument DIFFERENCE-NUMBER.
+If the prefix argument is negative, count differences from the
+end."
(interactive "p")
(ediff-barf-if-not-control-buffer)
(setq difference-number
@@ -1801,8 +1803,9 @@ If the prefix is negative, count differences from the
end."
The buffer depends on last command character \(a, b, or c) that invoked this
command. For instance, if the command was `ga' then the point value in buffer
A is used.
-With a prefix argument, synchronize all files around the current point position
-in the specified buffer."
+
+With a prefix argument ARG, synchronize all files around the
+current point position in the specified buffer."
(interactive "P")
(ediff-barf-if-not-control-buffer)
(let* ((buf-type (ediff-char-to-buftype last-command-event))
@@ -1898,15 +1901,17 @@ in the specified buffer."
(defun ediff-diff-to-diff (arg &optional keys)
"Copy buffer-X'th difference region to buffer Y (X,Y are A, B, or C).
-If numerical prefix argument, copy the difference specified in the arg.
+With numerical prefix argument ARG, copy the difference specified
+in the arg.
Otherwise, copy the difference given by `ediff-current-difference'.
This command assumes it is bound to a 2-character key sequence, `ab', `ba',
`ac', etc., which is used to determine the types of buffers to be used for
copying difference regions. The first character in the sequence specifies
the source buffer and the second specifies the target.
-If the second optional argument, a 2-character string, is given, use it to
-determine the source and the target buffers instead of the command keys."
+If optional argument KEYS, a 2-character string, is given, use it
+to determine the source and the target buffers instead of the
+command keys."
(interactive "P")
(ediff-barf-if-not-control-buffer)
(or keys (setq keys (this-command-keys)))
@@ -2137,8 +2142,9 @@ ARG is a prefix argument. If nil, copy the current
difference region."
(defun ediff-restore-diff (arg &optional key)
"Restore ARGth diff from `ediff-killed-diffs-alist'.
ARG is a prefix argument. If ARG is nil, restore the current-difference.
-If the second optional argument, a character, is given, use it to
-determine the target buffer instead of `ediff-last-command-char'."
+If the second optional argument KEY, a character, is given, use
+it to determine the target buffer instead of
+`ediff-last-command-char'."
(interactive "P")
(ediff-barf-if-not-control-buffer)
(if (numberp arg)
@@ -2157,8 +2163,8 @@ ARG is a prefix argument. If nil, restore the current
diff."
(defun ediff-toggle-regexp-match ()
- "Toggle between focusing and hiding of difference regions that match
-a regular expression typed in by the user."
+ "Toggle between focusing and hiding difference regions matching a regexp.
+Prompt the user for regular expression."
(interactive)
(ediff-barf-if-not-control-buffer)
(let ((regexp-A "")
@@ -2358,9 +2364,11 @@ flags of the compared file buffers, kills Ediff buffers
for this session
\(but not buffers A, B, C).
If `ediff-keep-variants' is nil, the user will be asked whether the buffers
-containing the variants should be removed \(if they haven't been modified).
-If it is t, they will be preserved unconditionally. A prefix argument,
-temporarily reverses the meaning of this variable."
+containing the variants should be removed (if they haven't been modified).
+If it is t, they will be preserved unconditionally.
+
+With prefix argument REVERSE-DEFAULT-KEEP-VARIANTS, temporarily
+reverse the meaning of this variable."
(interactive "P")
(ediff-barf-if-not-control-buffer)
(let ((ctl-buf (current-buffer))
@@ -3269,7 +3277,7 @@ Hit \\[ediff-recenter] to reset the windows afterward."
`wa' saves buffer A, `wb' saves buffer B, `wc' saves buffer C,
and `wd' saves the diff output.
-With prefix argument, `wd' saves plain diff output.
+With prefix argument ARG, `wd' saves plain diff output.
Without an argument, it saves customized diff argument, if available
\(and plain output, if customized output was not generated)."
(interactive "P")
diff --git a/lisp/vc/ediff-wind.el b/lisp/vc/ediff-wind.el
index 7c90348..bc6aa28 100644
--- a/lisp/vc/ediff-wind.el
+++ b/lisp/vc/ediff-wind.el
@@ -89,25 +89,25 @@ provided functions are written."
(function :tag "Other function"))
:version "24.3")
-;; indicates if we are in a multiframe setup
-(ediff-defvar-local ediff-multiframe nil "")
-
-;; Share of the frame occupied by the merge window (buffer C)
-(ediff-defvar-local ediff-merge-window-share 0.45 "")
-
-;; The control window.
-(ediff-defvar-local ediff-control-window nil "")
-;; Official window for buffer A
-(ediff-defvar-local ediff-window-A nil "")
-;; Official window for buffer B
-(ediff-defvar-local ediff-window-B nil "")
-;; Official window for buffer C
-(ediff-defvar-local ediff-window-C nil "")
-;; Official window for buffer Ancestor
-(ediff-defvar-local ediff-window-Ancestor nil "")
-;; Ediff's window configuration.
-;; Used to minimize the need to rearrange windows.
-(ediff-defvar-local ediff-window-config-saved "" "")
+(ediff-defvar-local ediff-multiframe nil
+ "Indicates if we are in a multiframe setup.")
+
+(ediff-defvar-local ediff-merge-window-share 0.45
+ "Share of the frame occupied by the merge window (buffer C).")
+
+(ediff-defvar-local ediff-control-window nil
+ "The control window.")
+(ediff-defvar-local ediff-window-A nil
+ "Official window for buffer A.")
+(ediff-defvar-local ediff-window-B nil
+ "Official window for buffer B.")
+(ediff-defvar-local ediff-window-C nil
+ "Official window for buffer C.")
+(ediff-defvar-local ediff-window-Ancestor nil
+ "Official window for buffer Ancestor.")
+(ediff-defvar-local ediff-window-config-saved ""
+ "Ediff's window configuration.
+Used to minimize the need to rearrange windows.")
;; Association between buff-type and ediff-window-*
(defconst ediff-window-alist
@@ -176,9 +176,9 @@ In this case, Ediff will use those frames to display these
buffers."
"Frame parameters for displaying Ediff Control Panel.
Used internally---not a user option.")
-;; position of the mouse; used to decide whether to warp the mouse into ctl
-;; frame
-(ediff-defvar-local ediff-mouse-pixel-position nil "")
+(ediff-defvar-local ediff-mouse-pixel-position nil
+ "Position of the mouse.
+Used to decide whether to warp the mouse into control frame.")
;; not used for now
(defvar ediff-mouse-pixel-threshold 30
@@ -227,12 +227,10 @@ customization of the default."
;; Wide frame display
-;; t means Ediff is using wide display
-(ediff-defvar-local ediff-wide-display-p nil "")
-;; keeps frame config for toggling wide display
+(ediff-defvar-local ediff-wide-display-p nil
+ "If t, Ediff is using wide display.")
(ediff-defvar-local ediff-wide-display-orig-parameters nil
- "Frame parameters to be restored when the user wants to toggle the wide
-display off.")
+ "Frame parameters to restore when toggling the wide display off.")
(ediff-defvar-local ediff-wide-display-frame nil
"Frame to be used for wide display.")
(ediff-defvar-local ediff-make-wide-display-function #'ediff-make-wide-display
@@ -243,8 +241,8 @@ frame parameters in `ediff-wide-display-orig-parameters'.
The variable `ediff-wide-display-frame' should be set to contain
the frame used for the wide display.")
-;; Frame used for the control panel in a windowing system.
-(ediff-defvar-local ediff-control-frame nil "")
+(ediff-defvar-local ediff-control-frame nil
+ "Frame used for the control panel in a windowing system.")
(defcustom ediff-prefer-iconified-control-frame nil
"If t, keep control panel iconified when help message is off.
@@ -844,7 +842,7 @@ keyboard input to go into icons."
(defun ediff-skip-unsuitable-frames (&optional ok-unsplittable)
"Skip unsplittable frames and frames that have dedicated windows.
-create a new splittable frame if none is found."
+Create a new splittable frame if none is found."
(if (ediff-window-display-p)
(let ((wind-frame (window-frame))
seen-windows)
diff --git a/lisp/vc/ediff.el b/lisp/vc/ediff.el
index e884ed8..74ed1bd 100644
--- a/lisp/vc/ediff.el
+++ b/lisp/vc/ediff.el
@@ -551,9 +551,11 @@ symbol describing the Ediff job type; it defaults to
;;;###autoload
(defun ediff-directories (dir1 dir2 regexp)
- "Run Ediff on a pair of directories, DIR1 and DIR2, comparing 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."
+ "Run Ediff on directories DIR1 and DIR2, comparing files.
+Consider only files that have the same name in both directories.
+
+REGEXP is nil or a regular expression; only file names that match
+the regexp are considered."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp t))
@@ -608,10 +610,11 @@ names. Only the files that are under revision control
are taken into account."
;;;###autoload
(defun ediff-directories3 (dir1 dir2 dir3 regexp)
- "Run Ediff on three directories, DIR1, DIR2, and DIR3, comparing files that
-have the same name in all three. The last argument, REGEXP, is nil or a
-regular expression; only file names that match the regexp are considered."
+ "Run Ediff on directories DIR1, DIR2, and DIR3, comparing files.
+Consider only files that have the same name in all three directories.
+REGEXP is nil or a regular expression; only file names that match
+the regexp are considered."
(interactive
(let ((dir-A (ediff-get-default-directory-name))
(default-regexp (eval ediff-default-filtering-regexp t))
diff --git a/lisp/vc/emerge.el b/lisp/vc/emerge.el
index b363fa2..25de2f0 100644
--- a/lisp/vc/emerge.el
+++ b/lisp/vc/emerge.el
@@ -26,15 +26,17 @@
;;; Macros
-(defmacro emerge-defvar-local (var value doc)
+(defmacro emerge-defvar-local (symbol value doc)
"Define SYMBOL as an advertised buffer-local variable.
-Performs a defvar, then executes `make-variable-buffer-local' on
-the variable. Also sets the `permanent-local' property, so that
-`kill-all-local-variables' (called by major-mode setting commands)
-won't destroy Emerge control variables."
+Run `defvar-local', setting the value of the variable to VALUE
+and its docstring to DOC.
+
+Then set the `permanent-local' property, so that
+`kill-all-local-variables' (called by major-mode setting
+commands) won't destroy Emerge control variables."
`(progn
- (defvar-local ,var ,value ,doc)
- (put ',var 'permanent-local t)))
+ (defvar-local ,symbol ,value ,doc)
+ (put ',symbol 'permanent-local t)))
;; We need to define this function so describe-mode can describe Emerge mode.
(define-minor-mode emerge-mode
@@ -217,8 +219,7 @@ depend on the flags."
(emerge-new-flags)
(defcustom emerge-min-visible-lines 3
- "Number of lines that we want to show above and below the flags when we are
-displaying a difference."
+ "Number of lines to show above and below the flags when displaying a
difference."
:type 'integer)
(defcustom emerge-temp-file-prefix
@@ -434,8 +435,7 @@ or nil if there is none.")
'((buffer-modified-p set-buffer-modified-p)
buffer-read-only
buffer-auto-save-file-name)
- "Variables and properties of a buffer which are saved, modified and restored
-during a merge.")
+ "Variables and properties of a buffer to save, modify and restore during a
merge.")
(defconst emerge-merging-values '(nil t nil)
"Values to be assigned to emerge-saved-variables during a merge.")
@@ -825,7 +825,7 @@ This is *not* a user option, since Emerge uses it for its
own processing.")
;;;###autoload
(defun emerge-files (_arg file-A file-B file-out &optional startup-hooks
quit-hooks)
- "Run Emerge on two files."
+ "Run Emerge on two files FILE-A and FILE-B."
(interactive
(let (f)
(list current-prefix-arg
@@ -874,7 +874,7 @@ This is *not* a user option, since Emerge uses it for its
own processing.")
;;;###autoload
(defun emerge-buffers (buffer-A buffer-B &optional startup-hooks quit-hooks)
- "Run Emerge on two buffers."
+ "Run Emerge on two buffers BUFFER-A and BUFFER-B."
(interactive "bBuffer A to merge: \nbBuffer B to merge: ")
(let ((emerge-file-A (emerge-make-temp-file "A"))
(emerge-file-B (emerge-make-temp-file "B")))
@@ -1773,15 +1773,15 @@ BEG must be at the beginning of a line."
(emerge-unselect-and-select-difference n)))
(error "At beginning")))
-(defun emerge-jump-to-difference (difference-number)
- "Go to the N-th difference."
+(defun emerge-jump-to-difference (n)
+ "Go to difference number N."
(interactive "p")
(let ((inhibit-read-only t))
- (setq difference-number (1- difference-number))
- (if (and (>= difference-number -1)
- (< difference-number (1+ emerge-number-of-differences)))
- (emerge-unselect-and-select-difference difference-number)
- (error "Bad difference number"))))
+ (setq n (1- n))
+ (if (and (>= n -1)
+ (< n (1+ emerge-number-of-differences)))
+ (emerge-unselect-and-select-difference n)
+ (error "Bad difference number: %s" n))))
(defun emerge-abort ()
"Abort the Emerge session."
@@ -1790,7 +1790,7 @@ BEG must be at the beginning of a line."
(defun emerge-quit (arg)
"Finish the Emerge session and exit Emerge.
-Prefix argument means to abort rather than successfully finish.
+Prefix argument ARG means to abort rather than successfully finish.
The difference depends on how the merge was started,
but usually means to not write over one of the original files, or to signal
to some process which invoked Emerge a failure code.
@@ -1849,7 +1849,7 @@ buffer after this will cause serious problems."
"Select the A variant of this difference.
Refuses to function if this difference has been edited, i.e., if it
is neither the A nor the B variant.
-A prefix argument forces the variant to be selected
+With prefix argument FORCE, force the variant to be selected
even if the difference has been edited."
(interactive "P")
(let ((operate #'emerge-select-A-edit)
@@ -1876,7 +1876,7 @@ even if the difference has been edited."
"Select the B variant of this difference.
Refuses to function if this difference has been edited, i.e., if it
is neither the A nor the B variant.
-A prefix argument forces the variant to be selected
+With prefix argument FORCE, force the variant to be selected
even if the difference has been edited."
(interactive "P")
(let ((operate #'emerge-select-B-edit)
@@ -1973,8 +1973,8 @@ must be prefixed with
\\<emerge-fast-keymap>\\[emerge-basic-keymap]."
"Toggle Auto-Advance mode, for Emerge.
This mode causes `emerge-select-A' and `emerge-select-B' to automatically
advance to the next difference.
-With a positive argument, turn on Auto-Advance mode.
-With a negative argument, turn off Auto-Advance mode."
+With a positive argument ARG, turn on Auto-Advance mode.
+With a negative argument ARG, turn off Auto-Advance mode."
(interactive "P")
(setq emerge-auto-advance (if (null arg)
(not emerge-auto-advance)
@@ -1988,8 +1988,8 @@ With a negative argument, turn off Auto-Advance mode."
"Toggle Skip-Prefers mode, for Emerge.
This mode causes `emerge-next-difference' and `emerge-previous-difference'
to automatically skip over differences for which there is a preference.
-With a positive argument, turn on Skip-Prefers mode.
-With a negative argument, turn off Skip-Prefers mode."
+With a positive argument ARG, turn on Skip-Prefers mode.
+With a negative argument ARG, turn off Skip-Prefers mode."
(interactive "P")
(setq emerge-skip-prefers (if (null arg)
(not emerge-skip-prefers)
@@ -2028,7 +2028,7 @@ With a negative argument, turn off Skip-Prefers mode."
(defun emerge-insert-A (arg)
"Insert the A variant of this difference at the point.
Leaves point after text, mark before.
-With prefix argument, puts point before, mark after."
+With prefix argument ARG, puts point before, mark after."
(interactive "P")
(emerge-validate-difference)
(let* ((diff-vector
@@ -2046,7 +2046,7 @@ With prefix argument, puts point before, mark after."
(defun emerge-insert-B (arg)
"Insert the B variant of this difference at the point.
Leaves point after text, mark before.
-With prefix argument, puts point before, mark after."
+With prefix argument ARG, puts point before, mark after."
(interactive "P")
(emerge-validate-difference)
(let* ((diff-vector
@@ -2063,7 +2063,7 @@ With prefix argument, puts point before, mark after."
(defun emerge-mark-difference (arg)
"Leave the point before this difference and the mark after it.
-With prefix argument, puts mark before, point after."
+With prefix argument ARG, put mark before, point after."
(interactive "P")
(emerge-validate-difference)
(let* ((diff-vector
@@ -2079,7 +2079,7 @@ With prefix argument, puts mark before, point after."
(defun emerge-file-names ()
"Show the names of the buffers or files being operated on by Emerge.
-Use C-u l to reset the windows afterward."
+Use \\[universal-argument] l to reset the windows afterward."
(interactive)
(delete-other-windows)
(let ((temp-buffer-show-function
@@ -2122,7 +2122,7 @@ Use C-u l to reset the windows afterward."
(defun emerge-join-differences (arg)
"Join the selected difference with the following one.
-With a prefix argument, join with the preceding one."
+With a prefix argument ARG, join with the preceding one."
(interactive "P")
(let ((n emerge-current-difference))
;; adjust n to be first difference to join
@@ -2332,9 +2332,9 @@ ancestor version does not share.)"
;; to have it ask for a buffer.
(defun emerge-find-difference (arg)
"Find the difference containing the current position of the point.
-If there is no containing difference and the prefix argument is positive,
-it finds the nearest following difference. A negative prefix argument finds
-the nearest previous difference."
+If there is no containing difference and the prefix argument ARG
+is positive, find the nearest following difference. With
+negative prefix argument, find the nearest previous difference."
(interactive "P")
(cond ((eq (current-buffer) emerge-A-buffer)
(emerge-find-difference-A arg))
@@ -2344,9 +2344,9 @@ the nearest previous difference."
(defun emerge-find-difference-merge (arg)
"Find the difference containing point, in the merge buffer.
-If there is no containing difference and the prefix argument is positive,
-it finds the nearest following difference. A negative prefix argument finds
-the nearest previous difference."
+If there is no containing difference and the prefix argument ARG
+is positive, find the nearest following difference. With
+negative prefix argument, find the nearest previous difference."
(interactive "P")
;; search for the point in the merge buffer, using the markers
;; for the beginning and end of the differences in the merge buffer
@@ -2355,9 +2355,9 @@ the nearest previous difference."
(defun emerge-find-difference-A (arg)
"Find the difference containing point, in the A buffer.
This command must be executed in the merge buffer.
-If there is no containing difference and the prefix argument is positive,
-it finds the nearest following difference. A negative prefix argument finds
-the nearest previous difference."
+If there is no containing difference and the prefix argument ARG
+is positive, find the nearest following difference. With
+negative prefix argument, find the nearest previous difference."
(interactive "P")
;; search for the point in the A buffer, using the markers
;; for the beginning and end of the differences in the A buffer
@@ -2368,9 +2368,9 @@ the nearest previous difference."
(defun emerge-find-difference-B (arg)
"Find the difference containing point, in the B buffer.
This command must be executed in the merge buffer.
-If there is no containing difference and the prefix argument is positive,
-it finds the nearest following difference. A negative prefix argument finds
-the nearest previous difference."
+If there is no containing difference and the prefix argument ARG
+is positive, find the nearest following difference. With
+negative prefix argument, find the nearest previous difference."
(interactive "P")
;; search for the point in the B buffer, using the markers
;; for the beginning and end of the differences in the B buffer
@@ -2450,8 +2450,10 @@ merge buffers."
(defun emerge-set-combine-template (string &optional localize)
"Set `emerge-combine-versions-template' to STRING.
This value controls how `emerge-combine-versions' combines the two versions.
-With prefix argument, `emerge-combine-versions-template' is made local to this
-merge buffer. Localization is permanent for any particular merge buffer."
+
+With prefix argument LOCALIZE, `emerge-combine-versions-template'
+is made local to this merge buffer. Localization is permanent
+for any particular merge buffer."
(interactive "s\nP")
(if localize
(make-local-variable 'emerge-combine-versions-template))
@@ -2464,8 +2466,10 @@ merge buffer. Localization is permanent for any
particular merge buffer."
(defun emerge-set-combine-versions-template (start end &optional localize)
"Copy region into `emerge-combine-versions-template'.
This controls how `emerge-combine-versions' will combine the two versions.
-With prefix argument, `emerge-combine-versions-template' is made local to this
-merge buffer. Localization is permanent for any particular merge buffer."
+
+With prefix argument LOCALIZE, `emerge-combine-versions-template'
+is made local to this merge buffer. Localization is permanent
+for any particular merge buffer."
(interactive "r\nP")
(if localize
(make-local-variable 'emerge-combine-versions-template))
@@ -2479,8 +2483,9 @@ merge buffer. Localization is permanent for any
particular merge buffer."
"Combine versions using the template in `emerge-combine-versions-template'.
Refuses to function if this difference has been edited, i.e., if it is
neither the A nor the B variant.
-An argument forces the variant to be selected even if the difference has
-been edited."
+
+With prefix argument FORCE, force the variant to be selected even
+if the difference has been edited."
(interactive "P")
(emerge-combine-versions-internal emerge-combine-versions-template force))
@@ -2490,8 +2495,9 @@ See documentation of the variable
`emerge-combine-versions-template'
for how the template is interpreted.
Refuses to function if this difference has been edited, i.e., if it is
neither the A nor the B variant.
-An argument forces the variant to be selected even if the difference has
-been edited.
+
+With prefix argument CHAR, force the variant to be selected even
+if the difference has been edited.
Interactively, reads the register using `register-read-with-preview'."
(interactive (list
@@ -2539,9 +2545,9 @@ Interactively, reads the register using
`register-read-with-preview'."
(if emerge-auto-advance (emerge-next-difference))))
(defun emerge-set-merge-mode (mode)
- "Set the major mode in a merge buffer.
-Overrides any change that the mode might make to the mode line or local
-keymap. Leaves merge in fast mode."
+ "Set the major mode to MODE in a merge buffer.
+Override any change that the mode might make to the mode line or
+local keymap. Leave merge in fast mode."
(interactive
(list (intern (completing-read "New major mode for merge buffer: "
obarray 'commandp t nil))))
@@ -2678,8 +2684,8 @@ keymap. Leaves merge in fast mode."
(emerge-refresh-mode-line))))
(defun emerge-select-version (force a-version b-version neither-version)
- "Perform tests to see whether user should be allowed to select a version
-of this difference:
+ "Test if user should be allowed to select a version of this difference.
+This is the case if:
a valid difference has been selected; and
the difference text in the merge buffer is:
the A version (execute a-version), or
@@ -2847,7 +2853,9 @@ Otherwise, signal an error."
;; When the pointless option emerge-temp-file-prefix goes,
;; make this function obsolete too, and just use make-temp-file.
(defun emerge-make-temp-file (prefix)
- "Make a private temporary file based on `emerge-temp-file-prefix'."
+ "Make a private temporary file based on PREFIX.
+This is named by concatenating `emerge-temp-file-prefix' with
+PREFIX."
(make-temp-file (concat emerge-temp-file-prefix prefix)))
;;; Functions that query the user before he can write out the current buffer.
diff --git a/lisp/vc/log-view.el b/lisp/vc/log-view.el
index bc66191..c2f008f 100644
--- a/lisp/vc/log-view.el
+++ b/lisp/vc/log-view.el
@@ -50,7 +50,7 @@
;; ------------------------------------------------------------------------
;; r4622 | ckuethe | 2007-12-23 18:18:01 -0500 (Sun, 23 Dec 2007) | 2 lines
;;
-;; uBlox AEK-4T in binary mode. Added to unstable because it breaks gpsfake
+;; uBlox AEK-4T in binary mode. Added to unstable because it breaks gpsfake
;;
;; ------------------------------------------------------------------------
;; r4621 | ckuethe | 2007-12-23 16:48:11 -0500 (Sun, 23 Dec 2007) | 3 lines
diff --git a/lisp/vc/pcvs.el b/lisp/vc/pcvs.el
index 23f0902..726fe4e 100644
--- a/lisp/vc/pcvs.el
+++ b/lisp/vc/pcvs.el
@@ -672,7 +672,7 @@ it is finished."
(when cvs-postproc
(if (null procbuf)
;;(set-process-buffer proc nil)
- (error "cvs' process buffer was killed")
+ (error "CVS process buffer was killed")
(with-current-buffer procbuf
;; Do the postprocessing like parsing and such.
(save-excursion
@@ -1503,7 +1503,7 @@ The POSTPROC specified there (typically `log-edit') is
then called,
(defvar cvs-edit-log-revision)
(defvar cvs-edit-log-files) (put 'cvs-edit-log-files 'permanent-local t)
(defun cvs-mode-edit-log (file rev &optional text)
- "Edit the log message at point.
+ "Edit log message at point.
This is best called from a `log-view-mode' buffer."
(interactive
(list
@@ -1661,7 +1661,7 @@ See `cvs-mode-diff' for more info."
This command can be used on files that are marked with \"Merged\"
or \"Conflict\" in the *cvs* buffer."
(interactive (list (cvs-flags-query 'cvs-diff-flags "diff flags")))
- (unless (listp flags) (error "flags should be a list of strings"))
+ (unless (listp flags) (error "Flags should be a list of strings"))
(save-some-buffers)
(let* ((marked (cvs-get-marked (cvs-ignore-marks-p "diff")))
(fis (car (cvs-partition 'cvs-fileinfo->backup-file marked))))
@@ -1862,7 +1862,7 @@ POSTPROC is a function of no argument to be evaluated at
the very end (after
(let ((def-dir default-directory))
;; Save the relevant buffers
(save-some-buffers nil (lambda () (cvs-is-within-p fis def-dir))))
- (unless (listp flags) (error "flags should be a list of strings"))
+ (unless (listp flags) (error "Flags should be a list of strings"))
;; Some w32 versions of CVS don't like an explicit . too much.
(when (and (car fis) (null (cdr fis))
(eq (cvs-fileinfo->type (car fis)) 'DIRCHANGE)
@@ -2259,7 +2259,7 @@ With prefix argument, prompt for cvs flags."
;;;;
(defun cvs-dir-member-p (fileinfo dir)
- "Return true if FILEINFO represents a file in directory DIR."
+ "Return non-nil if FILEINFO represents a file in directory DIR."
(and (not (eq (cvs-fileinfo->type fileinfo) 'DIRCHANGE))
(string-prefix-p dir (cvs-fileinfo->dir fileinfo))))
@@ -2316,7 +2316,7 @@ this file, or a list of arguments to send to the program."
(defun cvs-change-cvsroot (newroot)
- "Change the CVSROOT."
+ "Change the CVSROOT to NEWROOT."
(interactive "DNew repository: ")
(if (or (file-directory-p (expand-file-name "CVSROOT" newroot))
(y-or-n-p (concat "Warning: no CVSROOT found inside repository."
diff --git a/lisp/vc/smerge-mode.el b/lisp/vc/smerge-mode.el
index 956d9b3..b2a875c 100644
--- a/lisp/vc/smerge-mode.el
+++ b/lisp/vc/smerge-mode.el
@@ -961,7 +961,7 @@ It has the following disadvantages:
(defvar smerge--refine-long-words)
(defun smerge--refine-chopup-region (beg end file &optional preproc)
- "Chopup the region into small elements, one per line.
+ "Chopup the region from BEG to END into small elements, one per line.
Save the result into FILE.
If non-nil, PREPROC is called with no argument in a buffer that contains
a copy of the text, just before chopping it up. It can be used to replace
diff --git a/lisp/vc/vc-dir.el b/lisp/vc/vc-dir.el
index ebecdff..f8b8717 100644
--- a/lisp/vc/vc-dir.el
+++ b/lisp/vc/vc-dir.el
@@ -374,7 +374,7 @@ See `run-hooks'."
"Keymap for directory buffer.")
(defmacro vc-dir-at-event (event &rest body)
- "Evaluate BODY with point located at event-start of EVENT.
+ "Evaluate BODY with point located at `event-start' of EVENT.
If BODY uses EVENT, it should be a variable,
otherwise it will be evaluated twice."
(let ((posn (make-symbol "vc-dir-at-event-posn")))
@@ -567,7 +567,7 @@ If NOINSERT, ignore elements on ENTRIES which are not in
the ewoc."
(defun vc-dir-next-line (arg)
"Go to the next line.
-If a prefix argument is given, move by that many lines."
+With prefix argument ARG, move that many lines."
(interactive "p")
(with-no-warnings
(ewoc-goto-next vc-ewoc arg)
@@ -575,7 +575,7 @@ If a prefix argument is given, move by that many lines."
(defun vc-dir-previous-line (arg)
"Go to the previous line.
-If a prefix argument is given, move by that many lines."
+With prefix argument ARG, move that many lines."
(interactive "p")
(ewoc-goto-prev vc-ewoc arg)
(vc-dir-move-to-goal-column))
@@ -703,7 +703,7 @@ line."
(defun vc-dir-mark-all-files (arg)
"Mark all files with the same state as the current one.
-With a prefix argument mark all files (not directories).
+With prefix argument ARG, mark all files (not directories).
If the current entry is a directory, mark all child files.
The commands operate on files that are on the same state.
@@ -813,7 +813,7 @@ line."
(defun vc-dir-unmark-all-files (arg)
"Unmark all files with the same state as the current one.
-With a prefix argument unmark all files.
+With prefix argument ARG, unmark all files.
If the current entry is a directory, unmark all the child files.
The commands operate on files that are on the same state.
@@ -1181,7 +1181,7 @@ specific headers."
"\n"))
(defun vc-dir-refresh-files (files)
- "Refresh some files in the *VC-dir* buffer."
+ "Refresh some FILES in the *VC-dir* buffer."
(let ((def-dir default-directory)
(backend vc-dir-backend))
(vc-set-mode-line-busy-indicator)
diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el
index ec572e9..8332600 100644
--- a/lisp/vc/vc-git.el
+++ b/lisp/vc/vc-git.el
@@ -897,8 +897,7 @@ The car of the list is the current branch."
(declare-function log-edit--toggle-amend "log-edit" (last-msg-fn))
(defun vc-git-log-edit-toggle-signoff ()
- "Toggle whether to add the \"Signed-off-by\" line at the end of
-the commit message."
+ "Toggle whether to add the \"Signed-off-by\" line at the end of commit
message."
(interactive)
(log-edit-toggle-header "Sign-Off" "yes"))
@@ -1613,8 +1612,8 @@ before it is executed.
With two \\[universal-argument] prefixes, directly edit and run `grep-command'.
Collect output in a buffer. While git grep runs asynchronously, you
-can use \\[next-error] (M-x next-error), or
\\<grep-mode-map>\\[compile-goto-error] \
-in the grep output buffer,
+can use \\[next-error] (`next-error'), or \\<grep-mode-map>\
+\\[compile-goto-error] in the grep output buffer,
to go to the lines where grep found matches.
This command shares argument histories with \\[rgrep] and \\[grep]."
diff --git a/lisp/vc/vc-hg.el b/lisp/vc/vc-hg.el
index 1e8d673..0ed9f7c 100644
--- a/lisp/vc/vc-hg.el
+++ b/lisp/vc/vc-hg.el
@@ -137,8 +137,7 @@ switches."
:version "25.1")
(defcustom vc-hg-revert-switches nil
- "String or list of strings specifying switches for hg revert
-under VC."
+ "String or list of strings specifying switches for hg revert under VC."
:type '(choice (const :tag "None" nil)
(string :tag "Argument String")
(repeat :tag "Argument List" :value ("") string))
@@ -643,8 +642,8 @@ Variable `vc-hg-create-bookmark' controls what kind of
branch will be created."
;;; Native data structure reading
(defcustom vc-hg-parse-hg-data-structures t
- "If true, try directly parsing Mercurial data structures
-directly instead of always running Mercurial. We try to be safe
+ "If true, try parsing Mercurial data structures directly.
+This is done instead of always running Mercurial. We try to be safe
against Mercurial data structure format changes and always fall
back to running Mercurial directly."
:type 'boolean
@@ -1017,9 +1016,9 @@ FILENAME must be the file's true absolute name."
"remotefilelog"
"revlogv1"
"store")
- "List of Mercurial repository requirements we understand; if a
-repository requires features not present in this list, we avoid
-attempting to parse Mercurial data structures.")
+ "List of Mercurial repository requirements we understand.
+If a repository requires features not present in this list, we
+avoid attempting to parse Mercurial data structures.")
(defun vc-hg--requirements-understood-p (repo)
"Check that we understand the format of the given repository.