tools/lookup: update README & docstrings

And minor reformatting of config.el

modules/tools/lookup/README.org

@@ -4,22 +4,24 @@
 #+STARTUP: inlineimages
 
 * Table of Contents :TOC:
-- [[Description][Description]]
+- [[#description][Description]]
-  - [[Module Flags][Module Flags]]
+  - [[#module-flags][Module Flags]]
-  - [[Plugins][Plugins]]
+  - [[#plugins][Plugins]]
-- [[Install][Install]]
+- [[#prerequisites][Prerequisites]]
-  - [[Module flags][Module flags]]
+  - [[#macos][MacOS]]
-  - [[Dependencies][Dependencies]]
+  - [[#arch-linux][Arch Linux]]
-- [[Features][Features]]
+- [[#features][Features]]
-  - [[Jump to definition][Jump to definition]]
+  - [[#jump-to-definition][Jump to definition]]
-  - [[Find references][Find references]]
+  - [[#find-references][Find references]]
-  - [[Look up documentation][Look up documentation]]
+  - [[#look-up-documentation][Look up documentation]]
-  - [[Search a specific documentation backend][Search a specific documentation backend]]
+  - [[#search-a-specific-documentation-backend][Search a specific documentation backend]]
-- [[Configuration][Configuration]]
+  - [[#dashapp-docset-integration][Dash.app Docset integration]]
-  - [[Settings][Settings]]
+- [[#configuration][Configuration]]
-  - [[Open in eww instead of browser][Open in eww instead of browser]]
+  - [[#associating-lookup-handlers-with-major-modes][Associating lookup handlers with major modes]]
-- [[Appendix][Appendix]]
+  - [[#associating-dash-docsets-with-major-modes][Associating Dash docsets with major modes]]
-  - [[Commands][Commands]]
+  - [[#open-in-eww-instead-of-browser][Open in eww instead of browser]]
+- [[#appendix][Appendix]]
+  - [[#commands][Commands]]
 
 * Description
 Integrates with code navigation and documentation tools to help you quickly look
@@ -39,35 +41,26 @@ up definitions, references and documentation.
 + [[https://github.com/alexmurray/ivy-xref][ivy-xref]] or [[https://github.com/brotzeit/helm-xref][helm-xref]]
 + [[https://github.com/nathankot/counsel-dash][counsel-dash]] or [[https://github.com/areina/helm-dash][helm-dash]]
 
-* Install
+* Prerequisites
-To enable the module add =:tools lookup= to your ~doom!~ block in
-=~/.emacs.d/init.el=.
-
-** Module flags
-This module provides two flags:
-
-+ ~+docsets~ Enables integration with Dash docsets.
-
-** Dependencies
 This module has several soft dependencies:
 
-+ ~the_silver_searcher~ and/or ~ripgrep~ as a last-resort fallback for
++ ~the_silver_searcher~ or ~ripgrep~ (recommended) as a last-resort fallback for
   jump-to-definition/find-references.
-+ Optionally, ~sqlite3~ for Dash docset support.
++ ~sqlite3~ for Dash docset support.
 
-*** MacOS
+** MacOS
 #+BEGIN_SRC sh
 brew install the_silver_searcher ripgrep
 
 # An older version of sqlite is included in MacOS. If it causes you problems (and
-# it has been reported that it will), install it through homebrew:
+# folks have reported it will), install it through homebrew:
 brew install sqlite
 # Note that it's keg-only, meaning it isn't symlinked to /usr/local/bin. You'll
 # have to add it to PATH yourself (or symlink it into your PATH somewhere). e.g.
 export PATH="/usr/local/opt/sqlite/bin:$PATH"
 #+END_SRC
 
-*** Arch Linux
+** Arch Linux
 #+BEGIN_SRC sh
 sudo pacman -S sqlite the_silver_searcher ripgrep
 #+END_SRC
@@ -121,17 +114,21 @@ Depending on your configuration, this will try a list of sources:
 You can perform a documentation lookup on any backends directly:
 
 + Dash Docsets: ~+lookup/in-docsets~, or ~:dash QUERY~ for evil users.
-+ devdocs.io: ~+lookup/in-devdocs~, or ~:dd QUERY~ for evil users.
 + Online (generic): ~+lookup/online~ or ~+lookup/online-select~ (bound to =SPC /
   o=), or ~:lo[okup] QUERY~ for evil users.
 
-* Configuration
+** Dash.app Docset integration
-** Settings
+You can install dash docsets with ~M-x +lookup/install-docset~ and search them
-This module provides two setters:
+offline with ~M-x +lookup/in-docsets~, or with ~+lookup/documentation~ in modes
+that don't have a specialized :documentation lookup handler.
 
-*** ~set-lookup-handlers! MODES &rest PLIST~
+* Configuration
-Defines a lookup target for major MODES (one major-mode symbol or a list
+** Associating lookup handlers with major modes
-thereof). PLIST accepts the following optional properties:
+~set-lookup-handlers! MODES &key DEFINITION REFERENCES DOCUMENTATION FILE XREF-BACKEND ASYNC~
+
+Use ~set-lookup-handlers!~ to register lookup targets for MODES (a major or
+minor mode symbol or list thereof). PLIST accepts the following optional
+properties:
 
 + ~:definition FN~ :: Run when jumping to a symbol's definition. Used by
      ~+lookup/definition~.
@@ -141,10 +138,11 @@ thereof). PLIST accepts the following optional properties:
      ~+lookup/documentation~.
 + ~:file FN~ :: Run when looking up the file for a symbol/string. Typically a
      file path. Used by ~+lookup/file~.
-+ ~:xref-backend FN~ :: Defines an xref backend for a major-mode. With this,
++ ~:xref-backend FN~ :: Defines an xref backend, which implicitly provides
-     :definition and :references are unnecessary.
+     :definition and :references handlers. If you specify them anyway, they will
+     take precedence over the xref backend, however.
 
-**** Example
+e.g.
 #+BEGIN_SRC emacs-lisp
 ;; For python-mode, anaconda-mode offers a backend for all three lookup
 ;; functions. We can register them like so:
@@ -160,11 +158,14 @@ thereof). PLIST accepts the following optional properties:
 ;; NOTE: xref doesn't provide a :documentation backend.
 #+END_SRC
 
-*** ~set-docsets! MODES &rest DOCSETS~
+** Associating Dash docsets with major modes
-Registers DOCSETS (one string or list of strings) for MODES (one major mode
+~set-docsets! MODES &rest DOCSETS...~
-symbol or a list of them). It is used by ~+lookup/in-docsets~ and
-~+lookup/documentation~.
 
+Use ~set-docsets!~ to register DOCSETS (one string or list of strings) for MODES
+(one major mode symbol or a list of them). It is used by ~+lookup/in-docsets~
+and ~+lookup/documentation~.
+
+e.g.
 #+BEGIN_SRC emacs-lisp
 (set-docsets! 'js2-mode "JavaScript" "JQuery")
 ;; Add docsets to minor modes by starting DOCSETS with :add
@@ -173,9 +174,16 @@ symbol or a list of them). It is used by ~+lookup/in-docsets~ and
 (set-docsets! 'nodejs-mode :remove "JQuery")
 #+END_SRC
 
+This determines what docsets to implicitly search for when you use
+~+lookup/documentation~ in a mode with no ~:documentation~ handler. Those
+docsets must be installed with ~+lookup/install-docset~.
+
 ** Open in eww instead of browser
+To open results from ~+lookup/online~ in EWW instead of your system browser,
+change ~+lookup-open-url-fn~ (default: ~#'browse-url~):
+
 #+BEGIN_SRC emacs-lisp
-(setq +lookup-open-url-fn 'eww)
+(setq +lookup-open-url-fn #'eww)
 #+END_SRC
 
 * Appendix

modules/tools/lookup/config.el

@@ -41,7 +41,8 @@ window/point.
 
 If the argument is interactive (satisfies `commandp'), it is called with
 `call-interactively' (with no arguments). Otherwise, it is called with one
-argument: the identifier at point.")
+argument: the identifier at point. See `set-lookup-handlers!' about adding to
+this list.")
 
 (defvar +lookup-references-functions
   '(+lookup-xref-references-backend
@@ -52,7 +53,8 @@ window/point.
 
 If the argument is interactive (satisfies `commandp'), it is called with
 `call-interactively' (with no arguments). Otherwise, it is called with one
-argument: the identifier at point.")
+argument: the identifier at point. See `set-lookup-handlers!' about adding to
+this list.")
 
 (defvar +lookup-documentation-functions
   '(+lookup-dash-docsets-backend
@@ -63,7 +65,8 @@ window/point.
 
 If the argument is interactive (satisfies `commandp'), it is called with
 `call-interactively' (with no arguments). Otherwise, it is called with one
-argument: the identifier at point.")
+argument: the identifier at point. See `set-lookup-handlers!' about adding to
+this list.")
 
 (defvar +lookup-file-functions ()
   "Function for `+lookup/file' to try, before restoring to `find-file-at-point'.
@@ -72,7 +75,8 @@ window/point.
 
 If the argument is interactive (satisfies `commandp'), it is called with
 `call-interactively' (with no arguments). Otherwise, it is called with one
-argument: the identifier at point.")
+argument: the identifier at point. See `set-lookup-handlers!' about adding to
+this list.")
 
 
 ;;
@@ -97,19 +101,19 @@ argument: the identifier at point.")
   ;; We already have `projectile-find-tag' and `evil-jump-to-tag', no need for
   ;; xref to be one too.
   (remove-hook 'xref-backend-functions #'etags--xref-backend)
+  ;; ...however, it breaks `projectile-find-tag', unless we put it back.
+  (defun +lookup*projectile-find-tag (orig-fn)
+    (let ((xref-backend-functions '(etags--xref-backend t)))
+      (funcall orig-fn)))
+  (advice-add #'projectile-find-tag :around #'+lookup*projectile-find-tag)
+
   ;; The lookup commands are superior, and will consult xref if there are no
   ;; better backends available.
   (global-set-key [remap xref-find-definitions] #'+lookup/definition)
-  (global-set-key [remap xref-find-references]  #'+lookup/references))
+  (global-set-key [remap xref-find-references]  #'+lookup/references)
 
-;; Use `better-jumper' instead of xref's marker stack
+  ;; Use `better-jumper' instead of xref's marker stack
-(advice-add #'xref-push-marker-stack :around #'doom*set-jump)
+  (advice-add #'xref-push-marker-stack :around #'doom*set-jump))
-
-;; ...however, it breaks `projectile-find-tag', unless we put it back.
-(defun +lookup*projectile-find-tag (orig-fn)
-  (let ((xref-backend-functions '(etags--xref-backend t)))
-    (funcall orig-fn)))
-(advice-add #'projectile-find-tag :around #'+lookup*projectile-find-tag)
 
 
 (def-package! ivy-xref