a property "definition-type" would help find macro-defined tests

a property "definition-type" would help find macro-defined tests

[Stephen Gildea]

The find-function feature of Emacs cannot find "ert-deftest"
forms generated by a macro.  (The find-func library does look
through macro expansions in its search, but the search is too
specific to find "ert-deftest" forms.)

Function "find-function-search-for-symbol" is passed a "type"
for the thing to look for, but that type is based on the
caller's idea of what the thing is.  We need a way to say what
the definer thinks the definition looks like.

The existing property "definition-name" isn't helpful here
because often the call to a test-defining macro contains test
data only.

I propose a new property, "definition-type", that a macro could
put on a symbol.  If present, "find-function-search-for-symbol"
would use that type instead of the passed-in type.

With this enhancement, any subsystem that uses a macro to
define objects could
 - have the macro set property "definition-type" on the
   symbols it defines, and
 - add an entry to "find-function-regexp-alist" saying how to
   find the new type.

Concretely, here's the code change I'm proposing:

diff --git a/lisp/emacs-lisp/find-func.el b/lisp/emacs-lisp/find-func.el
index f3ddf9f81c9..df1eb8deae0 100644
--- a/lisp/emacs-lisp/find-func.el
+++ b/lisp/emacs-lisp/find-func.el
@@ -409,6 +409,8 @@ find-function-search-for-symbol
   ;; Some functions are defined as part of the construct
   ;; that defines something else.
   (while (and (symbolp symbol) (get symbol 'definition-name))
     (setq symbol (get symbol 'definition-name)))
+  (setq type (or (get symbol 'definition-type)
+                 type))
   (if (string-match "\\`src/\\(.*\\.\\(c\\|m\\)\\)\\'" library)
       (find-function-C-source symbol (match-string 1 library) type)


Does this seem like a generally useful addition?

 < Stephen

Re: a property "definition-type" would help find macro-defined tests

[Richard Lawrence]

Stephen Gildea <stepheng+emacs@gildea.com> writes:

> I propose a new property, "definition-type", that a macro could
> put on a symbol.  If present, "find-function-search-for-symbol"
> would use that type instead of the passed-in type.
>
> With this enhancement, any subsystem that uses a macro to
> define objects could
>  - have the macro set property "definition-type" on the
>    symbols it defines, and
>  - add an entry to "find-function-regexp-alist" saying how to
>    find the new type.
> ...
> Does this seem like a generally useful addition?

As someone who's recently written a macro to define a bunch of tests,
and was then mildly frustrated that e.g.
ert-results-pop-to-should-forms-for-test-at-point didn't even come close
to finding the definitions, something like this sounds useful to me!

I wonder if there isn't already some better way to do this, though, that
find-function-search-for-symbol could make use of. I got curious and
briefly went down a rabbit hole looking for one, since there are
functions like `symbol-file' and the intriguing `symbol-with-pos-pos'.
The latter extracts a position from a mysterious-to-me entity called a
"symbol with position". Perhaps there's *already* a standard way to tag
a symbol with a position in a source file somehow, and what's needed is
to encourage macro writers to use it, and to adjust the find-function*
functions to look for it? Someone who knows more than me about Emacs
internals could shed more light here...but anyway, if there isn't, I
like the idea!

Best,
Richard

Re: a property "definition-type" would help find macro-defined tests

[Stephen Gildea]

In the two weeks since posting the proposal for a new property
"definition-type" (find-function-search-for-symbol would use
it instead of the passed-in type to find a definition), I have
received only one response, an enthusiastic "yes, please!"

So unless I hear any objections now, I will go ahead and add this feature.

In addition to the small code and doc-string changes to
find-function-search-for-symbol, I will expand the Emacs Lisp
manual's documentation of definition-name in node "Standard
Properties" to include definition-type.  I will also mention
definition-type, with cross reference, in "defining functions
dynamically" and, in the ERT manual, in "How to Write Tests".

 < Stephen

Re: a property "definition-type" would help find macro-defined tests

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Tue, 07 Jan 2025 14:13:38 -0800
> 
> In the two weeks since posting the proposal for a new property
> "definition-type" (find-function-search-for-symbol would use
> it instead of the passed-in type to find a definition), I have
> received only one response, an enthusiastic "yes, please!"
> 
> So unless I hear any objections now, I will go ahead and add this feature.
> 
> In addition to the small code and doc-string changes to
> find-function-search-for-symbol, I will expand the Emacs Lisp
> manual's documentation of definition-name in node "Standard
> Properties" to include definition-type.  I will also mention
> definition-type, with cross reference, in "defining functions
> dynamically" and, in the ERT manual, in "How to Write Tests".

Please post the full patch before you install it.  Your original
message only shows a very small part of the tip of this particular
iceberg, which makes it hard to provide useful feedback.

Thanks.

Re: a property "definition-type" would help find macro-defined tests

[Stephen Gildea]

[-- Attachment #1: Type: text/plain, Size: 349 bytes --]

Eli Zaretskii <eliz@gnu.org> wrote:

>   Please post the full patch before you install it.  Your original
>   message only shows a very small part of the tip of this particular
>   iceberg, which makes it hard to provide useful feedback.

Thank you for your implied offer to review my small patch.
I had not expected so much interest.

 < Stephen



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: new property definition-type --]
[-- Type: text/x-diff, Size: 6709 bytes --]

diff --git a/lisp/emacs-lisp/find-func.el b/lisp/emacs-lisp/find-func.el
index 0837b37023e..8b6c7fc23cf 100644
--- a/lisp/emacs-lisp/find-func.el
+++ b/lisp/emacs-lisp/find-func.el
@@ -400,9 +400,13 @@ find-function-search-for-symbol
 Visit the library in a buffer, and return a cons cell (BUFFER . POSITION),
 or just (BUFFER . nil) if the definition can't be found in the file.
 
-If TYPE is nil, look for a function definition.
-Otherwise, TYPE specifies the kind of definition,
-and it is interpreted via `find-function-regexp-alist'.
+If TYPE is nil, look for a function definition, otherwise, TYPE specifies
+the kind of definition.  If SYMBOL has a property `definition-type',
+the property value is used instead of TYPE. (Macros that define objects
+can put a `definition-type' on the symbol to help find an
+unusual-looking definition site.)
+TYPE is interpreted via `find-function-regexp-alist'.
+
 The search is done in the source for library LIBRARY."
   (if (null library)
       (error "Don't know where `%s' is defined" symbol))
@@ -410,6 +414,8 @@ find-function-search-for-symbol
   ;; that defines something else.
   (while (and (symbolp symbol) (get symbol 'definition-name))
     (setq symbol (get symbol 'definition-name)))
+  (setq type (or (get symbol 'definition-type)
+                 type))
   (if (string-match "\\`src/\\(.*\\.\\(c\\|m\\)\\)\\'" library)
       (find-function-C-source symbol (match-string 1 library) type)
     (when (string-match "\\.el\\(c\\)\\'" library)
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 24b4e892024..6590d6be93f 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -536,9 +536,16 @@ Standard Properties
 related functions.  @xref{Variable Definitions}.
 
 @item definition-name
-This property is used to find the definition of a symbol in the source
-code, when it might be hard to find the definition by textual search
-of the source file.  For example, a @code{define-derived-mode}
+@itemx definition-type
+These properties help find the definition of a symbol in the source
+code when it might be hard to find the definition by textual search
+of the source file.
+The Emacs Help commands such as @kbd{C-h f} (@pxref{Help,,,
+emacs, The GNU Emacs Manual}) use these properties to show the definition
+of a symbol via a button in the @file{*Help*} buffer where the
+symbol's documentation is shown.
+
+For example, a @code{define-derived-mode}
 (@pxref{Derived Modes}) might define a mode-specific function or a
 variable implicitly; or your Lisp program might generate a run-time
 call to @code{defun} to define a function (@pxref{Defining
@@ -547,10 +554,50 @@ Standard Properties
 be found by textual search and whose code defines the original symbol.
 In the example with @code{define-derived-mode}, the value of this
 property of the functions and variables it defines should be the mode
-symbol.  The Emacs Help commands such as @kbd{C-h f} (@pxref{Help,,,
-emacs, The GNU Emacs Manual}) use this property to show the definition
-of a symbol via a button in the @file{*Help*} buffer where the
-symbol's documentation is shown.
+symbol.
+
+In some cases, the definition cannot be found by looking for the
+definition of another symbol.  For example, a test file might use a
+macro to generate calls to @code{ert-deftest}
+(@pxref{,,,ert, ERT: Emacs Lisp Regression Testing}) where the code
+is boiler plate and only varying data need to be passed in.
+In such cases, the @code{definition-type} property of the symbol can
+be a symbol that has an entry in @code{find-function-regexp-alist}
+telling how to find the definition of symbols of this type.
+
+In the example of a macro defining calls to @code{ert-deftest},
+the macro could put the property @code{definition-type} on each
+test defined.  The file defining the macro would also define a
+definition-finding function or regexp and add it to
+@code{find-function-regexp-alist} after that variable is loaded.
+Here is an example using a function to find the definition:
+
+@example
+(defmacro define-foo-test (data)
+  "Define a test of the foo system using DATA."
+  (declare (debug (&rest sexp)))
+  (let ((test-name (intern (concat ...))))
+    `(progn
+      (put ',test-name 'definition-type 'foo-test-type)
+      (ert-deftest ,test-name ()
+        ,(concat "Test foo with " ...)
+        ...))))
+
+(defun foo-find-test-def-function (test-name)
+  "Search for the `define-foo-test' call defining TEST-NAME.
+Return non-nil if the definition is found."
+  (save-match-data
+    (let ((regexp ...))
+      (save-restriction
+        (widen)
+        (goto-char (point-min))
+        (re-search-forward regexp nil t)))))
+
+(with-eval-after-load "find-func"
+  (add-to-list
+   'find-function-regexp-alist
+   '(foo-test-type . foo-find-test-def-function)))
+@end example
 
 @item disabled
 If the value is non-@code{nil}, the named function is disabled as a
diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index c659ecaf3f8..8e183e7382b 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -752,9 +752,9 @@ Defining Functions
 buffer a button to jump to the function's definition, might be unable
 to find the source code because generating a function dynamically
 usually looks very different from the usual static calls to
-@code{defun}.  You can make the job of finding the code which
+@code{defun}.  You can make the job of finding the code that
 generates such functions easier by using the @code{definition-name}
-property, @pxref{Standard Properties}.
+or @code{definition-type} property, @pxref{Standard Properties}.
 
 @cindex override existing functions
 @cindex redefine existing functions
diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi
index 9e60647f3ba..c8aac971ec7 100644
--- a/doc/misc/ert.texi
+++ b/doc/misc/ert.texi
@@ -518,9 +518,14 @@ How to Write Tests
 with @code{eval-defun} or @code{compile-defun}, or you can save the
 file and load it, optionally byte-compiling it first.
 
-Just like @code{find-function} is only able to find where a function
-was defined if the function was loaded from a file, ERT is only able
-to find where a test was defined if the test was loaded from a file.
+Just like @code{find-function} is able to find where a function was
+defined only if the function was loaded from a file, ERT is able to
+find where a test was defined only if the test was loaded from a file.
+
+If the test definition is generated by a macro, the macro may want to
+help ERT find the defining call to the macro by putting the property
+@code{definition-type} on the test name.
+@xref{Standard Properties,,,elisp, GNU Emacs Lisp Reference Manual}.
 
 
 @menu