[elpa] externals/setup 1728c11: Improve documentation of setup-attributes and related functionality

[ELPA Syncer]

branch: externals/setup
commit 1728c117185319db6ca8e80fdbb89b2074d5efd1
Author: Philip Kaludercic <philipk@posteo.net>
Commit: Philip Kaludercic <philipk@posteo.net>

    Improve documentation of setup-attributes and related functionality
---
 setup.el | 26 +++++++++++++++++---------
 1 file changed, 17 insertions(+), 9 deletions(-)

diff --git a/setup.el b/setup.el
index 7731daf..24fb643 100644
--- a/setup.el
+++ b/setup.el
@@ -45,28 +45,36 @@ prepend the new context to this variable using `let', before
 calling `setup-expand'.  Within the macro definitions `setup-get'
 is used to retrieve the current context.")
 
-(defvar setup-attributes '(error-demotion)
-  "A list symbols to be used by `setup-modifier-list'.")
+(defvar setup-attributes '()
+  "A list symbols used to store a state during macro processing.
+The list is populated during macro expansion, and may modify the
+behaviour of the functions in `setup-modifier-list'..")
 
 (defun setup-wrap-to-catch-quits (body _name)
-  "Wrap BODY in a catch block if necessary."
+  "Wrap BODY in a catch block if necessary.
+The body is wrapped in a `catch' block if `setup-attributes'
+contains the symbol `need-quit'."
   (if (memq 'need-quit setup-attributes)
       `(catch ',(setup-get 'quit) ,@(macroexp-unprogn body))
     body))
 
 (defun setup-wrap-to-demote-errors (body _name)
-  "Wrap BODY in a `with-demoted-errors' block."
-  (if (memq 'error-demotion setup-attributes)
-      `(with-demoted-errors ,(format "Error in setup form on line %d: %%S"
+  "Wrap BODY in a `with-demoted-errors' block.
+This behaviour is prevented, if `setup-attributes' contains the
+symbol `without-error-demotion'."
+  (if (memq 'without-error-demotion setup-attributes)
+      body
+    `(with-demoted-errors ,(format "Error in setup form on line %d: %%S"
                                      (line-number-at-pos))
-         ,body)
-    body))
+       ,body)))
 
 (defvar setup-modifier-list
   '(setup-expand-local-macros
     setup-wrap-to-catch-quits
     setup-wrap-to-demote-errors)
-  "List of wrapper functions to be called after macro expansion.")
+  "List of wrapper functions to be called after macro expansion.
+Each function is invoked by passing the current body and the name
+of the default feature, returning the modified body.")
 
 (defvar setup-macros nil
   "Local macro definitions to be bound in `setup' bodies.