[elpa] externals/bind-key 87c03dffc7 13/13: Merge pull request #1015 from skangas/checkdoc

[ELPA Syncer]

branch: externals/bind-key
commit 87c03dffc79e7980468231a797c412d88aed9bc7
Merge: d9b136d420 362788164a
Author: John Wiegley <johnw@newartisans.com>
Commit: GitHub <noreply@github.com>

    Merge pull request #1015 from skangas/checkdoc
---
 bind-key.el                          |  8 +++---
 use-package-bind-key.el              |  2 +-
 use-package-chords-tests.el          |  2 +-
 use-package-core.el                  | 56 +++++++++++++++++++-----------------
 use-package-ensure-system-package.el |  4 +--
 use-package-ensure.el                |  6 ++--
 use-package-jump.el                  | 13 ++++-----
 use-package-lint.el                  |  2 +-
 8 files changed, 47 insertions(+), 46 deletions(-)

diff --git a/bind-key.el b/bind-key.el
index 567ef9e4e8..f0b9cdb588 100644
--- a/bind-key.el
+++ b/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.
diff --git a/use-package-bind-key.el b/use-package-bind-key.el
index 5ca2d01647..5e6a10925c 100644
--- a/use-package-bind-key.el
+++ b/use-package-bind-key.el
@@ -29,7 +29,7 @@
 ;;; Commentary:
 
 ;; Provides support for the :bind, :bind*, :bind-keymap and :bind-keymap*
-;; keywords. Note that these are currently still baked into
+;; keywords.  Note that these are currently still baked into
 ;; `use-package-keywords' and `use-package-deferring-keywords', although this
 ;; is harmless if they are never used.
 
diff --git a/use-package-chords-tests.el b/use-package-chords-tests.el
index 3c3dc4b4fe..2b7588dd80 100644
--- a/use-package-chords-tests.el
+++ b/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
diff --git a/use-package-core.el b/use-package-core.el
index 43106b7234..429b108ac7 100644
--- a/use-package-core.el
+++ b/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
@@ -113,13 +113,13 @@
   "The set of valid keywords, in the order they are processed in.
 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
+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)
 
@@ -156,7 +156,7 @@ call)."
   "Whether to report about loading and configuration details.
 If you customize this, then you should require the `use-package'
 feature in files that use `use-package', even if these files only
-contain compiled expansions of the macros. If you don't do so,
+contain compiled expansions of the macros.  If you don't do so,
 then the expanded macros do their job silently."
   :type '(choice (const :tag "Quiet, without catching errors" errors)
                  (const :tag "Quiet" nil)
@@ -203,9 +203,9 @@ Each entry in the alist is a list of three elements:
 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
-`use-package', in normalized form. The value it returns should
+value.  It can also be a function that will receive the name of
+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
 caution).
@@ -213,9 +213,9 @@ caution).
 The third element is a form that can be evaluated to determine
 whether or not to assign a default value; if it evaluates to nil,
 then the default value is not assigned even if the keyword is not
-present in the `use-package' form. This third element may also be
+present in the `use-package' form.  This third element may also be
 a function, in which case it receives the name of the package (as
-a symbol) and a list of keywords (in normalized form). It should
+a symbol) and a list of keywords (in normalized form).  It should
 return nil or non-nil depending on whether defaulting should be
 attempted."
   :type `(repeat
@@ -300,7 +300,7 @@ This disables:
 
 The main advantage to this variable is that, if you know your
 configuration works, it will make the byte-compiled file as
-minimal as possible. It can also help with reading macro-expanded
+minimal as possible.  It can also help with reading macro-expanded
 definitions, to understand the main intent of what's happening."
   :type 'boolean
   :group 'use-package)
@@ -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,8 +345,8 @@ 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.
-View the statistical report using `use-package-report'. Note that
+  "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
 undefined variables."
@@ -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)))
 
@@ -745,8 +745,8 @@ one.
 If AFTER is non-nil, insert KEYWORD either at the end of the
 keywords list, or after the ANCHOR if one has been provided.
 If TEST is non-nil, it is the test used to compare ELEM to list
-elements. The default is `eq'.
-The modified list is returned. The original list is not modified."
+elements.  The default is `eq'.
+The modified list is returned.  The original list is not modified."
   (let (result)
     (dolist (k xs)
       (if (funcall (or test #'eq) k anchor)
@@ -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)
diff --git a/use-package-ensure-system-package.el 
b/use-package-ensure-system-package.el
index 8f1affadae..c42996f9d2 100644
--- a/use-package-ensure-system-package.el
+++ b/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
diff --git a/use-package-ensure.el b/use-package-ensure.el
index 78a7e8be1e..a879c294dc 100644
--- a/use-package-ensure.el
+++ b/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
@@ -64,7 +64,7 @@ to all `:ensure' keywords (always a list, even if only one); 
and
 the current `state' plist created by previous handlers.
 
 Note that this function is called whenever `:ensure' is provided,
-even if it is nil. It is up to the function to decide on the
+even if it is nil.  It is up to the function to decide on the
 semantics of the various values for `:ensure'.
 
 This function should return non-nil if the package is installed.
@@ -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))))
diff --git a/use-package-jump.el b/use-package-jump.el
index 224d2e06b6..6b9c02808e 100644
--- a/use-package-jump.el
+++ b/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))
diff --git a/use-package-lint.el b/use-package-lint.el
index 49a47a9d32..12974ab15e 100644
--- a/use-package-lint.el
+++ b/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)