General revision of docstrings

core/core-editor.el

@@ -119,7 +119,7 @@ fundamental-mode) for performance sake."
         sp-show-pair-delay 0
         sp-max-pair-length 3)
 
-  ;; disable smartparens in evil-mode's replace state (they conflict)
+  ;; smartparens conflicts with evil-mode's replace state
   (add-hook 'evil-replace-state-entry-hook #'turn-off-smartparens-mode)
   (add-hook 'evil-replace-state-exit-hook  #'turn-on-smartparens-mode)
 

core/core-lib.el

@@ -232,8 +232,8 @@ Body forms can access the hook's arguments through the let-bound variable
 
 ;; I needed a way to reliably cross-configure modules without worrying about
 ;; whether they were enabled or not, so I wrote `set!'. If a setting doesn't
-;; exist at runtime, the `set!' call is ignored (and omitted when
-;; byte-compiled).
+;; exist at runtime, the `set!' call is ignored and its arguments are left
+;; unevaluated (and entirely omitted when byte-compiled).
 (defvar doom-settings nil)
 
 (defmacro def-setting! (keyword arglist &optional docstring &rest forms)
@@ -255,7 +255,9 @@ Do not use this for configuring Doom core."
 
 (defmacro set! (keyword &rest values)
   "Set an option defined by `def-setting!'. Skip if doesn't exist. See
-`doom/describe-setting' for a list of available settings."
+`doom/describe-setting' for a list of available settings.
+
+VALUES doesn't get evaluated if the KEYWORD setting doesn't exist."
   (declare (indent defun))
   (unless values
     (error "Empty set! for %s" keyword))

modules/config/default/+evil-commands.el

@@ -12,6 +12,7 @@
   (doom/open-scratch-buffer bang))
 
 (evil-define-command doom:pwd (bang)
+  "Display the current working directory. If BANG, copy it to your clipboard."
   (interactive "<!>")
   (if (not bang)
       (pwd)
@@ -19,6 +20,8 @@
     (message "Copied to clipboard")))
 
 (evil-define-command doom:make (command &optional from-pwd)
+  "Run the current project Makefile's COMMAND. If FROM-PWD (bang), run the make
+command from the current directory instead of the project root."
   (interactive "<sh><!>")
   (let ((default-directory (if from-pwd default-directory (doom-project-root t)))
         (command (and command (evil-ex-replace-special-filenames command))))

modules/feature/lookup/autoload/lookup.el

@@ -56,17 +56,13 @@
 
 ;;;###autoload
 (defun +lookup/definition (identifier &optional other-window)
-  "Jump to the definition of the symbol at point. It will try several things
-to find it:
+  "Jump to the definition of the symbol at point.
 
-1. It will try whatever function that has been set for the current buffer, in
-   `+lookup-current-functions'.
-2. Then try any available xref backends,
-3. Then `dumb-jump',
-4. Then a plain project-wide text search, using ripgrep or the_silver_searcher.
-5. Then, if `evil-mode' is active, use `evil-goto-definition',
+Each function in `+lookup-definition-functions' is tried until one changes the
+point or current buffer.
 
-Failing all that, it will give up with an error."
+Falls back to dumb-jump, naive ripgrep/the_silver_searcher text search, then
+`evil-goto-definition' if evil-mode is active."
   (interactive
    (list (+lookup--symbol-or-region) current-prefix-arg))
   (cond ((null identifier)
@@ -114,7 +110,10 @@ Failing all that, it will give up with an error."
 (defun +lookup/references (identifier)
   "Show a list of references to the symbol at point.
 
-Tries `xref-find-references' and falls back to rg/ag."
+Tries each function in `+lookup-references-functions' until one changes the
+point and/or current buffer.
+
+Falls back to a naive ripgrep/the_silver_searcher search otherwise."
   (interactive
    (list (+lookup--symbol-or-region)))
   (cond ((and +lookup-references-functions
@@ -145,7 +144,7 @@ Goes down a list of possible backends:
   (cond ((and +lookup-documentation-functions
               (+lookup--jump-to :documentation identifier)))
 
-        ((and (featurep! :feature lookup +docsets)
+        ((and (featurep! +docsets)
               (or (require 'counsel-dash nil t)
                   (require 'helm-dash nil t))
               (or (bound-and-true-p counsel-dash-docsets)

modules/feature/lookup/config.el

@@ -63,7 +63,10 @@ properties:
     Used by `+lookup/documentation'.
   :xref-backend FN
     Defines an xref backend for a major-mode. With this, :definition and
-    :references are unnecessary."
+    :references are unnecessary.
+
+Using this multiple times overwrites previous properties and unsets omitted
+ones."
   `(progn
      ,@(cl-loop for mode in (doom-enlist (doom-unquote modes))
                 for def-name = (intern (format "doom--init-lookup-%s" mode))