Merge pull request from skangas/checkdoc

GitHub-reference: https://github.com/jwiegley/use-package/issues/1015

lisp/use-package/bind-key.el

@@ -29,7 +29,7 @@
 
 ;; If you have lots of keybindings set in your .emacs file, it can be hard to
 ;; know which ones you haven't set yet, and which may now be overriding some
-;; new default in a new emacs version.  This module aims to solve that
+;; new default in a new Emacs version.  This module aims to solve that
 ;; problem.
 ;;
 ;; Bind keys as follows in your .emacs:
@@ -104,7 +104,7 @@
 (require 'easy-mmode)
 
 (defgroup bind-key nil
-  "A simple way to manage personal keybindings"
+  "A simple way to manage personal keybindings."
   :group 'emacs)
 
 (defcustom bind-key-column-widths '(18 . 40)
@@ -127,7 +127,7 @@
 ;; Create override-global-mode to force key remappings
 
 (defvar override-global-map (make-keymap)
-  "override-global-mode keymap")
+  "Keymap for `override-global-mode'.")
 
 (define-minor-mode override-global-mode
   "A minor mode so that keymap settings override other modes."
@@ -150,7 +150,7 @@ Elements have the form ((KEY . [MAP]) CMD ORIGINAL-CMD)")
 
 KEY-NAME may be a vector, in which case it is passed straight to
 `define-key'. Or it may be a string to be interpreted as
-spelled-out keystrokes, e.g., \"C-c C-z\". See documentation of
+spelled-out keystrokes, e.g., `C-c C-z'. See documentation of
 `edmacro-mode' for details.
 
 COMMAND must be an interactive function or lambda form.

lisp/use-package/use-package-core.el

@@ -70,11 +70,11 @@
   (require 'regexp-opt))
 
 (defgroup use-package nil
-  "A use-package declaration for simplifying your `.emacs'."
+  "A `use-package' declaration for simplifying your `.emacs'."
   :group 'startup)
 
 (defconst use-package-version "2.4.4"
-  "This version of use-package.")
+  "This version of `use-package'.")
 
 (defcustom use-package-keywords
   '(:disabled
@@ -115,11 +115,11 @@ The order of this list is *very important*, so it is only
 advisable to insert new keywords, never to delete or reorder
 them.  Further, attention should be paid to the NEWS.md if the
 default order ever changes, as they may have subtle effects on
-the semantics of use-package declarations and may necessitate
+the semantics of `use-package' declarations and may necessitate
 changing where you had inserted a new keyword earlier.
 
 Note that `:disabled' is special in this list, as it causes
-nothing at all to happen, even if the rest of the use-package
+nothing at all to happen, even if the rest of the `use-package'
 declaration is incorrect."
   :type '(repeat symbol)
   :group 'use-package)
@@ -139,9 +139,9 @@ otherwise requested."
   :group 'use-package)
 
 (defcustom use-package-ignore-unknown-keywords nil
-  "If non-nil, issue warning instead of error when unknown
-keyword is encountered. The unknown keyword and its associated
-arguments will be ignored in the `use-package' expansion."
+  "If non-nil, warn instead of signaling error for unknown keywords.
+The unknown keyword and its associated arguments will be ignored
+in the `use-package' expansion."
   :type 'boolean
   :group 'use-package)
 
@@ -204,7 +204,7 @@ The first element is the `use-package' keyword.
 
 The second is a form that can be evaluated to get the default
 value.  It can also be a function that will receive the name of
-the use-package declaration and the keyword plist given to
+the `use-package' declaration and the keyword plist given to
 `use-package', in normalized form.  The value it returns should
 also be in normalized form (which is sometimes *not* what one
 would normally write in a `use-package' declaration, so use
@@ -312,7 +312,7 @@ definitions, to understand the main intent of what's happening."
                       "\\s-+\\("))
            (or (bound-and-true-p lisp-mode-symbol-regexp)
                "\\(?:\\sw\\|\\s_\\|\\\\.\\)+") "\\)")
-  "Sexp providing regexp for finding use-package forms in user files.
+  "Sexp providing regexp for finding `use-package' forms in user files.
 This is used by `use-package-jump-to-package-form' and
 `use-package-enable-imenu-support'."
   :type 'sexp
@@ -323,7 +323,7 @@ This is used by `use-package-jump-to-package-form' and
 This is done by adjusting `lisp-imenu-generic-expression' to
 include support for finding `use-package' and `require' forms.
 
-Must be set before loading use-package."
+Must be set before loading `use-package'."
   :type 'boolean
   :set
   #'(lambda (sym value)
@@ -345,7 +345,7 @@ Must be set before loading use-package."
 (font-lock-add-keywords 'emacs-lisp-mode use-package-font-lock-keywords)
 
 (defcustom use-package-compute-statistics nil
-  "If non-nil, compute statistics concerned use-package declarations.
+  "If non-nil, compute statistics concerned `use-package' declarations.
 View the statistical report using `use-package-report'.  Note that
 if this option is enabled, you must require `use-package' in your
 user init file at loadup time, or you will see errors concerning
@@ -372,14 +372,14 @@ undefined variables."
   (and sym (symbolp sym)))
 
 (defsubst use-package-as-symbol (string-or-symbol)
-  "If STRING-OR-SYMBOL is already a symbol, return it.  Otherwise
-convert it to a symbol and return that."
+  "If STRING-OR-SYMBOL is already a symbol, return it.
+Otherwise convert it to a symbol and return that."
   (if (symbolp string-or-symbol) string-or-symbol
     (intern string-or-symbol)))
 
 (defsubst use-package-as-string (string-or-symbol)
-  "If STRING-OR-SYMBOL is already a string, return it.  Otherwise
-convert it to a string and return that."
+  "If STRING-OR-SYMBOL is already a string, return it.
+Otherwise convert it to a string and return that."
   (if (stringp string-or-symbol) string-or-symbol
     (symbol-name string-or-symbol)))
 
@@ -996,6 +996,8 @@ If RECURSED is non-nil, recurse into sublists."
 ;;
 
 (defun use-package-reset-statistics ()
+  "Reset statistics for `use-package'.
+See also `use-package-statistics'."
   (interactive)
   (setq use-package-statistics (make-hash-table)))
 
@@ -1038,7 +1040,7 @@ The information is formatted in a way suitable for
       (format "%.2f" (use-package-statistics-time statistics))))))
 
 (defun use-package-report ()
-  "Show current statistics gathered about use-package declarations.
+  "Show current statistics gathered about `use-package' declarations.
 In the table that's generated, the status field has the following
 meaning:
   Configured        :config has been processed (the package is loaded!)
@@ -1062,7 +1064,7 @@ meaning:
 
 (define-derived-mode use-package-statistics-mode tabulated-list-mode
   "use-package statistics"
-  "Show current statistics gathered about use-package declarations."
+  "Show current statistics gathered about `use-package' declarations."
   (setq tabulated-list-format
         ;; The sum of column width is 80 characters:
         [("Package" 25 t)

lisp/use-package/use-package-ensure-system-package.el

@@ -29,7 +29,7 @@
   "List of custom packages installed.")
 
 (defun use-package-ensure-system-package-consify (arg)
-  "Turn `arg' into a cons of (`package-name' . `install-command')."
+  "Turn ARG into a cons of (`package-name' . `install-command')."
   (cond
    ((stringp arg)
     (cons arg `(system-packages-install ,arg)))
@@ -54,7 +54,7 @@
 
 ;;;###autoload
 (defun use-package-normalize/:ensure-system-package (_name-symbol keyword args)
-  "Turn `arg' into a list of cons-es of (`package-name' . `install-command')."
+  "Turn ARGS into a list of conses of (`package-name' . `install-command')."
   (use-package-as-one (symbol-name keyword) args
     (lambda (_label arg)
       (cond

lisp/use-package/use-package-ensure.el

@@ -37,7 +37,7 @@
 (require 'use-package-core)
 
 (defgroup use-package-ensure nil
-  "Support for :ensure and :pin keywords in use-package declarations."
+  "Support for :ensure and :pin keywords in `use-package' declarations."
   :group 'use-package)
 
 (eval-when-compile
@@ -111,7 +111,7 @@ manually updated package."
         (archive-name   (if (stringp archive) archive (symbol-name archive))))
     (if (use-package-archive-exists-p archive-symbol)
         (add-to-list 'package-pinned-packages (cons package archive-name))
-      (error "Archive '%s' requested for package '%s' is not available."
+      (error "Archive '%s' requested for package '%s' is not available"
              archive-name package))
     (unless (bound-and-true-p package--initialized)
       (package-initialize t))))

lisp/use-package/use-package-jump.el

@@ -30,8 +30,8 @@
 
 ;; Provides the command `M-x use-package-jump-to-package-form', however it
 ;; only works if the package being jumped to was required during
-;; initialization. If it was delay-loaded, it will not work. Improvements are
-;; needed.
+;; initialization.  If it was delay-loaded, it will not work.
+;; Improvements are needed.
 
 ;;; Code:
 
@@ -48,11 +48,10 @@ Returns an absolute file path or nil if none is found."
 
 ;;;###autoload
 (defun use-package-jump-to-package-form (package)
-  "Attempt to find and jump to the `use-package' form that loaded
-PACKAGE. This will only find the form if that form actually
-required PACKAGE. If PACKAGE was previously required then this
-function will jump to the file that originally required PACKAGE
-instead."
+  "Attempt to find and jump to the `use-package' form that loaded PACKAGE.
+This will only find the form if that form actually required
+PACKAGE.  If PACKAGE was previously required then this function
+will jump to the file that originally required PACKAGE instead."
   (interactive (list (completing-read "Package: " features)))
   (let* ((package (if (stringp package) (intern package) package))
          (requiring-file (use-package-find-require package))

lisp/use-package/use-package-lint.el

@@ -63,7 +63,7 @@
 
 ;;;###autoload
 (defun use-package-lint ()
-  "Check for errors in use-package declarations.
+  "Check for errors in `use-package' declarations.
 For example, if the module's `:if' condition is met, but even
 with the specified `:load-path' the module cannot be found."
   (interactive)

test/lisp/use-package/use-package-chords-tests.el

@@ -158,4 +158,4 @@
 ;; no-update-autoloads: t
 ;; End:
 
-;;; use-package-tests.el ends here
+;;; use-package-chords-tests.el ends here