Create new Edebug spec for docstrings and use it in closures

Since (:documentation FORM) can be used to create a docstring
when lexical-binding is on, allow for that possibility in Edebug
specs (bug#24773).
* lisp/emacs-lisp/edebug.el: Define an Edebug spec for docstrings
called lambda-doc and modify the Edebug specs for defun and
defmacro to use it.
(edebug-instrument-function): Check for generic functions first,
to fix bug where edebug-step-in didn't work on methods now that
cl-defgeneric has an Edebug spec.
* lisp/subr.el (lambda): Modify Edebug spec to use lambda-doc.
* lisp/emacs-lisp/cl-generic.el (cl-defgeneric): Add Edebug spec
(bug#27747).
(cl-defmethod): Use lambda-doc in Edebug spec.
* lisp/emacs-lisp/cl-macs.el: Modify Edebug spec for
cl-declarations-or-string to use lambda-doc, and modify Edebug
spec for cl-lambda-expr to use cl-declarations-or-string.
* lisp/emacs-lisp/pcase.el (pcase-lambda): Modify Edebug spec to
use lambda-doc, as well as &define and def-body which are
necessary for using Edebug on code wrapped by lambda.
* lisp/emacs-lisp/generator.el (iter-defun, iter-lambda): Add
Edebug specs.

lisp/emacs-lisp/cl-generic.el

@@ -204,7 +204,16 @@ OPTIONS-AND-METHODS currently understands:
 DEFAULT-BODY, if present, is used as the body of a default method.
 
 \(fn NAME ARGS [DOC-STRING] [OPTIONS-AND-METHODS...] &rest DEFAULT-BODY)"
-  (declare (indent 2) (doc-string 3))
+  (declare (indent 2) (doc-string 3)
+           (debug
+            (&define name cl-lambda-list lambda-doc
+                     [&rest [&or
+                             ("declare" &rest sexp)
+                             (":argument-precedence-order" &rest sexp)
+                             (&define ":method" [&rest atom]
+                                      cl-generic-method-args lambda-doc
+                                      def-body)]]
+                     def-body)))
   (let* ((doc (if (stringp (car-safe options-and-methods))
                   (pop options-and-methods)))
          (declarations nil)
@@ -422,7 +431,7 @@ The set of acceptable TYPEs (also called \"specializers\") is defined
                                     ; Like in CLOS spec, we support
                                     ; any non-list values.
              cl-generic-method-args     ; arguments
-             [ &optional stringp ]      ; documentation string
+             lambda-doc                 ; documentation string
              def-body)))                ; part to be debugged
   (let ((qualifiers nil))
     (while (not (listp args))

lisp/emacs-lisp/cl-macs.el

@@ -190,7 +190,7 @@ The name is made by appending a number to PREFIX, default \"T\"."
   (&rest ("cl-declare" &rest sexp)))
 
 (def-edebug-spec cl-declarations-or-string
-  (&or stringp cl-declarations))
+  (&or lambda-doc cl-declarations))
 
 (def-edebug-spec cl-lambda-list
   (([&rest arg]
@@ -447,8 +447,8 @@ more details.
 
 (def-edebug-spec cl-lambda-expr
   (&define ("lambda" cl-lambda-list
-	    ;;cl-declarations-or-string
-	    ;;[&optional ("interactive" interactive)]
+	    cl-declarations-or-string
+	    [&optional ("interactive" interactive)]
 	    def-body)))
 
 ;; Redefine function-form to also match cl-function

lisp/emacs-lisp/edebug.el

@@ -1986,15 +1986,14 @@ expressions; a `progn' form will be returned enclosing these forms."
 (def-edebug-spec defvar (symbolp &optional form stringp))
 
 (def-edebug-spec defun
-  (&define name lambda-list
-	   [&optional stringp]
+  (&define name lambda-list lambda-doc
            [&optional ("declare" &rest sexp)]
 	   [&optional ("interactive" interactive)]
 	   def-body))
 (def-edebug-spec defmacro
   ;; FIXME: Improve `declare' so we can Edebug gv-expander and
   ;; gv-setter declarations.
-  (&define name lambda-list [&optional stringp]
+  (&define name lambda-list lambda-doc
            [&optional ("declare" &rest sexp)] def-body))
 
 (def-edebug-spec arglist lambda-list)  ;; deprecated - use lambda-list.
@@ -2005,6 +2004,10 @@ expressions; a `progn' form will be returned enclosing these forms."
     &optional ["&rest" arg]
     )))
 
+(def-edebug-spec lambda-doc
+  (&optional [&or stringp
+                  (&define ":documentation" def-form)]))
+
 (def-edebug-spec interactive
   (&optional &or stringp def-form))
 
@@ -3204,15 +3207,6 @@ generated symbols for methods.  If a function or method to
 instrument cannot be found, signal an error."
   (let ((func-marker (get func 'edebug)))
     (cond
-     ((and (markerp func-marker) (marker-buffer func-marker))
-      ;; It is uninstrumented, so instrument it.
-      (with-current-buffer (marker-buffer func-marker)
-	(goto-char func-marker)
-	(edebug-eval-top-level-form)
-        (list func)))
-     ((consp func-marker)
-      (message "%s is already instrumented." func)
-      (list func))
      ((cl-generic-p func)
       (let ((method-defs (cl--generic-method-files func))
             symbols)
@@ -3227,6 +3221,15 @@ instrument cannot be found, signal an error."
               (edebug-eval-top-level-form)
               (push (edebug-form-data-symbol) symbols))))
         symbols))
+     ((and (markerp func-marker) (marker-buffer func-marker))
+      ;; It is uninstrumented, so instrument it.
+      (with-current-buffer (marker-buffer func-marker)
+	(goto-char func-marker)
+	(edebug-eval-top-level-form)
+        (list func)))
+     ((consp func-marker)
+      (message "%s is already instrumented." func)
+      (list func))
      (t
       (let ((loc (find-function-noselect func t)))
 	(unless (cdr loc)

lisp/emacs-lisp/generator.el

@@ -680,7 +680,8 @@ sub-iterator function returns via `iter-end-of-sequence'."
 When called as a function, NAME returns an iterator value that
 encapsulates the state of a computation that produces a sequence
 of values.  Callers can retrieve each value using `iter-next'."
-  (declare (indent defun))
+  (declare (indent defun)
+           (debug (&define name lambda-list lambda-doc def-body)))
   (cl-assert lexical-binding)
   (let* ((parsed-body (macroexp-parse-body body))
          (declarations (car parsed-body))
@@ -692,7 +693,8 @@ of values.  Callers can retrieve each value using `iter-next'."
 (defmacro iter-lambda (arglist &rest body)
   "Return a lambda generator.
 `iter-lambda' is to `iter-defun' as `lambda' is to `defun'."
-  (declare (indent defun))
+  (declare (indent defun)
+           (debug (&define lambda-list lambda-doc def-body)))
   (cl-assert lexical-binding)
   `(lambda ,arglist
      ,(cps-generate-evaluator body)))

lisp/emacs-lisp/pcase.el

@@ -226,7 +226,7 @@ I.e. accepts the usual &optional and &rest keywords, but every
 formal argument can be any pattern accepted by `pcase' (a mere
 variable name being but a special case of it)."
   (declare (doc-string 2) (indent defun)
-           (debug ((&rest pcase-PAT) body)))
+           (debug (&define (&rest pcase-PAT) lambda-doc def-body)))
   (let* ((bindings ())
          (parsed-body (macroexp-parse-body body))
          (args (mapcar (lambda (pat)

lisp/subr.el

@@ -110,8 +110,7 @@ BODY should be a list of Lisp expressions.
 
 \(fn ARGS [DOCSTRING] [INTERACTIVE] BODY)"
   (declare (doc-string 2) (indent defun)
-           (debug (&define lambda-list
-                           [&optional stringp]
+           (debug (&define lambda-list lambda-doc
                            [&optional ("interactive" interactive)]
                            def-body)))
   ;; Note that this definition should not use backquotes; subr.el should not