Edebug doc fixes

* doc/lispref/edebug.texi (Instrumenting Macro Calls):
Mention defining macros at instrumentation time.
(Edebug Options): Mention edebug-unwrap-results.

* lisp/emacs-lisp/edebug.el (edebug-unwrap-results): Doc fix.
Comments.

* admin/FOR-RELEASE: Markup.

5 files changed, 65 insertions, 6 deletions

diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index 1f498e06c31..ec12b977b9e 100644
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -183,7 +183,7 @@ xresources.texi   cyd
 abbrevs.texi      rgm
 advice.texi       cyd
 anti.texi         
-back.texi
+back.texi         rgm
 backups.texi      cyd
 buffers.texi      cyd
 commands.texi     cyd
@@ -192,7 +192,7 @@ control.texi      cyd
 customize.texi    cyd
 debugging.texi    cyd
 display.texi      cyd
-edebug.texi
+edebug.texi       rgm
 elisp.texi
 errors.texi       rgm
 eval.texi         cyd
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index b0f9b7c586e..cb7a5c48e15 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2012-03-31  Glenn Morris  <rgm@gnu.org>
+
+        * edebug.texi (Instrumenting Macro Calls):
+        Mention defining macros at instrumentation time.
+        (Edebug Options): Mention edebug-unwrap-results.
+
 2012-03-31  Eli Zaretskii  <eliz@gnu.org>
 
         * text.texi (Special Properties): Clarify the description of the
diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi
index 33e5e54f1c6..245aaf94c6d 100644
--- a/doc/lispref/edebug.texi
+++ b/doc/lispref/edebug.texi
@@ -1113,6 +1113,15 @@ definition, but specifications are much more general than macro
 arguments.  @xref{Defining Macros}, for more explanation of
 the @code{declare} form.
 
+@c See eg http://debbugs.gnu.org/10577
+@c FIXME  Maybe there should be an Edebug option to get it to
+@c automatically load the entire source file containing the function
+@c being instrumented.  That would avoid this.
+  Take care to ensure that the specifications are known to Edebug when
+you instrument code.  If you are instrumenting a function from a file
+that uses @code{eval-when-compile} to require another file containing
+macro definitions, you may need to explicitly load that file.
+
   You can also define an edebug specification for a macro separately
 from the macro definition with @code{def-edebug-spec}.  Adding
 @code{debug} declarations is preferred, and more convenient, for macro
@@ -1255,6 +1264,8 @@ Each of the following elements is matched as alternatives as if by using
 of them match, nothing is matched, but the @code{&not} specification
 succeeds.
 
+@c FIXME &key?
+
 @item &define
 @c @kindex &define @r{(Edebug)}
 Indicates that the specification is for a defining form.  The defining
@@ -1422,7 +1433,15 @@ of the bindings is either a symbol or a sublist with a symbol and
 optional expression.  In the specification below, notice the @code{gate}
 inside of the sublist to prevent backtracking once a sublist is found.
 
-@c FIXME? The actual definition in edebug.el does not have a gate.
+@ignore
+@c FIXME?  The actual definition in edebug.el looks like this (and always
+@c has AFAICS).  In fact, nothing in edebug.el uses gate.  So maybe
+@c this is just an example for illustration?
+(def-edebug-spec let
+  ((&rest
+    &or (symbolp &optional form) symbolp)
+   body))
+@end ignore
 @example
 (def-edebug-spec let
   ((&rest
@@ -1566,7 +1585,28 @@ debugged.
 @xref{Edebug Execution Modes}.
 @end defopt
 
-@c FIXME edebug-unwrap-results
+@defopt edebug-unwrap-results
+If non-@code{nil}, Edebug tries to remove any of its own
+instrumentation when showing the results of expressions.  This is
+relevant when debugging macros where the results of expressions are
+themselves instrumented expressions.  As a very artificial example,
+suppose that the example function @code{fac} has been instrumented,
+and consider a macro of the form:
+
+@c FIXME find a less silly example.
+@smallexample
+(defmacro test () "Edebug example."
+  (if (symbol-function 'fac)
+      @dots{}))
+@end smallexample
+
+If you instrument the @code{test} macro and step through it, then by
+default the result of the @code{symbol-function} call has numerous
+@code{edebug-after} and @code{edebug-before} forms, which can make it
+difficult to see the ``actual'' result.  If
+@code{edebug-unwrap-results} is non-@code{nil}, Edebug tries to remove
+these forms from the result.
+@end defopt
 
 @defopt edebug-on-error
 Edebug binds @code{debug-on-error} to this value, if
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 2def7e4c934..970c74bf50f 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2012-03-31  Glenn Morris  <rgm@gnu.org>
+
+        * emacs-lisp/edebug.el (edebug-unwrap-results): Doc fix.
+
 2012-03-30  Thierry Volpiatto  <thierry.volpiatto@gmail.com>
 
         * dired-aux.el (dired-copy-file-recursive, dired-create-files):
diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el
index c241ac710cf..67ffd6d5d31 100644
--- a/lisp/emacs-lisp/edebug.el
+++ b/lisp/emacs-lisp/edebug.el
@@ -1,6 +1,6 @@
 ;;; edebug.el --- a source-level debugger for Emacs Lisp
 
-;; Copyright (C) 1988-1995, 1997, 1999-2012  Free Software Foundation, Inc.
+;; Copyright (C) 1988-1995, 1997, 1999-2012 Free Software Foundation, Inc.
 
 ;; Author: Daniel LaLiberte <liberte@holonexus.org>
 ;; Maintainer: FSF
@@ -191,6 +191,7 @@ Use this with caution since it is not debugged."
 
 (defcustom edebug-unwrap-results nil
   "Non-nil if Edebug should unwrap results of expressions.
+That is, Edebug will try to remove its own instrumentation from the result.
 This is useful when debugging macros where the results of expressions
 are instrumented expressions.  But don't do this when results might be
 circular or an infinite loop will result."
@@ -2028,7 +2029,10 @@ expressions; a `progn' form will be returned enclosing these forms."
 (def-edebug-spec apply (function-form &rest form))
 (def-edebug-spec funcall (function-form &rest form))
 
-;; FIXME? The manual has a gate here.
+;; FIXME?  The manual uses this form (maybe that's just for illustration?):
+;; (def-edebug-spec let
+;;   ((&rest &or symbolp (gate symbolp &optional form))
+;;    body))
 (def-edebug-spec let
   ((&rest &or (symbolp &optional form) symbolp)
    body))
@@ -4157,6 +4161,8 @@ You must include newlines in FMT to break lines, but one newline is appended."
 ;;; Frequency count and coverage
 
 ;; FIXME should this use overlays instead?
+;; Definitely, IMO.  The current business with undo in
+;; edebug-temp-display-freq-count is horrid.
 (defun edebug-display-freq-count ()
   "Display the frequency count data for each line of the current definition.
 The frequency counts are inserted as comment lines after each line,
@@ -4226,6 +4232,8 @@ reinstrument it."
         (insert "\n")
         (setq i first-index)))))
 
+;; FIXME this does not work very well.  Eg if you press an arrow key,
+;; or make a mouse-click, it fails with "Non-character input-event".
 (defun edebug-temp-display-freq-count ()
   "Temporarily display the frequency count data for the current definition.
 It is removed when you hit any char."
@@ -4235,6 +4243,7 @@ It is removed when you hit any char."
     (undo-boundary)
     (edebug-display-freq-count)
     (setq unread-command-char (read-char))
+    ;; Yuck!  This doesn't seem to work at all for me.
     (undo)))