[Emacs-diffs] /srv/bzr/emacs/trunk r110579: * lisp/emacs-lisp/advice.el: Clean up commentary a bit.

[Stefan Monnier]

------------------------------------------------------------
revno: 110579
committer: Stefan Monnier <address@hidden>
branch nick: trunk
timestamp: Thu 2012-10-18 11:37:57 -0400
message:
  * lisp/emacs-lisp/advice.el: Clean up commentary a bit.
  (ad-do-advised-functions, ad-with-originals): Use `declare'.
  (byte-code-function-p): Never redefine.
modified:
  lisp/ChangeLog
  lisp/emacs-lisp/advice.el

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-10-18 12:56:10 +0000
+++ b/lisp/ChangeLog    2012-10-18 15:37:57 +0000
@@ -1,5 +1,9 @@
 2012-10-18  Stefan Monnier  <address@hidden>
 
+       * emacs-lisp/advice.el: Clean up commentary a bit.
+       (ad-do-advised-functions, ad-with-originals): Use `declare'.
+       (byte-code-function-p): Never redefine.
+
        * emacs-lisp/gv.el (cond): Same fix as before for `if'.
 
 2012-10-18  Glenn Morris  <address@hidden>

=== modified file 'lisp/emacs-lisp/advice.el'
--- a/lisp/emacs-lisp/advice.el 2012-09-14 13:44:31 +0000
+++ b/lisp/emacs-lisp/advice.el 2012-10-18 15:37:57 +0000
@@ -31,10 +31,6 @@
 
 ;;; Commentary:
 
-;; NOTE: This documentation is slightly out of date. In particular, all the
-;; references to Emacs-18 are obsolete now, because it is not any longer
-;; supported by this version of Advice.
-
 ;; Advice is documented in the Emacs Lisp Manual.
 
 ;; @ Introduction:
@@ -83,21 +79,10 @@
 ;; - Provides manipulation mechanisms for sets of advised functions via
 ;;   regular expressions that match advice names
 
-;; @ How to get Advice for Emacs-18:
-;; =================================
-;; `advice18.el', a version of Advice that also works in Emacs-18 is available
-;; either via anonymous ftp from `ftp.cs.buffalo.edu (128.205.32.9)' with
-;; pathname `/pub/Emacs/advice18.el', or from one of the Emacs Lisp archive
-;; sites, or send email to <address@hidden> and I'll mail it to you.
-
 ;; @ Overview, or how to read this file:
 ;; =====================================
-;; NOTE: This documentation is slightly out of date. In particular, all the
-;; references to Emacs-18 are obsolete now, because it is not any longer
-;; supported by this version of Advice. An up-to-date version will soon be
-;; available as an info file (thanks to the kind help of Jack Vinson and
-;; David M. Smith). Until then you can use `outline-mode' to help you read
-;; this documentation (set `outline-regexp' to `";; @+"').
+;; You can use `outline-mode' to help you read this documentation (set
+;; `outline-regexp' to `";; @+"').
 ;;
 ;; The four major sections of this file are:
 ;;
@@ -111,9 +96,6 @@
 
 ;; @ Restrictions:
 ;; ===============
-;; - This version of Advice only works for Emacs 19.26 and later. It uses
-;;   new versions of the built-in functions `fset/defalias' which are not
-;;   yet available in Lucid Emacs, hence, it won't work there.
 ;; - Advised functions/macros/subrs will only exhibit their advised behavior
 ;;   when they are invoked via their function cell. This means that advice will
 ;;   not work for the following:
@@ -229,13 +211,8 @@
 
 ;; @@ Terminology:
 ;; ===============
-;; - Emacs, Emacs-19: Emacs as released by the GNU Project
-;; - Lemacs: Lucid's version of Emacs with major version 19
-;; - v18: Any Emacs with major version 18 or built as an extension to that
-;;        (such as Epoch)
-;; - v19: Any Emacs with major version 19
-;; - jwz: Jamie Zawinski - former keeper of Lemacs and creator of the 
optimizing
-;;        byte-compiler used in v19s.
+;; - Emacs: Emacs as released by the GNU Project
+;; - jwz: Jamie Zawinski - creator of the byte-compiler used in v19s.
 ;; - Advice: The name of this package.
 ;; - advices: Short for "pieces of advice".
 
@@ -294,8 +271,7 @@
 ;;              generates a compiled advised definition according to the
 ;;              current advice state which will be used during activation
 ;;              if appropriate. Only use this if the `defadvice' gets
