[nongnu] elpa/cdlatex 0eb638546c 37/49: Fix checkdoc issues

[ELPA Syncer]

branch: elpa/cdlatex
commit 0eb638546c1ba94faaa0de7849c87759e3b6aa07
Author: Philip Kaludercic <philipk@posteo.net>
Commit: Philip Kaludercic <philipk@posteo.net>

    Fix checkdoc issues
---
 cdlatex.el | 127 +++++++++++++++++++++++++++++++++++--------------------------
 1 file changed, 73 insertions(+), 54 deletions(-)

diff --git a/cdlatex.el b/cdlatex.el
index ca25770946..2bea2391ac 100644
--- a/cdlatex.el
+++ b/cdlatex.el
@@ -436,8 +436,8 @@ indicating the label types for which it should be true."
 
 (defcustom cdlatex-math-symbol-prefix ?`
   "Prefix key for `cdlatex-math-symbol'.
-This may be a character, a string readable with read-kbd-macro, or a
-lisp vector."
+This may be a character, a string readable with `read-kbd-macro', or a
+Lisp vector."
   :group 'cdlatex-math-support
   :type '(choice
           (character)
@@ -450,8 +450,8 @@ This is a list of key binding descriptions for different 
levels of
 math symbols.  First entry for level 1 etc.
 Each entry consists of a prefix key and a list of modifiers for the
 character.  The prefix key can be nil, or any of a character, a
-read-kbd-macro readable string or a vector.
-Examples: 
+`read-kbd-macro' readable string or a vector.
+Examples:
 `((nil alt))'                   bind `\\delta' to `A-d'.
 `((\"C-c C-f\"))'               bind `\\delta' to `C-c C-f d'.
 `((nil alt) (nil alt control))' bind `\\delta' to `A-d' and
@@ -495,7 +495,7 @@ functions and opperators."
 (defcustom cdlatex-math-modify-prefix ?'
   "Prefix key for `cdlatex-math-modify'.
 It can be a character, a string interpretable with `read-kbd-macro',
-or a lisp vector."
+or a Lisp vector."
   :group 'cdlatex-math-support
   :type '(choice
           (character)
@@ -505,7 +505,7 @@ or a lisp vector."
 (defcustom cdlatex-modify-backwards t
   "*Non-nil means, `cdlatex-math-modify' modifies char before point.
 Nil means, always insert only an empty modification form.  This is also
-the case if the character before point is white or some punctuation. "
+the case if the character before point is white or some punctuation."
   :group 'cdlatex-math-support
   :type 'boolean)
 
@@ -599,7 +599,7 @@ When nil, `_' and `^' will just self-insert."
 
 (defcustom cdlatex-auto-help-delay 1.5
   "Number of idle seconds before display of auto-help.
-When executing cdlatex-math-symbol or cdlatex-math-modify, display
+When executing `cdlatex-math-symbol' or `cdlatex-math-modify', display
 automatic help when idle for more than this amount of time."
   :group 'cdlatex-miscellaneous-configurations
   :type 'number)
@@ -635,38 +635,52 @@ automatic help when idle for more than this amount of 
time."
 
 ;;;###autoload
 (defun cdlatex-mode (&optional arg)
-  "Minor mode for editing scientific LaTeX documents.  Here is a
-list of features: \\<cdlatex-mode-map>
+  "Minor mode for editing scientific LaTeX documents.
+
+Here is a list of features: \\<cdlatex-mode-map>
 
                            KEYWORD COMMANDS
                            ----------------
-Many CDLaTeX commands are activated with an abbrev-like mechanism.
-When a keyword is typed followed `\\[cdlatex-tab]', the keyword is deleted
-from the buffer and a command is executed.  You can get a full list
-of these commands with `\\[cdlatex-command-help]'.
-For example, when you type `fr<TAB>', CDLaTeX will insert `\\frac{}{}'.
 
-When inserting templates like '\\frac{}{}', the cursor is positioned
-properly.  Use `\\[cdlatex-tab]' to move through templates.  `\\[cdlatex-tab]' 
also kills
-unnecessary braces around subscripts and superscripts at point.
+Many CDLaTeX commands are activated with an abbrev-like
+mechanism.  When a keyword is typed followed \\[cdlatex-tab], the
+keyword is deleted from the buffer and a command is executed.
+You can get a full list of these commands with
+\\[cdlatex-command-help].  For example, when you type `fr<TAB>',
+CDLaTeX will insert \\frac{}{}.
+
+When inserting templates like '\\frac{}{}', the cursor is
+positioned properly.  Use \\[cdlatex-tab] to move through
+templates.  \\[cdlatex-tab] also kills unnecessary braces around
+subscripts and superscripts at point.
 
                      MATH CHARACTERS AND ACCENTS
                      ---------------------------
-\\[cdlatex-math-symbol]  followed by any character inserts a LaTeX math 
character
-      e.g. \\[cdlatex-math-symbol]e   => \\epsilon
-\\[cdlatex-math-symbol]\\[cdlatex-math-symbol] followed by any character 
inserts other LaTeX math character
-      e.g. \\[cdlatex-math-symbol]\\[cdlatex-math-symbol]e  => \\varepsilon
-\\[cdlatex-math-modify]  followed by character puts a math accent on a letter 
or symbol
-      e.g. \\[cdlatex-math-symbol]a\\[cdlatex-math-modify]~ => \\tilde{\\alpha}
 
-CDLaTeX is aware of the math environments in LaTeX and modifies the
-workings of some functions according to the current status.
+\\[cdlatex-math-symbol] followed by any character inserts a LaTeX
+math character
+      e.g. \\[cdlatex-math-symbol]e
+        => \\epsilon
+
+\\[cdlatex-math-symbol]\\[cdlatex-math-symbol] followed by any
+character inserts other LaTeX math character
+      e.g. \\[cdlatex-math-symbol]\\[cdlatex-math-symbol]e
+        => \\varepsilon
+\\[cdlatex-math-modify]  followed by character puts a math
+accent on a letter or symbol
+      e.g. \\[cdlatex-math-symbol]a\\[cdlatex-math-modify]~
+        => \\tilde{\\alpha}
+
+CDLaTeX is aware of the math environments in LaTeX and modifies
+the workings of some functions according to the current status.
 
                              ONLINE HELP
                              -----------
-After pressing \\[cdlatex-math-symbol] or \\[cdlatex-math-modify], CDLaTeX 
waits for a short time for the second character.
-If that does not come, it will pop up a window displaying the available
-characters and their meanings.
+
+After pressing \\[cdlatex-math-symbol] or
+\\[cdlatex-math-modify], CDLaTeX waits for a short time for the
+second character.  If that does not come, it will pop up a window
+displaying the available characters and their meanings.
 
                              KEY BINDINGS
                              ------------
@@ -674,8 +688,6 @@ characters and their meanings.
 
 Under X, many functions will be available also in a menu on the menu bar.
 
-Entering cdlatex-mode calls the hook cdlatex-mode-hook.
-------------------------------------------------------------------------------"
 
   (interactive "P")
   (setq cdlatex-mode (not (or (and (null arg) cdlatex-mode)
@@ -698,13 +710,17 @@ Entering cdlatex-mode calls the hook cdlatex-mode-hook.
           (cons (cons 'cdlatex-mode cdlatex-mode-map)
                 minor-mode-map-alist)))
 
+Entering `cdlatex-mode' calls the hook cdlatex-mode-hook."
 
 ;;; ===========================================================================
 ;;;
 ;;; Functions that check out the surroundings
 
 (defun cdlatex-dollars-balanced-to-here (&optional from)
-  ;; Return t if the dollars are balanced between start of paragraph and point.
+  "Non-nil if the dollars are balanced between start of paragraph and point.
+Unless the optional argument FROM specifies the position from
+where to check for balance, the beginning of the current
+paragraph is used."
   (save-excursion
     (let ((answer t) (pos (point)))
       (if from
@@ -717,7 +733,7 @@ Entering cdlatex-mode calls the hook cdlatex-mode-hook.
       (setq answer answer))))
 
 (defun cdlatex-number-of-backslashes-is-odd ()
-  ;; Count backslashes before point and return t if number is odd.
+  "Count backslashes before point and return t if number is odd."
   (let ((odd nil))
     (save-excursion
       (while (equal (preceding-char) ?\\)
@@ -731,6 +747,7 @@ Entering cdlatex-mode calls the hook cdlatex-mode-hook.
 ;; Some generally useful functions
 
 (defun cdlatex-get-kbd-vector (obj)
+  "Ensure OBJ can be used as a keybinding."
   (cond ((vectorp obj) obj)
         ((integerp obj) (vector obj))
         ((stringp obj) (read-kbd-macro obj))
@@ -739,8 +756,8 @@ Entering cdlatex-mode calls the hook cdlatex-mode-hook.
         (t nil)))
 
 (defun cdlatex-uniquify (alist &optional keep-list)
-  ;; Return a list of all elements in ALIST, but each car only once.
-  ;; Elements of KEEP-LIST are not removed even if duplicate.
+  "Return a list of all elements in ALIST, but each car only once.
+Elements of KEEP-LIST are not removed even if duplicate."
   (let (new elm)
     (while alist
       (setq elm (car alist)
@@ -752,7 +769,7 @@ Entering cdlatex-mode calls the hook cdlatex-mode-hook.
     new))
 
 (defun cdlatex-use-fonts ()
-  ;; Return t if we can and want to use fonts.
+  "Return t if we can and want to use fonts."
   (and window-system
        cdlatex-use-fonts
        (boundp 'font-lock-keyword-face)))
@@ -779,7 +796,7 @@ Entering cdlatex-mode calls the hook cdlatex-mode-hook.
       (insert paren))))
 
 (defun cdlatex-ensure-math ()
-  ;; Make sure we are in math
+  "Make sure we are in math mode."
   (unless (texmathp)
     (if cdlatex-use-dollar-to-ensure-math
         (cdlatex-dollar)
@@ -788,7 +805,7 @@ Entering cdlatex-mode calls the hook cdlatex-mode-hook.
 
 (defun cdlatex-dollar (&optional arg)
   "Insert a pair of dollars unless number of backslashes before point is odd.
-With arg, insert pair of double dollars."
+With ARG, insert pair of double dollars."
   (interactive "P")
   (if (cdlatex-number-of-backslashes-is-odd)
       (insert "$")
@@ -877,8 +894,8 @@ expect that more input can be put in.
 To do that, the cursor is moved according to the following rules:
 
 The cursor stops...
-- before closing brackets if preceding-char is any of -({[]})
-- after  closing brackets, but not if following-char is any of ({[_^
+- before closing brackets if `preceding-char' is any of -({[]})
+- after  closing brackets, but not if `following-char' is any of ({[_^
 - just after $, if the cursor was before that $.
 - at end of non-empty lines
 - at the beginning of empty lines
@@ -966,7 +983,8 @@ Sounds strange?  Try it out!"
               (throw 'stop t))))))))
 
 (defun cdlatex-command-help (&optional arg)
-  "Show the available cdlatex commands in the help buffer."
+  "Show the available cdlatex commands in the help buffer.
+With a non-nil ARG, or a prefix argument, run texdoc instead."
   (interactive "P")
   (if arg
       (call-interactively 'TeX-documentation-texdoc)
@@ -994,7 +1012,7 @@ Sounds strange?  Try it out!"
 ;;; Cursor position after insertion of forms
 
 (defun cdlatex-position-cursor ()
-  ;; Search back to question mark, delete it, leave point there
+  "Search back to question mark, delete it, leave point there."
   (if (search-backward "\?" (- (point) 100) t)
       (delete-char 1)))
 
@@ -1101,7 +1119,7 @@ add two backslashes to the previous line if required."
     (cdlatex-environment env t)))
 
 (defun cdlatex-comment-at-point ()
-  ;; Return t if point is inside a TeX comment
+  "Return t if point is inside a TeX comment."
   (let ((end (point))
         (start (progn (beginning-of-line 1) (point))))
     (goto-char end)
@@ -1353,7 +1371,7 @@ constant `cdlatex-math-modify-alist'."
 ;;; And here is the help function for the symbol insertions stuff
 
 (defun cdlatex-turn-on-help (header level alist offset &optional sparse)
-  ;; Show help-window for alist
+  "Show help-window for ALIST."
   (let ((cnt 0) (all-chars "")
         (flock (cdlatex-use-fonts)) this-char value)
     (if sparse
@@ -1526,7 +1544,7 @@ zZ
     ("qqq"        "Insert \\qquad"
      "\\qquad"       nil nil t t)
     )
-  "Default for cdlatex-command-alist.")
+  "Default for `cdlatex-command-alist'.")
 
 (defconst cdlatex-math-modify-alist-default
   '(
@@ -1560,7 +1578,7 @@ zZ
     ( ?2    "\\scriptstyle"       nil        nil nil nil )
     ( ?3    "\\scriptscriptstyle" nil        nil nil nil )
     )
-  "Default for cdlatex-math-modify-alist.")
+  "Default for `cdlatex-math-modify-alist'.")
 
 (defconst cdlatex-math-symbol-alist-default
   '(
@@ -1657,8 +1675,7 @@ zZ
     ( ?'  ("\\prime"          ))
     ( ?.  ("\\cdot"           ))
     )
-  "Default for cdlatex-math-symbol-alist."
-  )
+  "Default for `cdlatex-math-symbol-alist'.")
 
 ;;; ---------------------------------------------------------------------------
 
@@ -2091,17 +2108,18 @@ nil
 ;;; Functions to compile the tables, reset the mode etc.
 
 (defun cdlatex-reset-mode ()
-  "Reset CDLaTeX Mode.  Required to implement changes to some list variables.
-This function will compile the information in `cdlatex-label-alist' and similar
-variables.  It is called when CDLaTeX is first used, and after changes to
-these variables via `cdlatex-add-to-label-alist'."
+  "Reset CDLaTeX Mode.
+Required to implement changes to some list variables.  This
+function will compile the information in `cdlatex-label-alist'
+and similar variables.  It is called when CDLaTeX is first used,
+and after changes to these variables via
+`cdlatex-add-to-label-alist'."
   (interactive)
   (cdlatex-compute-tables))
 
 
 (defun cdlatex-compute-tables ()
-  ;; Update tables not connected with ref and cite support
-
+  "Update tables not connected with ref and cite support."
   (setq cdlatex-env-alist-comb
         (cdlatex-uniquify
          (append cdlatex-env-alist
@@ -2168,6 +2186,7 @@ these variables via `cdlatex-add-to-label-alist'."
     (put 'cdlatex-math-symbol-alist-comb 'cdlatex-bindings bindings)))
 
 (defun cdlatex-insert-math (string)
+  "Insert STRING in math-mode."
   (cdlatex-ensure-math)
   (insert string)
   (if (string-match "\\?" string)
@@ -2209,7 +2228,7 @@ these variables via `cdlatex-add-to-label-alist'."
 
 (easy-menu-define
  cdlatex-mode-menu cdlatex-mode-map
- "Menu used in CDLaTeX mode"
+ "Menu used in CDLaTeX mode."
  '("CDLTX"
    ["\\begin{...} \\label"   cdlatex-environment t]
    ["\\item \\label"         cdlatex-item t]