emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Revise core lib docstrings for clarity

Browse source
This commit is contained in:
Henrik Lissner 2020-12-11 17:38:59 -05:00
parent 10f1b8040a
commit 4281a772b1
No known key found for this signature in database
GPG key ID: 5F6C0EA160557395
1 changed files with 28 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

38
core/core-lib.el
View file

@ -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)