lisp/subr.el: Update comment.

[bpt/emacs.git] / lisp / subr.el

diff --git a/lisp/subr.el b/lisp/subr.el
index 6c79b3f..87b9898 100644 (file)
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -1785,6 +1785,8 @@ this name matching.
 
 Alternatively, FILE can be a feature (i.e. a symbol), in which case FORM
 is evaluated at the end of any file that `provide's this feature.
+If the feature is provided when evaluating code not associated with a
+file, FORM is evaluated immediately after the provide statement.
 
 Usually FILE is just a library name like \"font-lock\" or a feature name
 like 'font-lock.
@@ -1814,14 +1816,16 @@ This function makes or adds to an entry on `after-load-alist'."
        ;; make sure that `form' is really run "after-load" in case the provide
        ;; call happens early.
        (setq form
-             `(when load-file-name
-                (let ((fun (make-symbol "eval-after-load-helper")))
-                  (fset fun `(lambda (file)
-                               (if (not (equal file ',load-file-name))
-                                   nil
-                                 (remove-hook 'after-load-functions ',fun)
-                                 ,',form)))
-                  (add-hook 'after-load-functions fun)))))
+             `(if load-file-name
+                  (let ((fun (make-symbol "eval-after-load-helper")))
+                    (fset fun `(lambda (file)
+                                 (if (not (equal file ',load-file-name))
+                                     nil
+                                   (remove-hook 'after-load-functions ',fun)
+                                   ,',form)))
+                    (add-hook 'after-load-functions fun))
+                ;; Not being provided from a file, run form right now.
+                ,form)))
       ;; Add FORM to the element unless it's already there.
       (unless (member form (cdr elt))
        (nconc elt (purecopy (list form)))))))
@@ -1884,14 +1888,14 @@ Used from `delayed-warnings-hook' (which see)."
         (push warning collapsed)))
     (setq delayed-warnings-list (nreverse collapsed))))
 
-;; At present this is only really useful for Emacs internals.
-;; Document in the lispref if it becomes generally useful.
+;; At present this is only used for Emacs internals.
 ;; Ref http://lists.gnu.org/archive/html/emacs-devel/2012-02/msg00085.html
 (defvar delayed-warnings-hook '(collapse-delayed-warnings
                                 display-delayed-warnings)
-  "Normal hook run to process delayed warnings.
-Functions in this hook should access the `delayed-warnings-list'
-variable (which see) and remove from it the warnings they process.")
+  "Normal hook run to process and display delayed warnings.
+By default, this hook contains functions to consolidate the
+warnings listed in `delayed-warnings-list', display them, and set
+`delayed-warnings-list' back to nil.")
 
 \f
 ;;;; Process stuff.
@@ -3026,13 +3030,12 @@ the buffer list."
           (set-buffer ,old-buffer))))))
 
 (defmacro save-window-excursion (&rest body)
-  "Execute BODY, preserving window sizes and contents.
-Return the value of the last form in BODY.
-Restore which buffer appears in which window, where display starts,
-and the value of point and mark for each window.
-Also restore the choice of selected window.
-Also restore which buffer is current.
-Does not restore the value of point in current buffer.
+  "Execute BODY, then restore previous window configuration.
+This macro saves the window configuration on the selected frame,
+executes BODY, then calls `set-window-configuration' to restore
+the saved window configuration.  The return value is the last
+form in BODY.  The window configuration is also restored if BODY
+exits nonlocally.
 
 BEWARE: Most uses of this macro introduce bugs.
 E.g. it should not be used to try and prevent some code from opening
@@ -3219,7 +3222,7 @@ If BODY finishes, `while-no-input' returns whatever value BODY produced."
           (or (input-pending-p)
               (progn ,@body)))))))
 
-(defmacro condition-case-no-debug (var bodyform &rest handlers)
+(defmacro condition-case-unless-debug (var bodyform &rest handlers)
   "Like `condition-case' except that it does not catch anything when debugging.
 More specifically if `debug-on-error' is set, then it does not catch any signal."
   (declare (debug condition-case) (indent 2))
@@ -3231,6 +3234,9 @@ More specifically if `debug-on-error' is set, then it does not catch any signal.
              (funcall ,bodysym)
            ,@handlers)))))
 
+(define-obsolete-function-alias 'condition-case-no-debug
+  'condition-case-unless-debug "24.1")
+
 (defmacro with-demoted-errors (&rest body)
   "Run BODY and demote any errors to simple messages.
 If `debug-on-error' is non-nil, run BODY without catching its errors.
@@ -3238,7 +3244,7 @@ This is to be used around code which is not expected to signal an error
 but which should be robust in the unexpected case that an error is signaled."
   (declare (debug t) (indent 0))
   (let ((err (make-symbol "err")))
-    `(condition-case-no-debug ,err
+    `(condition-case-unless-debug ,err
          (progn ,@body)
        (error (message "Error: %S" ,err) nil))))