Revise and update docstrings and comments

modules/config/default/config.el

@@ -111,7 +111,7 @@
 
     ;; Highjacks backspace to:
     ;;  a) balance spaces inside brackets/parentheses ( | ) -> (|)
-    ;;  b) delete space-indented `tab-width' steps at a time
+    ;;  b) delete up to nearest column multiple of `tab-width' at a time
     ;;  c) close empty multiline brace blocks in one step:
     ;;     {
     ;;     |

modules/lang/emacs-lisp/autoload.el

@@ -1,7 +1,7 @@
 ;;; lang/emacs-lisp/autoload.el -*- lexical-binding: t; -*-
 
 ;;
-;; Library
+;;; Library
 
 ;;;###autoload
 (defun +emacs-lisp-eval (beg end)
@@ -77,7 +77,7 @@ library/userland functions"
 
 
 ;;
-;; Commands
+;;; Commands
 
 ;;;###autoload
 (defun +emacs-lisp/open-repl ()
@@ -92,7 +92,7 @@ library/userland functions"
 
 
 ;;
-;; Hooks
+;;; Hooks
 
 ;;;###autoload
 (defun +emacs-lisp|extend-imenu ()

modules/lang/emacs-lisp/config.el

@@ -14,7 +14,7 @@ This marks a foldable marker for `outline-minor-mode' in elisp buffers.")
 
 
 ;;
-;; Config
+;;; Config
 
 (def-package! elisp-mode
   :mode ("\\.Cask\\'" . emacs-lisp-mode)
@@ -76,14 +76,13 @@ This marks a foldable marker for `outline-minor-mode' in elisp buffers.")
 
 
 ;;
-;; Packages
+;;; Packages
 
-;; `auto-compile'
+;;;###package auto-compile
 (setq auto-compile-display-buffer nil
       auto-compile-use-mode-line nil)
 
 
-;; `macrostep'
 (when (featurep! :editor evil)
   (after! macrostep
     (evil-define-key* 'normal macrostep-keymap
@@ -108,7 +107,7 @@ This marks a foldable marker for `outline-minor-mode' in elisp buffers.")
     (add-hook 'macrostep-mode-hook #'evil-normalize-keymaps)))
 
 
-;; `overseer'
+;;;###package overseer
 (autoload 'overseer-test "overseer" nil t)
 (remove-hook 'emacs-lisp-mode-hook 'overseer-enable-mode)
 
@@ -129,7 +128,7 @@ This marks a foldable marker for `outline-minor-mode' in elisp buffers.")
 
 
 ;;
-;; Project modes
+;;; Project modes
 
 (def-project-mode! +emacs-lisp-ert-mode
   :modes (emacs-lisp-mode)

modules/lang/web/+css.el

@@ -22,11 +22,12 @@
 
 
 ;;
-;; Major modes
+;;; Major modes
 
 (add-hook! (css-mode sass-mode stylus-mode) #'rainbow-mode)
 
-(after! css-mode  ; built-in -- contains both css-mode & scss-mode
+;; built-in, and contains both css-mode & scss-mode
+(after! css-mode
   ;; css-mode hooks apply to scss and less-css modes
   (add-hook 'css-mode-hook #'rainbow-delimiters-mode)
   (unless EMACS26+
@@ -41,7 +42,7 @@
 
 
 ;;
-;; Tools
+;;; Tools
 
 (when (featurep! +lsp)
   (add-hook! (css-mode sass-mode less-css-mode) #'lsp!))

modules/lang/web/autoload/css.el

@@ -45,8 +45,9 @@
 
 ;;;###autoload
 (defun +css/comment-indent-new-line ()
-  "Continues the comment in an indented new line in css-mode and scss-mode.
-Meant for `comment-line-break-function'."
+  "Continues the comment in an indented new line.
+
+Meant for `comment-line-break-function' in `css-mode' and `scss-mode'."
   (interactive)
   (when (sp-point-in-comment)
     (let ((at-end (looking-at-p ".+\\*/"))

modules/lang/web/autoload/evil.el

@@ -3,7 +3,7 @@
 
 ;;;###autoload (autoload '+web:encode-html-entities "lang/web/autoload/evil" nil t)
 (evil-define-operator +web:encode-html-entities (beg end &optional input)
-  "Encodes HTML entities in the selected region."
+  "Encodes HTML entities in INPUT or the selected region."
   (interactive "<r><a>")
   (cond (input
          (insert (+web-encode-entities input)))
@@ -12,7 +12,7 @@
 
 ;;;###autoload (autoload '+web:decode-html-entities "lang/web/autoload/evil" nil t)
 (evil-define-operator +web:decode-html-entities (beg end &optional input)
-  "Decodes HTML entities in the selected region."
+  "Decodes HTML entities in INPUT or the selected region."
   (interactive "<r><a>")
   (cond (input
          (insert (+web-decode-entities input)))

modules/lang/web/autoload/html.el

@@ -94,6 +94,10 @@ function @ http://ergoemacs.org/emacs/elisp_replace_html_entities_command.html"
   "TODO"
   (+web--entities-string text t))
 
+
+;;
+;;; Commands
+
 ;;;###autoload
 (defun +web/encode-entities-region (beg end)
   "Encode HTML entities in region."
@@ -108,8 +112,10 @@ function @ http://ergoemacs.org/emacs/elisp_replace_html_entities_command.html"
 
 ;;;###autoload
 (defun +web/indent-or-yas-or-emmet-expand ()
-  "Invoke `indent-for-tab-command' if at or before text bol, `yas-expand' if on
-a snippet, or `emmet-expand-yas'/`emmet-expand-line', depending on whether
+  "Do-what-I-mean on TAB.
+
+Invokes `indent-for-tab-command' if at or before text bol, `yas-expand' if on a
+snippet, or `emmet-expand-yas'/`emmet-expand-line', depending on whether
 `yas-minor-mode' is enabled or not."
   (interactive)
   (call-interactively

modules/tools/lookup/autoload/lookup.el

@@ -5,10 +5,10 @@
 ;;;###autodef
 (cl-defun set-lookup-handlers!
     (modes &rest plist &key definition references documentation file xref-backend async)
-  "Define a jump target for major MODES.
+  "Define jump handlers for major or minor MODES.
 
 This overwrites previously defined handlers for MODES. If used on minor modes,
-they are combined with handlers defined for other minor modes or the major mode
+they are stacked onto handlers defined for other minor modes or the major mode
 it's activated in.
 
 This can be passed nil as its second argument to unset handlers for MODES. e.g.
@@ -33,10 +33,23 @@ Otherwise, these properties are available to be set:
   Defines an xref backend for a major-mode. If you define :definition and
   :references along with :xref-backend, those will have higher precedence.
 :async BOOL
-  Indicates that the supplied handlers *after* this property are asynchronous.
-  Note: async handlers do not fall back to the default handlers, due to their
-  nature. To get around this, you must write specialized wrappers to wait for
-  the async response and return 'fallback."
+  Indicates that *all* supplied FNs are asynchronous. Note: async handlers do
+  not fall back to the default handlers, due to their nature. To get around
+  this, you must write specialized wrappers to wait for the async response.
+
+  If you only want to specify one FN is async, use a PLIST instead:
+
+    (set-lookup-handlers! 'rust-mode
+      :definition '(racer-find-definition :async t))
+
+Handlers can either be interactive or non-interactive. Non-interactive handlers
+must take one argument: the identifier being looked up. This function must
+change the current buffer or window or return non-nil when it succeeds.
+
+If it doesn't change the current buffer, or it returns nil, the lookup module
+will fall back to the next handler in `+lookup-definition-functions',
+`+lookup-references-functions', `+lookup-file-functions' or
+`+lookup-documentation-functions'."
   (declare (indent defun))
   (dolist (mode (doom-enlist modes))
     (let ((hook (intern (format "%s-hook" mode)))
@@ -60,7 +73,8 @@ Otherwise, these properties are available to be set:
                                       '+lookup-references-functions
                                       '+lookup-documentation-functions
                                       '+lookup-file-functions
-                                      'xref-backend-functions)))))
+                                      'xref-backend-functions)
+                                async))))
              (add-hook hook fn))))))