; Fix some recent fixes to doc strings

* lisp/whitespace.el (whitespace-empty-at-bob-regexp):
* lisp/vc/vc-dir.el (vc-dir-child-files-and-states):
* lisp/vc/vc-annotate.el
(vc-annotate-show-changeset-diff-revision-at-line):
* lisp/vc/ediff.el (ediff-merge-with-ancestor-command):
* lisp/gnus/nnvirtual.el (nnvirtual-update-xref-header)
(nnvirtual-map-article):
* lisp/emulation/viper-init.el (viper-ESC-keyseq-timeout):
* lisp/emulation/viper-cmd.el
(viper-set-parsing-style-toggling-macro):
* lisp/cedet/data-debug.el (data-debug-insert-hash-table-button):
"The first line of a doc string must be a complete sentence."
Also, fix some awkward wording in doc strings while at that.

8 files changed, 24 insertions, 19 deletions

diff --git a/lisp/cedet/data-debug.el b/lisp/cedet/data-debug.el
index 8f40a4db79d..d8d1364491f 100644
--- a/lisp/cedet/data-debug.el
+++ b/lisp/cedet/data-debug.el
@@ -413,8 +413,9 @@ PREBUTTONTEXT is some text between prefix and the stuff list button."
   )
 
 (defun data-debug-insert-hash-table-button (hash-table prefix prebuttontext)
-  "Insert HASH-TABLE as expandable button with recursive prefix PREFIX and
-PREBUTTONTEXT in front of the button text."
+  "Insert HASH-TABLE as expandable button, using PREFIX and PREBUTTONTEXT.
+PREFIX is a recursive prefix and PREBUTTONTEXT is text to be inserted
+in front of the button text."
   (let ((string (propertize (format "%s" hash-table)
 			    'face 'font-lock-keyword-face)))
     (insert (propertize
diff --git a/lisp/emulation/viper-cmd.el b/lisp/emulation/viper-cmd.el
index b132d786eb1..3fcc14c99d7 100644
--- a/lisp/emulation/viper-cmd.el
+++ b/lisp/emulation/viper-cmd.el
@@ -3546,11 +3546,11 @@ If MODE is set, set the macros only in that major mode."
 
 
 (defun viper-set-parsing-style-toggling-macro (unset)
-  "Set `%%%' to be a macro that toggles whether comment fields should be parsed
-for matching parentheses.
+  "Set or unset `%%%' as a macro that toggles comment parsing for parentheses.
 This is used in conjunction with the `%' command.
-
-With a prefix argument, unsets the macro."
+By default, sets the macro which will toggle whether comment fields should
+be parsed for matching parentheses.  With a prefix argument, unsets the
+macro instead."
   (interactive "P")
   (or noninteractive
       (if (not unset)
diff --git a/lisp/emulation/viper-init.el b/lisp/emulation/viper-init.el
index ffcb4602e73..fe3704841ac 100644
--- a/lisp/emulation/viper-init.el
+++ b/lisp/emulation/viper-init.el
@@ -932,8 +932,9 @@ Should be set in `viper-custom-file-name'."
   (setq cursor-type '(bar . 2)))
 
 (defun viper-ESC-keyseq-timeout ()
-  "Key sequence beginning with ESC and separated by no more than this many
-milliseconds is considered to be generated by a keyboard function key.
+  "Return the timeout for considering an ESC sequence to be a function key.
+Sequences of keys beginning with ESC and separated by no more than this many
+milliseconds are considered to be generated by a keyboard function key.
 Setting this too high may slow down switching from insert to vi state.  Setting
 this value too low will make it impossible to use function keys in insert mode
 on a dumb terminal."
diff --git a/lisp/gnus/nnvirtual.el b/lisp/gnus/nnvirtual.el
index 4136392c825..41a2da958a0 100644
--- a/lisp/gnus/nnvirtual.el
+++ b/lisp/gnus/nnvirtual.el
@@ -382,8 +382,10 @@ It is computed from the marks of individual component groups.")
 
 
 (defun nnvirtual-update-xref-header (group article prefix sysname)
-  "Edit current NOV header in current buffer to have an xref to the component
-group, and also server prefix any existing xref lines."
+  "Edit current NOV header to have xref to component group and correct prefix.
+This function edits the current NOV header in current buffer so that it
+has an xref to the component group, and also ensures any existing xref
+lines have the correct component server prefix."
   ;; Move to beginning of Xref field, creating a slot if needed.
   (beginning-of-line)
   (looking-at
@@ -570,7 +572,8 @@ If UPDATE-P is not nil, call gnus-group-update-group on the components."
 ;; unique reverse mapping.
 
 (defun nnvirtual-map-article (article)
-  "Return a cons of the component group and article corresponding to the given
+  "Return the component group and article corresponding to virtual ARTICLE.
+Value is a cons of the component group and article corresponding to the given
 virtual ARTICLE."
   (let ((table nnvirtual-mapping-table)
 	entry group-pos)
diff --git a/lisp/vc/ediff.el b/lisp/vc/ediff.el
index e406275cd1a..49fc60431f6 100644
--- a/lisp/vc/ediff.el
+++ b/lisp/vc/ediff.el
@@ -1600,8 +1600,7 @@ With optional NODE, goes to that node."
 
 ;;;###autoload
 (defun ediff-merge-with-ancestor-command ()
-  "Call `ediff-merge-files-with-ancestor' with the next three command line
-arguments."
+  "Call `ediff-merge-files-with-ancestor' with next three command line arguments."
   (let ((file-a (nth 0 command-line-args-left))
 	(file-b (nth 1 command-line-args-left))
 	(ancestor (nth 2 command-line-args-left)))
diff --git a/lisp/vc/vc-annotate.el b/lisp/vc/vc-annotate.el
index 5a4ac1aca84..def87db8712 100644
--- a/lisp/vc/vc-annotate.el
+++ b/lisp/vc/vc-annotate.el
@@ -610,7 +610,7 @@ the file in question, search for the log entry required and move point."
   (vc-annotate-show-diff-revision-at-line-internal t))
 
 (defun vc-annotate-show-changeset-diff-revision-at-line ()
-  "Visit diff of revision at line from previous revision.
+  "Show the diffs of revision at current line relative to previous revision.
 This is done for all files in changeset."
   (interactive)
   (when (eq 'file (vc-call-backend vc-annotate-backend 'revision-granularity))
diff --git a/lisp/vc/vc-dir.el b/lisp/vc/vc-dir.el
index d079b891e4d..8165d5e09f1 100644
--- a/lisp/vc/vc-dir.el
+++ b/lisp/vc/vc-dir.el
@@ -1015,9 +1015,11 @@ child files."
     (nreverse result)))
 
 (defun vc-dir-child-files-and-states ()
-  "Return list of conses for child files of the current entry if it's a directory.
-The conses have the format (FILE . STATE).
-If it is a file, return the corresponding cons for the file itself."
+  "Return the state of one or more files for the current entry.
+If the entry is a directory, return the list of states of its child
+files, where each file is described by a cons of the form (FILE . STATE).
+If the entry is a file, return a single cons cell (FILE . STATE) for
+that file."
   (let* ((crt (ewoc-locate vc-ewoc))
 	 (crt-data (ewoc-data crt))
          result)
diff --git a/lisp/whitespace.el b/lisp/whitespace.el
index 6e132de536d..017409d6a42 100644
--- a/lisp/whitespace.el
+++ b/lisp/whitespace.el
@@ -2193,8 +2193,7 @@ resultant list will be returned."
    limit t))
 
 (defun whitespace-empty-at-bob-regexp (limit)
-  "Match spaces at beginning of buffer which do not contain
-the point at beginning of buffer."
+  "Match spaces at beginning of buffer (BOB) which do not contain point at BOB."
   (let ((b (point))
 	r)
     (cond