[Emacs-diffs] /srv/bzr/emacs/trunk r107715: Edebug doc fixes

[Glenn Morris]

------------------------------------------------------------
revno: 107715
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Sat 2012-03-31 12:58:05 -0700
message:
  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.
modified:
  admin/FOR-RELEASE
  doc/lispref/ChangeLog
  doc/lispref/edebug.texi
  lisp/ChangeLog
  lisp/emacs-lisp/edebug.el

=== modified file 'admin/FOR-RELEASE'
--- a/admin/FOR-RELEASE 2012-03-30 16:31:24 +0000
+++ b/admin/FOR-RELEASE 2012-03-31 19:58:05 +0000
@@ -183,7 +183,7 @@
 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 @@
 customize.texi    cyd
 debugging.texi    cyd
 display.texi      cyd
-edebug.texi
+edebug.texi       rgm
 elisp.texi
 errors.texi       rgm
 eval.texi         cyd

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2012-03-31 10:27:04 +0000
+++ b/doc/lispref/ChangeLog     2012-03-31 19:58:05 +0000
@@ -1,3 +1,9 @@
+2012-03-31  Glenn Morris  <address@hidden>
+
+       * edebug.texi (Instrumenting Macro Calls):
+       Mention defining macros at instrumentation time.
+       (Edebug Options): Mention edebug-unwrap-results.
+
 2012-03-31  Eli Zaretskii  <address@hidden>
 
        * text.texi (Special Properties): Clarify the description of the

=== modified file 'doc/lispref/edebug.texi'
--- a/doc/lispref/edebug.texi   2012-03-31 01:09:30 +0000
+++ b/doc/lispref/edebug.texi   2012-03-31 19:58:05 +0000
@@ -1113,6 +1113,15 @@
 arguments.  @xref{Defining Macros}, for more explanation of
 the @code{declare} form.
 
address@hidden See eg http://debbugs.gnu.org/10577
address@hidden FIXME  Maybe there should be an Edebug option to get it to
address@hidden automatically load the entire source file containing the function
address@hidden 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 @@
 of them match, nothing is matched, but the @code{&not} specification
 succeeds.
 
address@hidden FIXME &key?
+
 @item &define
 @c @kindex &define @r{(Edebug)}
 Indicates that the specification is for a defining form.  The defining
@@ -1422,7 +1433,15 @@
 optional expression.  In the specification below, notice the @code{gate}
 inside of the sublist to prevent backtracking once a sublist is found.
 
address@hidden FIXME? The actual definition in edebug.el does not have a gate.
address@hidden
address@hidden FIXME?  The actual definition in edebug.el looks like this (and 
always
address@hidden has AFAICS).  In fact, nothing in edebug.el uses gate.  So maybe
address@hidden this is just an example for illustration?
+(def-edebug-spec let
+  ((&rest
+    &or (symbolp &optional form) symbolp)
+   body))
address@hidden ignore
 @example
 (def-edebug-spec let
   ((&rest
@@ -1566,7 +1585,28 @@
 @xref{Edebug Execution Modes}.
 @end defopt
 
address@hidden FIXME edebug-unwrap-results
address@hidden edebug-unwrap-results
+If address@hidden, 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:
+
address@hidden FIXME find a less silly example.
address@hidden
+(defmacro test () "Edebug example."
+  (if (symbol-function 'fac)
+      @dots{}))
address@hidden 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
address@hidden and @code{edebug-before} forms, which can make it
+difficult to see the ``actual'' result.  If
address@hidden is address@hidden, Edebug tries to remove
+these forms from the result.
address@hidden defopt
 
 @defopt edebug-on-error
 Edebug binds @code{debug-on-error} to this value, if

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2012-03-30 16:49:29 +0000
+++ b/lisp/ChangeLog    2012-03-31 19:58:05 +0000
@@ -1,3 +1,7 @@
+2012-03-31  Glenn Morris  <address@hidden>
+
+       * emacs-lisp/edebug.el (edebug-unwrap-results): Doc fix.
+
 2012-03-30  Thierry Volpiatto  <address@hidden>
 
        * dired-aux.el (dired-copy-file-recursive, dired-create-files):

=== modified file 'lisp/emacs-lisp/edebug.el'
--- a/lisp/emacs-lisp/edebug.el 2012-01-19 07:21:25 +0000
+++ b/lisp/emacs-lisp/edebug.el 2012-03-31 19:58:05 +0000
@@ -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 <address@hidden>
 ;; Maintainer: FSF
@@ -191,6 +191,7 @@
 
 (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 @@
 (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 @@
 ;;; 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 @@
        (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 @@
     (undo-boundary)
     (edebug-display-freq-count)
     (setq unread-command-char (read-char))
+    ;; Yuck!  This doesn't seem to work at all for me.
     (undo)))