-;;              actually compiled (with a v18 byte-compiler put the `defadvice'
-;;              into the body of a `defun' to accomplish proper compilation).
+;;              actually compiled.
 
 ;; An optional <documentation-string> can be supplied to document the advice.
 ;; On call of the `documentation' function it will be combined with the
@@ -399,10 +375,7 @@
 ;; gets redefined in a non-advice style into a function by the edebug
 ;; package. If the advice assumes `eval-region' to be a subr it might break
 ;; once edebug is loaded. Similar situations arise when one wants to use the
-;; same piece of advice across different versions of Emacs. Some subrs in a
-;; v18 Emacs are functions in v19 and vice versa, but for the most part the
-;; semantics remain the same, hence, the same piece of advice might be usable
-;; in both Emacs versions.
+;; same piece of advice across different versions of Emacs.
 
 ;; As a solution to that advice provides argument list access macros that get
 ;; translated into the proper access forms at activation time, i.e., when the
@@ -556,12 +529,7 @@
 ;; defined. The special forms `defun' and `defmacro' have been advised to
 ;; check whether the function/macro they defined had advice information
 ;; associated with it. If so and forward advice is enabled, the original
-;; definition will be saved, and then the advice will be activated. When a
-;; file is loaded in a v18 Emacs the functions/macros it defines are also
-;; defined with calls to `defun/defmacro'.  Hence, we can forward advise
-;; functions/macros which will be defined later during a load/autoload of some
-;; file (for compiled files generated by jwz's byte-compiler in a v19 Emacs
-;; this is slightly more complicated but the basic idea is the same).
+;; definition will be saved, and then the advice will be activated.
 
 ;; @@ Enabling/disabling pieces or sets of advice:
 ;; ===============================================
@@ -694,10 +662,8 @@
 ;; specified as disabled) and all other currently enabled pieces of advice to
 ;; construct an advised definition and an identifying cache-id and makes them
 ;; part of the `defadvice' expansion which will then be compiled by the
-;; byte-compiler (to ensure that in a v18 emacs you have to put the
-;; `defadvice' inside a `defun' to get it compiled and then you have to call
-;; that compiled `defun' in order to actually execute the `defadvice'). When
-;; the file with the compiled, preactivating `defadvice' gets loaded the
+;; byte-compiler.
+;; When the file with the compiled, preactivating `defadvice' gets loaded the
 ;; precompiled advised definition will be cached on the advised function's
 ;; advice-info. When it gets activated (can be immediately on execution of the
 ;; `defadvice' or any time later) the cache-id gets checked against the
@@ -792,8 +758,7 @@
 ;; advised definition of a function, rather they are assembled into a hook
 ;; form which will be evaluated whenever the advice-info of the advised
 ;; function gets activated or deactivated. One application of this mechanism
-;; is to define file load hooks for files that do not provide such hooks
-;; (v19s already come with a general file-load-hook mechanism, v18s don't).
+;; is to define file load hooks for files that do not provide such hooks.
 ;; For example, suppose you want to print a message whenever `file-x' gets
 ;; loaded, and suppose the last function defined in `file-x' is
 ;; `file-x-last-fn'.  Then we can define the following advice:
@@ -1400,8 +1365,8 @@
 ;;
 ;; If you put a preactivating `defadvice' into a Lisp file that gets byte-
 ;; compiled then the constructed advised definition will get compiled by
-;; the byte-compiler. For that to occur in a v18 emacs you have to put the
-;; `defadvice' inside a `defun' because the v18 compiler does not compile
+;; the byte-compiler. For that to occur in a v18 Emacs you had to put the
+;; `defadvice' inside a `defun' because the v18 compiler did not compile
 ;; top-level forms other than `defun' or `defmacro', for example,
 ;;
 ;; (defun fg-defadvice-fum ()
@@ -1496,10 +1461,7 @@
 ;; if one advises a subr such as `eval-region' which then gets redefined by
 ;; some package (e.g., edebug) into a function with different argument names,
 ;; then a piece of advice written for `eval-region' that was written with
-;; the subr arguments in mind will break. Similar situations arise when one
-;; switches between major Emacs versions, e.g., certain subrs in v18 are
-;; functions in v19 and vice versa. Also, in v19s subr argument lists
-;; are available and will be used, while they are not available in v18.
+;; the subr arguments in mind will break.
 ;;
 ;; Argument access text macros allow one to access arguments of an advised
 ;; function in a portable way without having to worry about all these
@@ -1882,15 +1844,13 @@
    BODY-FORM...)
 On each iteration VAR will be bound to the name of an advised function
 \(a symbol)."
+  (declare (indent 1))
   `(cl-dolist (,(car varform)
                ad-advised-functions
                ,(car (cdr varform)))
      (setq ,(car varform) (intern (car ,(car varform))))
      ,@body))
 
-(if (not (get 'ad-do-advised-functions 'lisp-indent-hook))
-    (put 'ad-do-advised-functions 'lisp-indent-hook 1))
-
 (defun ad-get-advice-info (function)
   (get function 'ad-advice-info))
 
@@ -2117,7 +2077,7 @@
                (lambda (function)
                  ;; Oops, no closures - the joys of dynamic scoping:
                  ;; `predicate' clashed with the `predicate' argument
-                 ;; of Lemacs' `completing-read'.....
+                 ;; of `completing-read'.....
                  (funcall ad-pReDiCaTe (intern (car function))))))
           t)))
     (if (equal function "")
@@ -2394,12 +2354,6 @@
   ;;"non-nil if DEFINITION is a piece of advice."
   `(eq (car-safe ,definition) 'advice))
 
-;; Emacs/Lemacs cross-compatibility
-;; (compiled-function-p is an obsolete function in Emacs):
-(if (and (not (fboundp 'byte-code-function-p))
-        (fboundp 'compiled-function-p))
-    (ad-safe-fset 'byte-code-function-p 'compiled-function-p))
-
 (defmacro ad-compiled-p (definition)
   "Return non-nil if DEFINITION is a compiled byte-code object."
   `(or (byte-code-function-p ,definition)
@@ -3696,6 +3650,7 @@
 For any members of FUNCTIONS that are not currently advised the rebinding will
 be a noop.  Any modifications done to the definitions of FUNCTIONS will be
 undone on exit of this macro."
+  (declare (indent 1))
   (let* ((index -1)
         ;; Make let-variables to store current definitions:
         (current-bindings
@@ -3735,14 +3690,6 @@
                 ,(car (nth index current-bindings)))))
             functions))))))
 
-(if (not (get 'ad-with-originals 'lisp-indent-hook))
-    (put 'ad-with-originals 'lisp-indent-hook 1))
-
-
-;; @@ Advising `documentation':
-;; ============================
-;; Use the advice mechanism to advise `documentation' to make it
-;; generate proper documentation strings for advised definitions:
 
 ;; @@ Starting, stopping and recovering from the advice package magic:
 ;; ===================================================================