From ff30d22909194f818e5262537bcd045c4bf86e90 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Mon, 14 Nov 2022 02:15:19 +0100 Subject: [PATCH] Various checkdoc fixes --- lisp/use-package/bind-key.el | 8 +-- lisp/use-package/use-package-bind-key.el | 2 +- lisp/use-package/use-package-core.el | 56 ++++++++++--------- .../use-package-ensure-system-package.el | 4 +- lisp/use-package/use-package-ensure.el | 6 +- lisp/use-package/use-package-jump.el | 13 ++--- lisp/use-package/use-package-lint.el | 2 +- .../use-package/use-package-chords-tests.el | 2 +- 8 files changed, 47 insertions(+), 46 deletions(-) diff --git a/lisp/use-package/bind-key.el b/lisp/use-package/bind-key.el index cca5ad86187..1a84d6a9066 100644 --- a/lisp/use-package/bind-key.el +++ b/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. diff --git a/lisp/use-package/use-package-bind-key.el b/lisp/use-package/use-package-bind-key.el index 5ca2d016478..5e6a10925ca 100644 --- a/lisp/use-package/use-package-bind-key.el +++ b/lisp/use-package/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/lisp/use-package/use-package-core.el b/lisp/use-package/use-package-core.el index 7d7217d094b..5b001e496dd 100644 --- a/lisp/use-package/use-package-core.el +++ b/lisp/use-package/use-package-core.el @@ -63,11 +63,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 @@ -106,13 +106,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) @@ -132,9 +132,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) @@ -149,7 +149,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) @@ -196,9 +196,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). @@ -206,9 +206,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 @@ -293,7 +293,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) @@ -305,7 +305,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 @@ -316,7 +316,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) @@ -338,8 +338,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." @@ -365,14 +365,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))) @@ -738,8 +738,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) @@ -989,6 +989,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))) @@ -1031,7 +1033,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!) @@ -1055,7 +1057,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/lisp/use-package/use-package-ensure-system-package.el b/lisp/use-package/use-package-ensure-system-package.el index 8f1affadae0..c42996f9d2a 100644 --- a/lisp/use-package/use-package-ensure-system-package.el +++ b/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 diff --git a/lisp/use-package/use-package-ensure.el b/lisp/use-package/use-package-ensure.el index 78a7e8be1e2..a879c294dc3 100644 --- a/lisp/use-package/use-package-ensure.el +++ b/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 @@ -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/lisp/use-package/use-package-jump.el b/lisp/use-package/use-package-jump.el index 224d2e06b6e..6b9c02808e1 100644 --- a/lisp/use-package/use-package-jump.el +++ b/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)) diff --git a/lisp/use-package/use-package-lint.el b/lisp/use-package/use-package-lint.el index 49a47a9d32b..12974ab15e4 100644 --- a/lisp/use-package/use-package-lint.el +++ b/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) diff --git a/test/lisp/use-package/use-package-chords-tests.el b/test/lisp/use-package/use-package-chords-tests.el index 3c3dc4b4fe0..2b7588dd807 100644 --- a/test/lisp/use-package/use-package-chords-tests.el +++ b/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 -- 2.39.2