From 86d22428959a0f5aecef270e0f4dd7d4b5712fc3 Mon Sep 17 00:00:00 2001 From: Erik Martin-Dorel Date: Thu, 23 Aug 2018 00:01:12 +0200 Subject: Fix most doc issues raised by (checkdoc) --- lib/bufhist.el | 12 ++++++---- lib/holes.el | 55 ++++++++++++++++++++++++--------------------- lib/local-vars-list.el | 15 ++++++++----- lib/maths-menu.el | 2 +- lib/pg-dev.el | 10 ++++----- lib/proof-compat.el | 3 +-- lib/scomint.el | 9 ++++---- lib/span.el | 9 ++++---- lib/texi-docstring-magic.el | 14 +++++++++--- lib/unicode-chars.el | 3 ++- lib/unicode-tokens.el | 9 ++++---- 11 files changed, 82 insertions(+), 59 deletions(-) (limited to 'lib') 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)) -- cgit v1.2.3