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?

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

[Stephen Gildea]

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

I have made the changes requested and one other:

 - added a NEWS entry

 - find-function-search-for-symbol doc string additions
   trimmed of detail that is available from the manual.

 - in the manual, added an index entry for the new property,
   definition-type, and for all the existing properties that
   did not have index entries (which was most of them).

 - in the code example, put each top-level form in @group.

 - new in this version of the patch: added a cross reference
   from where Coding Conventions discusses how to write macros
   that define functions.



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

diff --git a/etc/NEWS b/etc/NEWS
index 37e5669b139..50928cd9264 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1137,6 +1137,13 @@ It offers a more concise way to create a completion table with metadata.
 +++
 ** 'all-completions' and 'unintern' no longer support old calling conventions.
 
++++
+** New property 'definition-type' used by find-function and friends.
+Macros that define an object in a way makes the object's name and the
+macro call site defining the object hard to associate can put the
+property 'definition-type' on the object's name to provide instructions
+for finding the definition.
+
 \f
 * Changes in Emacs 31.1 on Non-Free Operating Systems
 
diff --git a/lisp/emacs-lisp/find-func.el b/lisp/emacs-lisp/find-func.el
index 0837b37023e..643b6aba2a6 100644
--- a/lisp/emacs-lisp/find-func.el
+++ b/lisp/emacs-lisp/find-func.el
@@ -400,9 +400,12 @@ 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.
+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 +413,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..7990e2a8f75 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -510,35 +510,54 @@ Standard Properties
 
 @table @code
 @item :advertised-binding
+@cindex @code{:advertised-binding} property
 This property value specifies the preferred key binding, when showing
 documentation, for the named function.  @xref{Keys in Documentation}.
 
 @item char-table-extra-slots
+@cindex @code{char-table-extra-slots} property
 The value, if non-@code{nil}, specifies the number of extra slots in
 the named char-table type.  @xref{Char-Tables}.
 
 @item customized-face
+@cindex @code{customized-face} property
 @itemx face-defface-spec
+@cindex @code{face-defface-spec} property
 @itemx saved-face
+@cindex @code{saved-face} property
 @itemx theme-face
+@cindex @code{theme-face} property
 These properties are used to record a face's standard, saved,
 customized, and themed face specs.  Do not set them directly; they are
 managed by @code{defface} and related functions.  @xref{Defining
 Faces}.
 
 @item customized-value
+@cindex @code{customized-value} property
 @itemx saved-value
+@cindex @code{saved-value} property
 @itemx standard-value
+@cindex @code{standard-value} property
 @itemx theme-value
+@cindex @code{theme-value} property
 These properties are used to record a customizable variable's standard
 value, saved value, customized-but-unsaved value, and themed values.
 Do not set them directly; they are managed by @code{defcustom} and
 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}
+@cindex @code{definition-name} property
+@itemx definition-type
+@cindex @code{definition-type} property
+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,43 +566,101 @@ 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
+@group
+(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 " ...)
+        ...))))
+@end group
+@end example
+
+@example
+@group
+(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)))))
+@end group
+@end example
+
+@example
+@group
+(with-eval-after-load "find-func"
+  (add-to-list
+   'find-function-regexp-alist
+   '(foo-test-type . foo-find-test-def-function)))
+@end group
+@end example
 
 @item disabled
+@cindex @code{disabled} property
 If the value is non-@code{nil}, the named function is disabled 

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Thu, 09 Jan 2025 20:47:28 -0800
> 
> I have made the changes requested and one other:
> 
>  - added a NEWS entry
> 
>  - find-function-search-for-symbol doc string additions
>    trimmed of detail that is available from the manual.
> 
>  - in the manual, added an index entry for the new property,
>    definition-type, and for all the existing properties that
>    did not have index entries (which was most of them).
> 
>  - in the code example, put each top-level form in @group.
> 
>  - new in this version of the patch: added a cross reference
>    from where Coding Conventions discusses how to write macros
>    that define functions.

Thanks.  A few remaining nits below.

> ++++
> +** New property 'definition-type' used by find-function and friends.

"find-function" should be quoted 'like this'.

> +Macros that define an object in a way makes the object's name and the
                                        ^
I think "that" is missing there.

>  @item :advertised-binding
> +@cindex @code{:advertised-binding} property

I think all these index entries should use "symbol property" instead
of the more general "property", to distinguish them from other kinds
of properties we have in Emacs.

Also, please move the index entries to _before_ the corresponding
@item's, so that following the index search will place point on the
line produced from the @item, not the line after it.

>  @item customized-face
> +@cindex @code{customized-face} property
>  @itemx face-defface-spec
> +@cindex @code{face-defface-spec} property
>  @itemx saved-face
> +@cindex @code{saved-face} property
>  @itemx theme-face
> +@cindex @code{theme-face} property

I generally find it to be more useful to have all the index entries
together before the @item..@itemx...@item lines.  That way, when the
readers follow the index search, they see names of all the items
discussed in the following text, which I think is better.

> +Here is an example using a function to find the definition:
> +
> +@example
> +@group
> +(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 " ...)
> +        ...))))
> +@end group
> +@end example
> +
> +@example
> +@group

You don't need to @end example when you @end group.  Instead, have
only one @example..@end example around all the groups.  The
"@group..@end group" will prevent Texinfo from inserting a page break
inside the groups, so page breaks will be only between the groups.

Thanks again for working on this.