Fix most doc issues raised by (checkdoc)

11 files changed, 82 insertions, 59 deletions

diff --git a/lib/bufhist.el b/lib/bufhist.el
index 4c24ca42..65d33cc5 100644
--- a/lib/bufhist.el
+++ b/lib/bufhist.el
@@ -186,7 +186,8 @@ This is as a pair (POINT . CONTENTS)."
   (bufhist-insert-buttons))
 
 (defun bufhist-checkpoint-and-erase ()
-  "Add buffer contents to history then erase. Only erase if not in bufhist mode"
+  "Add buffer contents to history then erase.
+Only erase if not in bufhist mode."
   (interactive)
   (bufhist-checkpoint)
   (bufhist-erase-buffer))
@@ -241,7 +242,8 @@ If optional NOSAVE is non-nil, do not try to save current contents."
   (bufhist-switch-to-index 0 nil 'browsing))
 
 (defun bufhist-prev (&optional n)
-  "Browse backward in the history of buffer contents."
+  "Browse backward in the history of buffer contents.
+If N is omitted or nil, move backward by one item."
   (interactive "p")
   (bufhist-switch-to-index
    (mod (+ bufhist-ring-pos (or n 1))
@@ -249,7 +251,8 @@ If optional NOSAVE is non-nil, do not try to save current contents."
    nil 'browsing))
 
 (defun bufhist-next (&optional n)
-  "Browse forward in the history of buffer contents."
+  "Browse forward in the history of buffer contents.
+If N is omitted or nil, move forward by one item."
   (interactive "p")
   (bufhist-prev (- (or n 1))))
 
@@ -284,7 +287,7 @@ If optional NOSAVE is non-nil, do not try to save current contents."
   "Initialise a ring history for the current buffer.
 The history will be read-only unless READWRITE is non-nil.
 For read-only histories, edits to the buffer switch to the latest version.
-The size defaults to `bufhist-ring-size'."
+If RINGSIZE is omitted or nil, the size defaults to ‘bufhist-ring-size’."
   (interactive)
   (setq bufhist-ring (make-ring (or ringsize bufhist-ring-size)))
   (setq bufhist-normal-read-only buffer-read-only)
@@ -370,3 +373,4 @@ The size defaults to `bufhist-ring-size'."
 	(setq bufhist-top-point (point))))))
 
 (provide 'bufhist)
+;;; bufhist.el ends here
diff --git a/lib/holes.el b/lib/holes.el
index 2b154723..9a45037c 100644
--- a/lib/holes.el
+++ b/lib/holes.el
@@ -42,7 +42,7 @@
 ;;; initialization
 ;;;
 
-(defvar holes-default-hole 
+(defvar holes-default-hole
   (let ((ol (make-overlay 0 0)))
     (delete-overlay ol) ol)
   "An empty detached hole used as the default hole.
@@ -78,7 +78,7 @@ which should be removed when making the text into a hole."
 
 
 ;(defcustom holes-search-limit 1000
-;  "Number of chars to look forward when looking for the next hole, unused for now.") 
+;  "Number of chars to look forward when looking for the next hole, unused for now.")
 ;unused for the moment
 
 ;; The following is customizable by a command of the form:
@@ -121,18 +121,18 @@ which should be removed when making the text into a hole."
     (define-key map [(mouse-2)] 'holes-mouse-forget-hole)
     map)
   "Keymap to use on the holes's overlays.
-This keymap is used only when point is on a hole.  
+This keymap is used only when point is on a hole.
 See `holes-mode-map' for the keymap of `holes-mode'.")
 
 (defvar holes-mode-map
   (let ((map (make-sparse-keymap)))
     (define-key map [(control c) (h)] 'holes-set-make-active-hole)
     (define-key map [(control c) (control y)] 'holes-replace-update-active-hole)
-    (define-key map [(control meta down-mouse-1)] 
+    (define-key map [(control meta down-mouse-1)]
       'holes-mouse-set-make-active-hole)
-    (define-key map [(control meta shift down-mouse-1)] 
+    (define-key map [(control meta shift down-mouse-1)]
       'holes-mouse-replace-active-hole)
-    (define-key map [(control c) (control j)] 
+    (define-key map [(control c) (control j)]
       'holes-set-point-next-hole-destroy)
     map)
   "Keymap of `holes-mode'.
@@ -190,7 +190,7 @@ This is not the keymap used on holes's overlay (see `hole-map' instead).")
 
 (defun holes-hole-start-position (hole)
   "Return start position of HOLE."
-  (assert (holes-is-hole-p hole) t 
+  (assert (holes-is-hole-p hole) t
 	  "holes-hole-start-position: %s is not a hole")
   (span-start hole))
 
@@ -285,7 +285,7 @@ the active hole is already disable."
 Error if HOLE is not a hole."
   (assert (holes-is-hole-p hole) t
 	  "holes-set-active-hole: %s is not a hole")
-  (if (holes-active-hole-exist-p) 
+  (if (holes-active-hole-exist-p)
       (holes-highlight-hole holes-active-hole))
   (setq holes-active-hole hole)
   (holes-highlight-hole-as-active holes-active-hole))
@@ -330,7 +330,7 @@ the span."
   "Clear the HOLE."
   (assert (holes-is-hole-p hole) t
 	  "holes-clear-hole: %s is not a hole")
-  (if (and (holes-active-hole-exist-p) 
+  (if (and (holes-active-hole-exist-p)
 	   (eq holes-active-hole hole))
       (holes-disable-active-hole))
   (span-delete hole))
@@ -343,9 +343,10 @@ the span."
   (holes-clear-hole (holes-hole-at (or pos (point)))))
 
 
-(defun holes-map-holes (function &optional object from to)
-  "Map function FUNCTION across holes."
-  (fold-spans function object from to nil nil 'hole))
+(defun holes-map-holes (function &optional buffer from to)
+  "Map function FUNCTION across holes in buffer BUFFER.
+Operate between character positions FROM and TO."
+  (fold-spans function buffer from to nil nil 'hole))
 
 (defun holes-clear-all-buffer-holes (&optional start end)
   "Clear all holes leaving their contents.
@@ -353,7 +354,7 @@ Operate betwenn START and END if non nil."
   (interactive)
   (holes-disable-active-hole)
   (span-mapcar-spans
-   'holes-clear-hole (or start (point-min)) (or end (point-max)) 
+   'holes-clear-hole (or start (point-min)) (or end (point-max))
    'hole))
 
 ;; limit ?
@@ -361,7 +362,7 @@ Operate betwenn START and END if non nil."
   "Return the first hole after POS in BUFFER.
 Or after the hole at pos if there is one (default pos=point).  If no
 hole found, return nil."
-  (holes-map-holes 
+  (holes-map-holes
    (lambda (h x) (and (holes-is-hole-p h) h)) buffer pos))
 
 (defun holes-next-after-active-hole ()
@@ -391,7 +392,8 @@ Default pos = point and buffer = current."
 
 
 (defun holes-replace-segment (start end str &optional buffer)
-  "Erase chars between START and END, and replace them with STR."
+  "Erase chars between START and END, and replace them with STR.
+Operate in buffer BUFFER."
   (with-current-buffer (or buffer (current-buffer))
     (goto-char end)
     ;; Insert before deleting, so the markers at `start' and `end'
@@ -445,9 +447,9 @@ following hole if it exists."
       (let ((nxthole (holes-next-after-active-hole)))
 	(holes-replace-active-hole
 	 (or str
-	     (and mark-active 
+	     (and mark-active
 		  (holes-copy-active-region))
-	     (current-kill 0) 
+	     (current-kill 0)
 	     (error "Nothing to put in hole")))
 	(if nxthole (holes-set-active-hole nxthole)
 	  (setq holes-active-hole holes-default-hole)))))
@@ -477,7 +479,7 @@ Sets `holes-active-hole' to the next hole if it exists."
 
 (defalias 'holes-track-mouse-selection 'mouse-drag-track)
 (defsubst holes-track-mouse-clicks ()
-  "See `mouse-track-click-count'"
+  "See `mouse-track-click-count'."
   (+ mouse-selection-click-count 1))
 
 (defun holes-mouse-replace-active-hole (event)
@@ -497,7 +499,7 @@ Sets `holes-active-hole' to the next hole if it exists."
 (defun holes-destroy-hole (&optional span)
   "Destroy the hole SPAN."
   (interactive)
-  (let* ((sp (or span (holes-hole-at (point)) 
+  (let* ((sp (or span (holes-hole-at (point))
 		 (error "No hole to destroy"))))
     (save-excursion
       (if (and (holes-active-hole-exist-p)
@@ -555,7 +557,7 @@ Sets `holes-active-hole' to the next hole if it exists."
 
 
 (defun holes-set-point-next-hole-destroy ()
-  "Moves the point to current active hole (if any and if in current buffer).
+  "Move the point to current active hole (if any and if in current buffer).
 Destroy it and makes the next hole active if any."
   (interactive)
   (assert (holes-active-hole-exist-p) nil "no active hole")
@@ -583,7 +585,10 @@ Destroy it and makes the next hole active if any."
 (defun holes-replace-string-by-holes-backward (limit)
   "Change each occurrence of REGEXP into a hole.
 Sets the active hole to the last created hole and unsets it if no hole is
-created.  Return the number of holes created."
+created.  Return the number of holes created.
+The LIMIT argument bounds the search; it is a buffer position.
+  The match found must not begin before that position.  A value of nil
+  means search to the beginning of the accessible portion of the buffer."
   (holes-disable-active-hole)
   (let ((n 0))
     (save-excursion
@@ -615,9 +620,9 @@ created.  Return the number of holes created."
 
 (defun holes-replace-string-by-holes-backward-jump (pos &optional noindent alwaysjump)
   "Put holes between POS and point, backward, indenting.
-\"#\" and \"@{..}\" between this positions will become holes. If
-ALWAYSJUMP is non nil, jump to the first hole even if more than
-one."
+\"#\" and \"@{..}\" between this positions will become holes.
+If NOINDENT is non-nil, skip the indenting step.
+If ALWAYSJUMP is non-nil, jump to the first hole even if more than one."
   (unless noindent (save-excursion (indent-region pos (point) nil)))
   (let ((n (holes-replace-string-by-holes-backward pos)))
     (case n
@@ -634,7 +639,7 @@ one."
 
 
 ;;;###autoload
-(define-minor-mode holes-mode 
+(define-minor-mode holes-mode
   "Toggle Holes minor mode.
 With arg, turn Outline minor mode on if arg is positive, off otherwise.
 
diff --git a/lib/local-vars-list.el b/lib/local-vars-list.el
index bcea270f..4d737d73 100644
--- a/lib/local-vars-list.el
+++ b/lib/local-vars-list.el
@@ -34,9 +34,9 @@
 (defconst local-vars-list-doc nil
 "From Emacs Info:
 
-A file can contain a \"local variables list\", which specifies the values to use for
-certain Emacs variables when that file is edited. See info node \"(emacs)File
-Variables\".
+A file can contain a \"local variables list\", which specifies the values to use
+for certain Emacs variables when that file is edited.
+See info node \"(emacs)File Variables\".
 
 local-vars-list provides two useful functions:
 
@@ -111,7 +111,7 @@ variable definition (or at the \"End:\" line)."
 	(read (buffer-substring boexp (point))))))) ; TODO: catch errors here?
 
 
-;; Only looks for file local vars. Not dir local vars. 
+;; Only looks for file local vars. Not dir local vars.
 (defun local-vars-list-get (symb)
   "Return the value written in the local variable list for variable symb.
 Raises an error if symb is not in the list.
@@ -122,14 +122,14 @@ alist. Proceed by looking in the file instead."
   (save-excursion
     (let*
 	((lrpat (local-vars-list-find))
-	 (dummy (if lrpat t (error "local variables zone not found. ")))
+	 (dummy (if lrpat t (error "Local variables zone not found")))
 	 (lpat (car lrpat))
 	 (rpat (car (cdr lrpat)))
 	 )
       (beginning-of-line)
       (if (local-vars-list-goto-var symb lpat rpat)
 	  t
-	(error "variable %s not found" symb))
+	(error "Variable %s not found" symb))
       (beginning-of-line)
       (local-vars-list-get-current lpat rpat))))
 
@@ -154,3 +154,6 @@ of the buffer first."
 ;;; fill-column: 85 ***
 ;;; indent-tabs-mode: nil ***
 ;;; End: ***
+
+(provide 'local-vars-list)
+;;; local-vars-list.el ends here
diff --git a/lib/maths-menu.el b/lib/maths-menu.el
index a6b64201..32911a35 100644
--- a/lib/maths-menu.el
+++ b/lib/maths-menu.el
@@ -56,7 +56,7 @@
 ;;; Code:
 
 (defvar maths-menu-filter-predicate (lambda (char) t)
-  "Predicate function used to filter menu elements")
+  "Predicate function used to filter menu elements.")
 
 (defvar maths-menu-tokenise-insert #'insert
   "Function used to insert possibly formatted or escaped character.")
diff --git a/lib/pg-dev.el b/lib/pg-dev.el
index 79afca23..8e82a753 100644
--- a/lib/pg-dev.el
+++ b/lib/pg-dev.el
@@ -114,7 +114,7 @@
      pg-thymodes pg-autotest
      ;;
      isar-syntax isar-find-theorems isar-unicode-tokens
-     isar-autotest interface-setup isabelle-system isar 
+     isar-autotest interface-setup isabelle-system isar
      isar-keywords
      ;;
      coq-abbrev coq-db coq-unicode-tokens coq-local-vars coq coq-syntax
@@ -130,7 +130,7 @@
 
 ;;;###autoload
 (defun profile-pg ()
-  "Configure Proof General for profiling.  Use M-x elp-results to see results."
+  "Configure Proof General for profiling.  Use \\[elp-results] to see results."
   (interactive)
   (elp-instrument-package "proof-")
   (elp-instrument-package "pg-")
@@ -142,10 +142,10 @@
   (elp-instrument-package "replace-") ; for replace-regexp etc
   (elp-instrument-package "re-search-") ; for re-search-forwad etc
   (elp-instrument-package "skip-chars-") ; for skip chars etc
-  (elp-instrument-list 
+  (elp-instrument-list
    '(string-match match-string re-search-forward re-search-backward
      skip-chars-forward skip-chars-backward
-     goto-char insert 
+     goto-char insert
      set-marker marker-position
      nreverse nconc mapc
      member
@@ -153,7 +153,7 @@
      sit-for
      overlay-put overlay-start overlay-end make-overlay
      buffer-live-p kill-buffer
-     process-status get-buffer-process 
+     process-status get-buffer-process
      delete-overlay move-overlay
      accept-process-output))
   (elp-instrument-package "font-lock"))
diff --git a/lib/proof-compat.el b/lib/proof-compat.el
index 4c1fa5b2..abbdb465 100644
--- a/lib/proof-compat.el
+++ b/lib/proof-compat.el
@@ -141,6 +141,5 @@ The value returned is the value of the last form in BODY."
   (if (and (symbolp this-command) (get this-command 'completion-function))
 	(funcall (get this-command 'completion-function)))))
 
-
-;; End of proof-compat.el
 (provide 'proof-compat)
+;;; proof-compat.el ends here
diff --git a/lib/scomint.el b/lib/scomint.el
index 3644add2..8f7104e8 100644
--- a/lib/scomint.el
+++ b/lib/scomint.el
@@ -88,7 +88,7 @@ a TCP connection to be opened via `open-network-stream'.  If there is already
 a running process in that buffer, it is not restarted.  Optional fourth arg
 STARTFILE is the name of a file to send the contents of to the process.
 
-If PROGRAM is a string, any more args are arguments to PROGRAM."
+If PROGRAM is a string, the remaining SWITCHES are arguments to PROGRAM."
   (unless (or (fboundp 'start-process)
 	      (fboundp 'start-file-process))
       (error "Multi-processing is not supported for this system"))
@@ -112,13 +112,14 @@ a TCP connection to be opened via `open-network-stream'.  If there is already
 a running process in that buffer, it is not restarted.  Optional third arg
 STARTFILE is the name of a file to send the contents of the process to.
 
-If PROGRAM is a string, any more args are arguments to PROGRAM."
+If PROGRAM is a string, the remaining SWITCHES are arguments to PROGRAM."
   (apply #'scomint-make-in-buffer name nil program startfile switches))
 
 
 (defun scomint-exec (buffer name command startfile switches)
-  "Start up a process named NAME in buffer BUFFER for Comint modes.
-Runs the given COMMAND with SWITCHES with output to STARTFILE.
+  "In buffer BUFFER, start up a process named NAME for Comint modes.
+Runs the given COMMAND with output to STARTFILE.
+SWITCHES contains the arguments passed to the COMMAND.
 Blasts any old process running in the buffer.  Doesn't set the buffer mode.
 You can use this to cheaply run a series of processes in the same Comint
 buffer.  The hook `scomint-exec-hook' is run after each exec."
diff --git a/lib/span.el b/lib/span.el
index 2252d605..e7e3d68b 100644
--- a/lib/span.el
+++ b/lib/span.el
@@ -39,7 +39,7 @@
 (defalias 'span-buffer 'overlay-buffer)
 
 (defun span-p (ol)
-  "Check if an overlay belongs to PG."
+  "Check if an overlay OL belongs to PG."
   (overlay-get ol 'pg-span))
 
 (defun span-read-only-hook (overlay after start end &optional len)
@@ -119,7 +119,7 @@
 
 (defun span-mapcar-spans-inorder (fn start end prop)
   "Map function FN over spans between START and END with property PROP."
-  (mapcar fn 
+  (mapcar fn
 	  (sort (spans-at-region-prop start end prop)
 		'span-lt)))
 
@@ -165,7 +165,7 @@ A span is before PT if it begins before the character before PT."
 
 (defun span-string (span)
   (with-current-buffer (overlay-buffer span)
-    (buffer-substring-no-properties 
+    (buffer-substring-no-properties
      (overlay-start span) (overlay-end span))))
 
 (defun set-span-properties (span plist)
@@ -212,7 +212,8 @@ A span is before PT if it begins before the character before PT."
   (span-mapc-spans 'span-delete start end prop))
 
 (defun span-property-safe (span name)
-  "Like span-property, but return nil if SPAN is nil."
+  "Get the property of span SPAN with property name NAME.
+Like ‘span-property’, but return nil if SPAN is nil."
   (and span (span-property span name)))
 
 (defun span-set-start (span value)
diff --git a/lib/texi-docstring-magic.el b/lib/texi-docstring-magic.el
index 93896209..e39ee51a 100644
--- a/lib/texi-docstring-magic.el
+++ b/lib/texi-docstring-magic.el
@@ -96,7 +96,10 @@
   (require 'cl))
 
 (defun texi-docstring-magic-find-face (face)
-  ;; Compatibility between FSF Emacs and XEmacs
+  "Return non-nil if FACE is a face name; nil otherwise.
+A face name can be a string or a symbol.
+
+Compatibility between FSF Emacs and XEmacs."
   (or (facep face)
       (and (fboundp 'find-face) (find-face face))))
 
@@ -202,13 +205,14 @@ including any whitespace included to delimit matches.")
 
 (defun texi-docstring-magic-untabify (string)
   "Convert tabs in STRING into multiple spaces."
-  (with-temp-buffer 
+  (with-temp-buffer
     (insert string)
     (untabify (point-min) (point-max))
     (buffer-string)))
 
 (defun texi-docstring-magic-munge-docstring (docstring args)
   "Markup DOCSTRING for texi according to regexp matches."
+  ;; FIXME(EMD): seems buggy as ARGS is not used
   (let ((case-fold-search nil))
     (setq docstring (texi-docstring-magic-untabify docstring))
     (dolist (test texi-docstring-magic-munge-table)
@@ -261,7 +265,7 @@ including any whitespace included to delimit matches.")
 
 (defun texi-docstring-magic-format-default (default)
   "Make a default value string for the value DEFAULT.
-Markup as @code{stuff} or @lisp stuff @end lisp."
+Markup as @code{stuff} or @lisp stuff @end Lisp."
   ;; NB: might be nice to use a 'default-value-description
   ;; property here, in case the default value is computed.
   (let ((text       (format "%S" default)))
@@ -409,3 +413,7 @@ With prefix arg, no errors on unknown symbols.  (This results in
 
 
 (provide 'texi-docstring-magic)
+
+(provide 'texi-docstring-magic)
+
+;;; texi-docstring-magic.el ends here
diff --git a/lib/unicode-chars.el b/lib/unicode-chars.el
index 880371ce..2b854739 100644
--- a/lib/unicode-chars.el
+++ b/lib/unicode-chars.el
@@ -5063,7 +5063,7 @@
 (defun unicode-chars-list-chars ()
   "Insert each Unicode character into a buffer.
 Lets you see which characters are available for literal display
-in your emacs font."
+in your Emacs font."
   (interactive)
   (pop-to-buffer "*unicode-chars*")
   (let ((chars unicode-chars-alist)
@@ -5081,3 +5081,4 @@ in your emacs font."
 	    (insert (format " %s\n" name)))))))
 
 (provide 'unicode-chars)
+;;; unicode-chars.el ends here
diff --git a/lib/unicode-tokens.el b/lib/unicode-tokens.el
index e98ca0a2..4d1d0d35 100644
--- a/lib/unicode-tokens.el
+++ b/lib/unicode-tokens.el
@@ -67,6 +67,7 @@
   :group 'unicode-tokens-options)
 
 (defun unicode-tokens-toggle-add-help-echo ()
+  "Toggle option ‘unicode-tokens-add-help-echo’."
   (interactive)
   (customize-set-variable 'unicode-tokens-add-help-echo
 			  (not unicode-tokens-add-help-echo))
@@ -264,7 +265,7 @@ This is used for an approximate reverse mapping, see `unicode-tokens-paste'.")
 ;;
 (defconst unicode-tokens-font-family-alternatives
   '(("STIXGeneral"
-     "DejaVu Sans Mono" "DejaVuLGC Sans Mono" 
+     "DejaVu Sans Mono" "DejaVuLGC Sans Mono"
      "Lucida Grande" "Lucida Sans Unicode" "Apple Symbols")
     ("Script"
      "Lucida Calligraphy" "URW Chancery L" "Zapf Chancery")
@@ -869,7 +870,7 @@ Starts from point."
 	 (regexp-opt (mapcar 'car unicode-tokens-shortcut-replacement-alist))))
     ;; override the display of the regexp because it's huge!
     ;; (doesn't help with C-h: need way to programmatically show string)
-    (cl-flet ((query-replace-descr (str) 
+    (cl-flet ((query-replace-descr (str)
 				(if (eq str shortcut-regexp) "shortcut" str)))
       (perform-replace shortcut-regexp
 		       (cons 'unicode-tokens-replace-shortcut-match nil)
@@ -883,7 +884,7 @@ Starts from point."
 	       (format unicode-tokens-token-format token)))))
 
 (defun unicode-tokens-replace-unicode ()
-  "Query-replace unicode sequences in the buffer with tokens having same appearance.
+  "Query-replace unicode seq. in the buffer with tokens having same appearance.
 Starts from point."
   (interactive)
   (let ((uchar-regexp unicode-tokens-uchar-regexp))
@@ -972,7 +973,7 @@ Starts from point."
 (defalias 'unicode-tokens-list-unicode-chars 'unicode-chars-list-chars)
 
 (defun unicode-tokens-encode-in-temp-buffer (str fn)
-  "Call FN on encoded version of STR."
+  "Compute an encoded version of STR and call FN onto."
   (with-temp-buffer
     (insert str)
     (goto-char (point-min))