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

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Wed, 08 Jan 2025 09:44:56 -0800
> 
> Thank you for your implied offer to review my small patch.
> I had not expected so much interest.

I thought you did, actually.

> --- 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'.

I think this kind of details do not belong to doc strings.  If you
think it's very important to point this out to readers of the doc
string, you could include in the doc string a link to the ELisp
reference manual.

> --- 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.

These (and AFAICT all the other properties in this node) should be
indexed.

> +Here is an example using a function to find the definition:

This is a long example with 3 distinct top-level forms in it.  I
suggest to wrap each group in @group..@end @group" to prevent breaking
each group between different pages, which makes them harder to read.

Finally, what about a NEWS entry announcing this new property?