[nongnu] elpa/engine-mode 6df818c67a 2/8: Resolve documentation-related linting errors

[ELPA Syncer]

branch: elpa/engine-mode
commit 6df818c67a173e9c97eb5f2a598a52566864cff6
Author: Harry R. Schwartz <hello@harryrschwartz.com>
Commit: Harry R. Schwartz <hello@harryrschwartz.com>

    Resolve documentation-related linting errors
    
    - Modify text wrap width in commentary section
    - Fix some `checkdoc` errors: shorten longer lines, use ALL-CAPS for 
variables
      in docstrings
    - Condense package summary to remove explicit reference to Emacs (of 
*course*
      this is for Emacs)
---
 engine-mode.el | 94 +++++++++++++++++++++++++++++++++-------------------------
 1 file changed, 54 insertions(+), 40 deletions(-)

diff --git a/engine-mode.el b/engine-mode.el
index 5945d6db8a..734d0a2e25 100644
--- a/engine-mode.el
+++ b/engine-mode.el
@@ -1,4 +1,4 @@
-;;; engine-mode.el --- Define and query search engines from within Emacs
+;;; engine-mode.el --- Define and query search engines
 
 ;; Author: Harry R. Schwartz <hello@harryrschwartz.com>
 ;; Version: 2.2.3
@@ -7,34 +7,33 @@
 
 ;; This file is NOT part of GNU Emacs.
 
-;; This program is free software: you can redistribute it and/or modify
-;; it under the terms of the GNU General Public License as published by
-;; the Free Software Foundation, either version 3 of the License, or
-;; (at your option) any later version.
+;; This program is free software: you can redistribute it and/or modify it 
under
+;; the terms of the GNU General Public License as published by the Free 
Software
+;; Foundation, either version 3 of the License, or (at your option) any later
+;; version.
 
-;; This program is distributed in the hope that it will be useful,
-;; but WITHOUT ANY WARRANTY; without even the implied warranty of
-;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-;; GNU General Public License for more details.
+;; This program is distributed in the hope that it will be useful, but WITHOUT
+;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
FITNESS
+;; FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+;; details.
 
-;; You should have received a copy of the GNU General Public License
-;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+;; You should have received a copy of the GNU General Public License along with
+;; this program. If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Commentary:
 
-;; `engine-mode' is a global minor mode for Emacs. It enables you to
-;; easily define search engines, bind them to keybindings, and query
-;; them from the comfort of your editor.
+;; `engine-mode' is a global minor mode for Emacs. It enables you to easily
+;; define search engines, bind them to keybindings, and query them from the
+;; comfort of your editor.
 
 ;; For example, suppose we want to be able to easily search GitHub:
 
 ;; (defengine github
 ;;   "https://github.com/search?ref=simplesearch&q=%s";)
 
-;; This defines an interactive function `engine/search-github'. When
-;; executed it will take the selected region (or prompt for input, if
-;; no region is selected) and search GitHub for it, displaying the
-;; results in your default browser.
+;; This defines an interactive function `engine/search-github'. When executed 
it
+;; will take the selected region (or prompt for input, if no region is 
selected)
+;; and search GitHub for it, displaying the results in your default browser.
 
 ;; The `defengine' macro can also take an optional key combination,
 ;; prefixed with "C-x /":
@@ -55,7 +54,7 @@
   :group 'external)
 
 (defcustom engine/keybinding-prefix "C-x /"
-  "The default engine-mode keybindings prefix."
+  "The default `engine-mode' keybindings prefix."
   :type '(choice (string :tag "Key")
                  (const :tag "No keybinding" nil)))
 
