From 4281a772b1f7692ca2f918914e962efec973a416 Mon Sep 17 00:00:00 2001
From: Henrik Lissner <henrik@lissner.net>
Date: Fri, 11 Dec 2020 17:38:59 -0500
Subject: [PATCH] Revise core lib docstrings for clarity

---
 core/core-lib.el | 38 ++++++++++++++++++++++++++++----------
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/core/core-lib.el b/core/core-lib.el
index a6035dba0..2a43c2407 100644
--- a/core/core-lib.el
+++ b/core/core-lib.el
@@ -67,8 +67,8 @@ list is returned as-is."
 
 (defmacro doom-log (format-string &rest args)
   "Log to *Messages* if `doom-debug-p' is on.
-Does not interrupt the minibuffer if it is in use, but still logs to *Messages*.
-Accepts the same arguments as `message'."
+Does not display text in echo area, but still logs to *Messages*. Accepts the
+same arguments as `message'."
   `(when doom-debug-p
      (let ((inhibit-message (active-minibuffer-window)))
        (message
@@ -85,7 +85,7 @@ Accepts the same arguments as `message'."
 (defalias 'doom-partial #'apply-partially)
 
 (defun doom-rpartial (fn &rest args)
-  "Return a function that is a partial application of FUN to right-hand ARGS.
+  "Return a partial application of FUN to right-hand ARGS.
 
 ARGS is a list of the last N arguments to pass to FUN. The result is a new
 function which does the same as FUN, except that the last N arguments are fixed
@@ -123,6 +123,7 @@ at the values with which this function was called."
 
 (defmacro letf! (bindings &rest body)
   "Temporarily rebind function and macros in BODY.
+Intended as a simpler version of `cl-letf' and `cl-macrolet'.
 
 BINDINGS is either a) a list of, or a single, `defun' or `defmacro'-ish form, or
 b) a list of (PLACE VALUE) bindings as `cl-letf*' would accept.
@@ -157,7 +158,8 @@ the same name, for use with `funcall' or `apply'. ARGLIST and BODY are as in
   "Run FORMS without generating any output.
 
 This silences calls to `message', `load', `write-region' and anything that
-writes to `standard-output'."
+writes to `standard-output'. In interactive sessions this won't suppress writing
+to *Messages*, only inhibit output in the echo area."
   `(if doom-debug-p
        (progn ,@forms)
      ,(if doom-interactive-p
@@ -193,21 +195,24 @@ See `eval-if!' for details on this macro's purpose."
 
 ;;; Closure factories
 (defmacro fn! (arglist &rest body)
-  "Expands to (cl-function (lambda ARGLIST BODY...))"
+  "Returns (cl-function (lambda ARGLIST BODY...))
+The closure is wrapped in `cl-function', meaning ARGLIST will accept anything
+`cl-defun' will. "
   (declare (indent defun) (doc-string 1) (pure t) (side-effect-free t))
   `(cl-function (lambda ,arglist ,@body)))
 
 (defmacro cmd! (&rest body)
-  "Expands to (lambda () (interactive) ,@body).
+  "Returns (lambda () (interactive) ,@body)
 A factory for quickly producing interaction commands, particularly for keybinds
 or aliases."
   (declare (doc-string 1) (pure t) (side-effect-free t))
   `(lambda (&rest _) (interactive) ,@body))
 
 (defmacro cmd!! (command &optional prefix-arg &rest args)
-  "Expands to a closure that interactively calls COMMAND with ARGS.
-A factory for quickly producing interactive, prefixed commands for keybinds or
-aliases."
+  "Returns a closure that interactively calls COMMAND with ARGS and PREFIX-ARG.
+Like `cmd!', but allows you to change `current-prefix-arg' or pass arguments to
+COMMAND. This macro is meant to be used as a target for keybinds (e.g. with
+`define-key' or `map!')."
   (declare (doc-string 1) (pure t) (side-effect-free t))
   `(lambda (arg &rest _) (interactive "P")
      (let ((current-prefix-arg (or ,prefix-arg arg)))
@@ -217,7 +222,20 @@ aliases."
         ,command ,@args))))
 
 (defmacro cmds! (&rest branches)
-  "Expands to a `menu-item' dispatcher for keybinds."
+  "Returns a dispatcher that runs the a command in BRANCHES.
+Meant to be used as a target for keybinds (e.g. with `define-key' or `map!').
+
+BRANCHES is a flat list of CONDITION COMMAND pairs. CONDITION is a lisp form
+that is evaluated when (and each time) the dispatcher is invoked. If it returns
+non-nil, COMMAND is invoked, otherwise it falls through to the next pair.
+
+The last element of BRANCHES can be a COMMANd with no CONDITION. This acts as
+the fallback if all other conditions fail.
+
+Otherwise, Emacs will fall through the keybind and search the next keymap for a
+keybind (as if this keybind never existed).
+
+See `general-key-dispatch' for what other arguments it accepts in BRANCHES."
   (declare (doc-string 1))
   (let ((docstring (if (stringp (car branches)) (pop branches) ""))
         fallback)