master 5b44e05: ; Fix some recent fixes to doc strings

[Eli Zaretskii]

branch: master
commit 5b44e0511a881593eb62ff1648be37ac1c728ecc
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; 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.
---
 lisp/cedet/data-debug.el     | 5 +++--
 lisp/emulation/viper-cmd.el  | 8 ++++----
 lisp/emulation/viper-init.el | 5 +++--
 lisp/gnus/nnvirtual.el       | 9 ++++++---
 lisp/vc/ediff.el             | 3 +--
 lisp/vc/vc-annotate.el       | 2 +-
 lisp/vc/vc-dir.el            | 8 +++++---
 lisp/whitespace.el           | 3 +--
 8 files changed, 24 insertions(+), 19 deletions(-)

diff --git a/lisp/cedet/data-debug.el b/lisp/cedet/data-debug.el
index 8f40a4d..d8d1364 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 b132d78..3fcc14c 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 ffcb460..fe37048 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 4136392..41a2da9 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 e406275..49fc604 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 5a4ac1a..def87db 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 d079b89..8165d5e 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 6e132de..017409d 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