@@ -77,7 +76,7 @@
   :keymap engine-mode-map)
 
 (defun engine/set-keymap-prefix (prefix-key)
-  "Bind the engine-mode keymap to a new prefix.
+  "Bind the engine-mode keymap to PREFIX-KEY.
 For example, to use \"C-c s\" instead of the default \"C-x /\":
 
 \(engine/set-keymap-prefix (kbd \"C-c s\"))"
@@ -92,23 +91,27 @@ Defaults to `browse-url-browser-function'."
   :type 'symbol)
 
 (defun engine/search-prompt (engine-name default-word)
+  "Return a search prompt for ENGINE-NAME, defaulting to DEFAULT-WORD."
   (if (string= default-word "")
       (format "Search %s: " (capitalize engine-name))
     (format "Search %s (%s): " (capitalize engine-name) default-word)))
 
 (defun engine/prompted-search-term (engine-name)
+  "Prompt the user for a search term for ENGINE-NAME.
+Default to the symbol at point."
   (let ((current-word (or (thing-at-point 'symbol 'no-properties) "")))
     (read-string (engine/search-prompt engine-name current-word)
      nil nil current-word)))
 
 (defun engine/get-query (engine-name)
-  "Return the selected region (if any) or prompt the user for a query."
+  "Return the selected region or prompt the user for a query for ENGINE-NAME."
   (if (use-region-p)
       (buffer-substring (region-beginning) (region-end))
     (engine/prompted-search-term engine-name)))
 
 (defun engine/execute-search (search-engine-url browser-function search-term)
-  "Display the results of the query."
+  "Search SEARCH-ENGINE-URL for SEARCH-TERM.
+Display the resulting URL with BROWSER-FUNCTION."
   (interactive)
   (let ((browse-url-browser-function browser-function))
     (browse-url
@@ -116,9 +119,14 @@ Defaults to `browse-url-browser-function'."
                   (format-spec-make ?s (url-hexify-string search-term))))))
 
 (defun engine/function-name (engine-name)
+  "Return the name of the function for ENGINE-NAME.
+
+For example, if ENGINE-NAME is the symbol `github', return
+`engine/search-github'."
   (intern (concat "engine/search-" (downcase (symbol-name engine-name)))))
 
 (defun engine/docstring (engine-name)
+  "Construct and return a default docstring for ENGINE-NAME."
   (format "Search %s for the selected text.\nPrompt for input if none is 
selected."
           (capitalize (symbol-name engine-name))))
 
@@ -137,21 +145,28 @@ it permits multiple keys in KEYBINDING."
                    (quote ,(engine/function-name engine-name))))))
 
 ;;;###autoload
-(cl-defmacro defengine (engine-name search-engine-url &key keybinding 
docstring (browser 'engine/browser-function) (term-transformation-hook 
'identity))
-  "Define a custom search engine.
+(cl-defmacro defengine (engine-name search-engine-url
+                                    &key keybinding docstring
+                                    (browser 'engine/browser-function)
+                                    (term-transformation-hook 'identity))
+  "Define a custom engine ENGINE-NAME searching SEARCH-ENGINE-URL.
+
+ENGINE-NAME is a symbol naming the engine.
 
-`engine-name' is a symbol naming the engine.
-`search-engine-url' is the url to be queried, with a \"%s\"
+SEARCH-ENGINE-URL is the url to be queried, with a \"%s\"
 standing in for the search term.
-The optional keyword argument `docstring' assigns a docstring to
+
+The optional keyword argument DOCSTRING assigns a docstring to
 the generated function. A reasonably sensible docstring will be
 generated if a custom one isn't provided.
-The optional keyword argument `browser` assigns the browser
+
+The optional keyword argument BROWSER assigns the browser
 function to be used when opening the URL.
-The optional keyword argument `term-transformation-hook' is a
+
+The optional keyword argument TERM-TRANSFORMATION-HOOK is a
 function that will be applied to the search term before it's
-substituted into `search-engine-url'. For example, if we wanted
-to always upcase our search terms, we might use:
+substituted into SEARCH-ENGINE-URL. For example, if we wanted to
+always upcase our search terms, we might use:
 
 \(defengine duckduckgo
   \"https://duckduckgo.com/?q=%s\";
@@ -160,29 +175,28 @@ to always upcase our search terms, we might use:
 In this case, searching for \"foobar\" will hit the url
 \"https://duckduckgo.com/?q=FOOBAR\";.
 
-The optional keyword argument `keybinding' is a string describing
+The optional keyword argument KEYBINDING is a string describing
 the key to bind the new function.
 
-Keybindings are in the `engine-mode-map', so they're prefixed.
+Keybindings are in `engine-mode-map', so they're prefixed.
 
 For example, to search Wikipedia, use:
 
   (defengine wikipedia
-    
\"https://www.wikipedia.org/search-redirect.php?language=en&go=Go&search=%s\";
+    \"https://www.wikipedia.org/search-redirect.php?search=%s\";
     :keybinding \"w\"
     :docstring \"Search Wikipedia!\")
 
 Hitting \"C-x / w\" will be bound to the newly-defined
 `engine/search-wikipedia' function."
-
   (declare (indent 1))
   (cl-assert (symbolp engine-name))
   `(prog1
-     (defun ,(engine/function-name engine-name) (search-term)
-       ,(or docstring (engine/docstring engine-name))
-       (interactive
-        (list (engine/get-query ,(symbol-name engine-name))))
-       (engine/execute-search ,search-engine-url ,browser 
(,term-transformation-hook search-term)))
+       (defun ,(engine/function-name engine-name) (search-term)
+         ,(or docstring (engine/docstring engine-name))
+         (interactive
+          (list (engine/get-query ,(symbol-name engine-name))))
+         (engine/execute-search ,search-engine-url ,browser 
(,term-transformation-hook search-term)))
      ,(engine/bind-key engine-name keybinding)))
 
 (provide 'engine-mode)