Fix checkdoc warnings

Author: xiongtx

clojure-mode.el

@@ -185,7 +185,7 @@ For example, \[ is allowed in :db/id[:db.part/user]."
 
 (defcustom clojure-build-tool-files '("project.clj" "build.boot" "build.gradle")
   "A list of files, which identify a Clojure project's root.
-Out-of-the box clojure-mode understands lein, boot and gradle."
+Out-of-the box `clojure-mode' understands lein, boot and gradle."
   :type '(repeat string)
   :package-version '(clojure-mode . "5.0.0")
   :safe (lambda (value)
@@ -317,7 +317,7 @@ CIDER provides a more complex version which does classpath analysis.")
   (message "clojure-mode (version %s)" clojure-mode-version))
 
 (defconst clojure-mode-report-bug-url "https://github.com/clojure-emacs/clojure-mode/issues/new"
-  "The URL to report a clojure-mode issue.")
+  "The URL to report a `clojure-mode' issue.")
 
 (defun clojure-mode-report-bug ()
   "Report a bug in your default browser."
@@ -458,7 +458,14 @@ ENDP and DELIMITER."
 (declare-function paredit-convolute-sexp "ext:paredit")
 
 (defun clojure--replace-let-bindings-and-indent (orig-fun &rest args)
-  "Advise `paredit-convolute-sexp' to replace s-expressions with their bound name if a let form was convoluted."
+  "Advise ORIG-FUN to replace let bindings.
+
+Sexps are replace by their bound name if a let form was
+convoluted.
+
+ORIG-FUN should be `paredit-convolute-sexp'.
+
+ARGS are passed to ORIG-FUN, as with all advice."
   (save-excursion
     (backward-sexp)
     (when (looking-back clojure--let-regexp)
@@ -520,13 +527,14 @@ replacement for `cljr-expand-let`."
   (add-hook 'paredit-mode-hook #'clojure-paredit-setup))
 
 (defcustom clojure-verify-major-mode t
-  "If non-nil, warn when activating the wrong major-mode."
+  "If non-nil, warn when activating the wrong `major-mode'."
   :type 'boolean
   :safe #'booleanp
   :package-version '(clojure-mode "5.3.0"))
 
 (defun clojure--check-wrong-major-mode ()
-  "Check if the current major-mode matches the file extension.
+  "Check if the current `major-mode' matches the file extension.
+
 If it doesn't, issue a warning if `clojure-verify-major-mode' is
 non-nil."
   (when (and clojure-verify-major-mode
@@ -1107,8 +1115,11 @@ Place point as in `clojure--position-for-alignment'."
 
 (defun clojure--search-whitespace-after-next-sexp (&optional bound _noerror)
   "Move point after all whitespace after the next sexp.
+
 Set the match data group 1 to be this region of whitespace and
-return point."
+return point.
+
+BOUND is bounds the whitespace search."
   (unwind-protect
       (ignore-errors
         (clojure-forward-logical-sexp 1)
@@ -1835,6 +1846,9 @@ list of (fn args) to pass to `apply''"
     (insert "\n")))
 
 (defun clojure--unwind-last ()
+  "Unwind a thread last macro once.
+
+Point must be between the opening paren and the ->> symbol."
   (forward-sexp)
   (save-excursion
     (let ((beg (point))
@@ -1857,13 +1871,15 @@ list of (fn args) to pass to `apply''"
   (forward-char))
 
 (defun clojure--ensure-parens-around-function-names ()
+  "Insert parens around function names if necessary."
   (clojure--looking-at-non-logical-sexp)
   (unless (looking-at "(")
     (insert-parentheses 1)
     (backward-up-list)))
 
 (defun clojure--unwind-first ()
   "Unwind a thread first macro once.
+
 Point must be between the opening paren and the -> symbol."
   (forward-sexp)
   (save-excursion
@@ -1879,12 +1895,14 @@ Point must be between the opening paren and the -> symbol."
   (forward-char))
 
 (defun clojure--pop-out-of-threading ()
+  "Raise a sexp up a level to unwind a threading form."
   (save-excursion
     (down-list 2)
     (backward-up-list)
     (raise-sexp)))
 
 (defun clojure--nothing-more-to-unwind ()
+  "Return non-nil if a threaded form cannot be unwound further."
   (save-excursion
     (let ((beg (point)))
       (forward-sexp)
@@ -1895,6 +1913,10 @@ Point must be between the opening paren and the -> symbol."
       (= beg (point)))))
 
 (defun clojure--fix-sexp-whitespace (&optional move-out)
+  "Fix whitespace after unwinding a threading form.
+
+Optional argument MOVE-OUT, if non-nil, means moves up a list
+before fixing whitespace."
   (save-excursion
     (when move-out (backward-up-list))
     (let ((sexp (bounds-of-thing-at-point 'sexp)))
@@ -1933,10 +1955,12 @@ Return nil if there are no more levels to unwind."
   (while (clojure-unwind)))
 
 (defun clojure--remove-superfluous-parens ()
+  "Remove extra parens from a form."
   (when (looking-at "([^ )]+)")
     (delete-pair)))
 
 (defun clojure--thread-first ()
+  "Thread a nested sexp using ->."
   (down-list)
   (forward-symbol 1)
   (unless (looking-at ")")
@@ -1954,6 +1978,7 @@ Return nil if there are no more levels to unwind."
       t)))
 
 (defun clojure--thread-last ()
+  "Thread a nested sexp using ->>."
   (forward-sexp 2)
   (down-list -1)
   (backward-sexp)
@@ -1972,6 +1997,7 @@ Return nil if there are no more levels to unwind."
       t)))
 
 (defun clojure--threadable-p ()
+  "Return non-nil if a form can be threaded."
   (save-excursion
     (forward-symbol 1)
     (looking-at "[\n\r\t ]*(")))
@@ -1993,6 +2019,12 @@ Return nil if there are no more levels to unwind."
       (clojure--fix-sexp-whitespace 'move-out))))
 
 (defun clojure--thread-all (first-or-last-thread but-last)
+  "Fully thread the form at point.
+
+FIRST-OR-LAST-THREAD is \"->\" or \"->>\".
+
+When BUT-LAST is non-nil, the last expression is not threaded.
+Default value is `clojure-thread-all-but-last'."
   (save-excursion
     (insert-parentheses 1)
     (insert first-or-last-thread))
@@ -2003,14 +2035,18 @@ Return nil if there are no more levels to unwind."
 ;;;###autoload
 (defun clojure-thread-first-all (but-last)
   "Fully thread the form at point using ->.
-When BUT-LAST is passed the last expression is not threaded."
+
+When BUT-LAST is non-nil, the last expression is not threaded.
+Default value is `clojure-thread-all-but-last'."
   (interactive "P")
   (clojure--thread-all "-> " but-last))
 
 ;;;###autoload
 (defun clojure-thread-last-all (but-last)
   "Fully thread the form at point using ->>.
-When BUT-LAST is passed the last expression is not threaded."
+
+When BUT-LAST is non-nil, the last expression is not threaded.
+Default value is `clojure-thread-all-but-last'."
   (interactive "P")
   (clojure--thread-all "->> " but-last))
 
@@ -2161,9 +2197,13 @@ See: https://github.com/clojure-emacs/clj-refactor.el/wiki/cljr-cycle-if"
 
 (defvar clojure--let-regexp
   "\(\\(when-let\\|if-let\\|let\\)\\(\\s-*\\|\\[\\)"
-  "Regexp matching let like expressions, i.e. let, when-let, if-let.
+  "Regexp matching let like expressions, i.e. \"let\", \"when-let\", \"if-let\".
+
+The first match-group is the let expression.
 
-The first match-group is the let expression, the second match-group is the whitespace or the opening square bracket if no whitespace between the let expression and the bracket.")
+The second match-group is the whitespace or the opening square
+bracket if no whitespace between the let expression and the
+bracket.")
 
 (defun clojure--goto-let ()
   "Go to the beginning of the nearest let form."
@@ -2177,6 +2217,7 @@ The first match-group is the let expression, the second match-group is the white
   (looking-at clojure--let-regexp))
 
 (defun clojure--inside-let-binding-p ()
+  "Return non-nil if point is inside a let binding."
   (ignore-errors
     (save-excursion
       (let ((pos (point)))
@@ -2225,12 +2266,18 @@ Assume that point is in the binding form of a let."
       (newline-and-indent))))
 
 (defun clojure--sexp-regexp (sexp)
+  "Return a regexp for matching SEXP."
   (concat "\\([^[:word:]^-]\\)"
           (mapconcat #'identity (mapcar 'regexp-quote (split-string sexp))
                      "[[:space:]\n\r]+")
           "\\([^[:word:]^-]\\)"))
 
 (defun clojure--replace-sexp-with-binding (bound-name init-expr)
+  "Replace a binding with its bound name in the let form.
+
+BOUND-NAME is the name (left-hand side) of a binding.
+
+INIT-EXPR is the value (right-hand side) of a binding."
   (save-excursion
     (while (re-search-forward
             (clojure--sexp-regexp init-expr)
@@ -2240,6 +2287,7 @@ Assume that point is in the binding form of a let."
 
 (defun clojure--replace-sexps-with-bindings (bindings)
   "Replace bindings with their respective bound names in the let form.
+
 BINDINGS is the list of bound names and init expressions."
   (let ((bound-name (pop bindings))
         (init-expr (pop bindings)))
@@ -2248,6 +2296,7 @@ BINDINGS is the list of bound names and init expressions."
       (clojure--replace-sexps-with-bindings bindings))))
 
 (defun clojure--replace-sexps-with-bindings-and-indent ()
+  "Replace sexps with bindings."
   (clojure--replace-sexps-with-bindings
    (clojure--read-let-bindings))
   (clojure-indent-region
@@ -2277,6 +2326,10 @@ Return a list: odd elements are bound names, even elements init expressions."
     (nreverse bindings)))
 
 (defun clojure--introduce-let-internal (name &optional n)
+  "Create a let form, binding the form at point with NAME.
+
+Optional numeric argument N, if non-nil, introduces the let N
+lists up."
   (if (numberp n)
       (let ((init-expr-sexp (clojure-delete-and-extract-sexp)))
         (insert name)
@@ -2299,6 +2352,7 @@ Return a list: odd elements are bound names, even elements init expressions."
     (insert name)))
 
 (defun clojure--move-to-let-internal (name)
+  "Bind the form at point to NAME in the nearest let."
   (if (not (save-excursion (clojure--goto-let)))
       (clojure--introduce-let-internal name)
     (let ((contents (clojure-delete-and-extract-sexp)))