[elpa] externals/setup 1893abc 13/24: Document :shorthand and extractors

[Stefan Monnier]

branch: externals/setup
commit 1893abc9965b32bbc9f6efe3d1d803b8e45ab550
Author: Philip K <philipk@posteo.net>
Commit: Philip K <philipk@posteo.net>

    Document :shorthand and extractors
---
 setup.el | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/setup.el b/setup.el
index d7f6782..e9aafbf 100644
--- a/setup.el
+++ b/setup.el
@@ -101,7 +101,8 @@ Do not modify this variable by hand.  Instead use
 (defmacro setup (name &rest body)
   "Configure feature or subsystem NAME.
 BODY may contain special forms defined by `setup-define', but
-will otherwise just be evaluated as is."
+will otherwise just be evaluated as is.
+NAME may also be a macro, if it can provide a symbol."
   (declare (debug (&rest &or [symbolp sexp] form))
            (indent defun))
   (when (consp name)
@@ -142,6 +143,12 @@ Give an advertised calling convention.
   :documentation STRING
 A documentation string.
 
+  :shorthand EXTRACTOR
+If a macro defines a shorthand, it might be used as the first
+argument of a `setup' form, instead of a symbol.  EXTRACTOR must
+be a function of one argument.  It takes the entire macro and
+returns a symbol to replace NAME.
+
   :debug SPEC
 A edebug specification, see Info node `(elisp) Specification List'.
 If not given, it is assumed nothing is evaluated."
@@ -238,14 +245,18 @@ If not given, it is assumed nothing is evaluated."
   (lambda (package)
     `(unless (package-installed-p ',package)
        (package-install ',package)))
-  :documentation "Install PACKAGE if it hasn't been installed yet."
+  :documentation "Install PACKAGE if it hasn't been installed yet.
+This macro can be used as HEAD, and it will replace itself with
+the first PACKAGE."
   :repeatable t
   :shorthand #'cadr)
 
 (setup-define :require
   (lambda (feature)
     `(require ',feature))
-  :documentation "Eagerly require FEATURE."
+  :documentation "Eagerly require FEATURE.
+This macro can be used as HEAD, and it will replace itself with
+the first FEATURE."
   :repeatable t
   :shorthand #'cadr)