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.

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

[Stephen Gildea]

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

Eli Zaretskii <eliz@gnu.org> wrote:

>   Thanks.  A few remaining nits below.
>   ...

I will fix these items and commit the result.

But first ...

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

Some of these symbol properties are missing index entries at
the point of their main discussion, or they have an entry with
a different format.  Adding or changing index entries in the
list of standard properties then creates a separate index
entry, bloating the index and making it more confusing to use.
I also discovered some symbol properties that were missing an
entry in this list.

I took it on myself to fix these discrepancies.

This is getting to be a bigger change, so I want to make it a
separate commit.  Here is what it looks like.

 < Stephen


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: better indexing of symbol properties --]
[-- Type: text/x-diff, Size: 6710 bytes --]

diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 24b4e892024..5d5804179d3 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -509,32 +509,43 @@ Standard Properties
 symbol; similarly for ``the named variable'' etc.
 
 @table @code
+@cindex @code{:advertised-binding} (symbol property)
 @item :advertised-binding
 This property value specifies the preferred key binding, when showing
 documentation, for the named function.  @xref{Keys in Documentation}.
 
+@cindex @code{char-table-extra-slots} (symbol property)
 @item char-table-extra-slots
 The value, if non-@code{nil}, specifies the number of extra slots in
 the named char-table type.  @xref{Char-Tables}.
 
+@cindex @code{customized-face} (face symbol property)
 @item customized-face
+@cindex @code{face-defface-spec} (face symbol property)
 @itemx face-defface-spec
+@cindex @code{saved-face} (face symbol property)
 @itemx saved-face
+@cindex @code{theme-face} (face symbol property)
 @itemx theme-face
 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}.
 
+@cindex @code{customized-value} (symbol property)
 @item customized-value
+@cindex @code{saved-value} (symbol property)
 @itemx saved-value
+@cindex @code{standard-value} (symbol property)
 @itemx standard-value
+@cindex @code{theme-value} (symbol property)
 @itemx theme-value
 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}.
 
+@cindex @code{definition-name} (symbol property)
 @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
@@ -552,62 +563,92 @@ Standard Properties
 of a symbol via a button in the @file{*Help*} buffer where the
 symbol's documentation is shown.
 
+@cindex @code{disabled} (symbol property)
 @item disabled
 If the value is non-@code{nil}, the named function is disabled as a
 command.  @xref{Disabling Commands}.
 
+@cindex @code{face-documentation} (face symbol property)
 @item face-documentation
 The value stores the documentation string of the named face.  This is
 set automatically by @code{defface}.  @xref{Defining Faces}.
 
+@cindex @code{history-length} (symbol property)
 @item history-length
 The value, if non-@code{nil}, specifies the maximum minibuffer history
 length for the named history list variable.  @xref{Minibuffer
 History}.
 
+@cindex @code{interactive-form} (symbol property)
 @item interactive-form
 The value is an interactive form for the named function.  Normally,
 you should not set this directly; use the @code{interactive} special
 form instead.  @xref{Interactive Call}.
 
+@cindex @code{interactive-only} (symbol property)
+@item interactive-only
+If the value is non-@code{nil}, the named function should not be called
+from Lisp.  The value is an error string or the function to call
+instead.  @xref{Defining Commands}.
+
+@cindex @code{menu-alias} (symbol property)
+@item menu-alias
+If non-nil, this symbol is an alias menu entry, and its own key binding
+should not be shown.  @xref{Alias Menu Items}.
+
+@cindex @code{menu-enable} (symbol property)
 @item menu-enable
 The value is an expression for determining whether the named menu item
 should be enabled in menus.  @xref{Simple Menu Items}.
 
+@cindex @code{mode-class} (symbol property)
 @item mode-class
 If the value is @code{special}, the named major mode is special.
 @xref{Major Mode Conventions}.
 
+@cindex @code{ignored-mouse-command} (symbol property)
+@item ignored-mouse-command
+@cindex @code{mouse-1-menu-command} (symbol property)
+@itemx mouse-1-menu-command
+These properties affect how commands bound to @code{down-mouse-1} behave.
+@xref{Touchscreen Events}.
+
+@cindex @code{permanent-local} (symbol property)
 @item permanent-local
 If the value is non-@code{nil}, the named variable is a buffer-local
 variable whose value should not be reset when changing major modes.
 @xref{Creating Buffer-Local}.
 
+@cindex @code{permanent-local-hook} (symbol property)
 @item permanent-local-hook
 If the value is non-@code{nil}, the named function should not be
 deleted from the local value of a hook variable when changing major
 modes.  @xref{Setting Hooks}.
 
+@cindex @code{pure} (symbol property)
 @item pure
-@cindex @code{pure} property
 If the value is non-@code{nil}, the named function is considered to be
 pure (@pxref{What Is a Function}).  Calls with constant arguments can
 be evaluated at compile time.  This may shift run time errors to
 compile time.  Not to be confused with pure storage (@pxref{Pure
 Storage}).
 
+@cindex @code{risky-local-variable} (symbol property)
 @item risky-local-variable
 If the value is non-@code{nil}, the named variable is considered risky
 as a file-local variable.  @xref{File Local Variables}.
 
+@cindex @code{safe-function} (symbol property)
 @item safe-function
 If the value is non-@code{nil}, the named function is considered
 generally safe for evaluation.  @xref{Function Safety}.
 
+@cindex @code{safe-local-eval-function} (symbol property)
 @item safe-local-eval-function
 If the value is non-@code{nil}, the named function is safe to call in
 file-local evaluation forms.  @xref{File Local Variables}.
 
+@cindex @code{safe-local-variable} (symbol property)
 @item safe-local-variable
 The value specifies a function for determining safe file-local values
 for the named variable.  @xref{File Local Variables}.  Since this
@@ -615,8 +656,8 @@ Standard Properties
 efficient and should ideally not lead to loading any libraries to
 determine the safeness (e.g., it should not be an autoloaded function).
 
+@cindex @code{side-effect-free} (symbol property)
 @item side-effect-free
-@cindex @code{side-effect-free} property
 A non-@code{nil} value indicates that the named function is free of
 side effects (@pxref{What Is a Function}), so the byte compiler may
 ignore a call whose value is unused.  If the property's value is
@@ -624,21 +665,25 @@ Standard Properties
 calls.  In addition to byte compiler optimizations, this property is
 also used for determining function safety (@pxref{Function Safety}).
 
+@cindex @code{important-return-value} (symbol property)
 @item important-return-value
-@cindex @code{important-return-value} property
 A non-@code{nil} value makes the byte compiler warn about code that
 calls the named function without using its returne

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Sat, 11 Jan 2025 11:43:55 -0800
> 
> Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >   Thanks.  A few remaining nits below.
> >   ...
> 
> I will fix these items and commit the result.

OK, but please see below.

> But first ...
> 
> >   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.
> 
> Some of these symbol properties are missing index entries at
> the point of their main discussion, or they have an entry with
> a different format.  Adding or changing index entries in the
> list of standard properties then creates a separate index
> entry, bloating the index and making it more confusing to use.

The index entry should be only at the place of the main description of
the symbol property, if there is such a place.  Duplicate index
entries are not a good thing, and an index entry leading to the list
is redundant when there's an index entry at the place of the main
description.  I'm sorry I didn't know that when I asked you to add
index entries.

> I also discovered some symbol properties that were missing an
> entry in this list.
> 
> I took it on myself to fix these discrepancies.

Thanks.

> This is getting to be a bigger change, so I want to make it a
> separate commit.  Here is what it looks like.

It's okay, but please remove the duplicate index entries, leaving only
those at the place of the main description of each property.  Again,
sorry for not noticing this before.

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

[Stephen Gildea]

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

Eli Zaretskii <eliz@gnu.org> wrote:

>   The index entry should be only at the place of the main description of
>   the symbol property, if there is such a place.  Duplicate index
>   entries are not a good thing....

Okay, I understand the user experience you're trying to create.

I still find we need more index entries, but not as many as I thought.

Here's the latest version of the indexing updates.

The most notable change here is that I moved the index of
'interactive-form' from node "Interactive Call" to "Using
Interactive", which I thought gave a more detailed explanation.

 < Stephen


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: better indexng of symbol properties, v2 --]
[-- Type: text/x-diff, Size: 6995 bytes --]

diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 24b4e892024..acd55fcbb81 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -535,6 +535,7 @@ Standard Properties
 Do not set them directly; they are managed by @code{defcustom} and
 related functions.  @xref{Variable Definitions}.
 
+@cindex @code{definition-name} (symbol property)
 @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
@@ -565,10 +566,27 @@ Standard Properties
 length for the named history list variable.  @xref{Minibuffer
 History}.
 
+@cindex @code{important-return-value} (symbol property)
+@item important-return-value
+A non-@code{nil} value makes the byte compiler warn about code that
+calls the named function without using its returned value.  This is
+useful for functions where doing so is likely to be a mistake.
+This property is normally added to a function with @code{declare}
+(@pxref{Declare Form}).
+
 @item interactive-form
 The value is an interactive form for the named function.  Normally,
 you should not set this directly; use the @code{interactive} special
-form instead.  @xref{Interactive Call}.
+form instead.  @xref{Using Interactive}.
+
+@item interactive-only
+If the value is non-@code{nil}, the named function should not be called
+from Lisp.  The value is an error string or the function to call
+instead.  @xref{Defining Commands}.
+
+@item menu-alias
+If non-nil, this symbol is an alias menu entry, and its own key binding
+should not be shown.  @xref{Alias Menu Items}.
 
 @item menu-enable
 The value is an expression for determining whether the named menu item
@@ -578,6 +596,11 @@ Standard Properties
 If the value is @code{special}, the named major mode is special.
 @xref{Major Mode Conventions}.
 
+@item ignored-mouse-command
+@itemx mouse-1-menu-command
+These properties affect how commands bound to @code{down-mouse-1} behave.
+@xref{Touchscreen Events}.
+
 @item permanent-local
 If the value is non-@code{nil}, the named variable is a buffer-local
 variable whose value should not be reset when changing major modes.
@@ -588,18 +611,20 @@ Standard Properties
 deleted from the local value of a hook variable when changing major
 modes.  @xref{Setting Hooks}.
 
+@cindex @code{pure} (symbol property)
 @item pure
-@cindex @code{pure} property
 If the value is non-@code{nil}, the named function is considered to be
 pure (@pxref{What Is a Function}).  Calls with constant arguments can
 be evaluated at compile time.  This may shift run time errors to
-compile time.  Not to be confused with pure storage (@pxref{Pure
-Storage}).
+compile time.  This property is normally added to a function with
+@code{declare} (@pxref{Declare Form}).  Not to be confused with pure
+storage (@pxref{Pure Storage}).
 
 @item risky-local-variable
 If the value is non-@code{nil}, the named variable is considered risky
 as a file-local variable.  @xref{File Local Variables}.
 
+@cindex @code{safe-function} (symbol property)
 @item safe-function
 If the value is non-@code{nil}, the named function is considered
 generally safe for evaluation.  @xref{Function Safety}.
@@ -610,25 +635,18 @@ Standard Properties
 
 @item safe-local-variable
 The value specifies a function for determining safe file-local values
-for the named variable.  @xref{File Local Variables}.  Since this
-value is consulted when loading files, the function should be
-efficient and should ideally not lead to loading any libraries to
-determine the safeness (e.g., it should not be an autoloaded function).
+for the named variable.  @xref{File Local Variables}.
 
+@cindex @code{side-effect-free} (symbol property)
 @item side-effect-free
-@cindex @code{side-effect-free} property
 A non-@code{nil} value indicates that the named function is free of
 side effects (@pxref{What Is a Function}), so the byte compiler may
 ignore a call whose value is unused.  If the property's value is
 @code{error-free}, the byte compiler may even delete such unused
 calls.  In addition to byte compiler optimizations, this property is
 also used for determining function safety (@pxref{Function Safety}).
-
-@item important-return-value
-@cindex @code{important-return-value} property
-A non-@code{nil} value makes the byte compiler warn about code that
-calls the named function without using its returned value.  This is
-useful for functions where doing so is likely to be a mistake.
+This property is normally added to a function with
+@code{declare} (@pxref{Declare Form}).
 
 @item undo-inhibit-region
 If non-@code{nil}, the named function prevents the @code{undo} operation
@@ -638,7 +656,7 @@ Standard Properties
 @item variable-documentation
 If non-@code{nil}, this specifies the named variable's documentation
 string.  This is set automatically by @code{defvar} and related
-functions.  @xref{Defining Faces}.
+functions.  @xref{Documentation Basics}.
 @end table
 
 @node Shorthands
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 7cc32a7fdb3..9fe8b4b9e21 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -122,14 +122,13 @@ Defining Commands
 be called interactively.  The argument of the @code{interactive} form
 specifies how the arguments for an interactive call should be read.
 
-@cindex @code{interactive-form} property
   Alternatively, an @code{interactive} form may be specified in a
 function symbol's @code{interactive-form} property.  A non-@code{nil}
 value for this property takes precedence over any @code{interactive}
 form in the function body itself.  This feature is seldom used.
 
 @anchor{The interactive-only property}
-@cindex @code{interactive-only} property
+@cindex @code{interactive-only} (symbol property)
   Sometimes, a function is only intended to be called interactively,
 never directly from Lisp.  In that case, give the function a
 non-@code{nil} @code{interactive-only} property, either directly
@@ -174,7 +173,7 @@ Using Interactive
 then the caller supplies the arguments and @var{arg-descriptor} has no
 effect.
 
-@cindex @code{interactive-form}, symbol property
+@cindex @code{interactive-form} (symbol property)
 The @code{interactive} form must be located at top-level in the
 function body, or in the function symbol's @code{interactive-form}
 property (@pxref{Symbol Properties}).  It has its effect because the
@@ -2124,7 +2123,7 @@ Touchscreen Events
 translation'', and produces a simple correspondence between touchpoint
 motion and mouse motion.
 
-@cindex @code{ignored-mouse-command}, a symbol property
+@cindex @code{ignored-mouse-command} (symbol property)
 However, some commands bound to
 @code{down-mouse-1}--@code{mouse-drag-region}, for example--either
 conflict with defined touch screen gestures (such as ``long-press to
@@ -2161,7 +2160,7 @@ Touchscreen Events
 @code{read-key} expecting to receive @code{mouse-movement} and
 @code{drag-mouse-1} events.

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Sun, 12 Jan 2025 09:06:28 -0800
> 
> Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >   The index entry should be only at the place of the main description of
> >   the symbol property, if there is such a place.  Duplicate index
> >   entries are not a good thing....
> 
> Okay, I understand the user experience you're trying to create.
> 
> I still find we need more index entries, but not as many as I thought.
> 
> Here's the latest version of the indexing updates.
> 
> The most notable change here is that I moved the index of
> 'interactive-form' from node "Interactive Call" to "Using
> Interactive", which I thought gave a more detailed explanation.

This LGTM, thanks.

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

[Stephen Gildea]

Eli Zaretskii <eliz@gnu.org> wrote:

>   This LGTM, thanks.

Pushed:
c98d9e -- better indexing of symbol properties
e6591b -- new symbol property 'definition-type'

Thanks for the reviews, Eli.

 < Stephen

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

[Eshel Yaron]

Hi there,

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

> Eli Zaretskii <eliz@gnu.org> wrote:
>
>>   This LGTM, thanks.
>
> Pushed:
> c98d9e -- better indexing of symbol properties
> e6591b -- new symbol property 'definition-type'

Thanks for working on this!  While I understand the motivation for this
feature, ISTM that the design/implementation is not completely coherent:
a symbol in ELisp can name multiple things of different types, the same
symbol can have definitions as a function, variable, face, feature, etc.
It doesn't make sense to talk about "the definition type" of a symbol,
because it can have multiple types.

The implementation makes this issue clear:
find-function-search-for-symbol now just ignores the TYPE argument for
symbols with a specified definition-type property.  So if we want to
find the definition of foo as a face, but someone happened to give foo a
definition-type of, say, a feature, then we're out of luck: we'll get
the wrong results from find-function-search-for-symbol, and we might not
even know it, since it silently ignores the requested TYPE.  Right?

So, unless I'm missing something, instead of a "definition-type", I'd
suggest to give such symbols that need special handling a
symbol-specific association between types and methods for finding
definitions as a symbol property.  So the value of the property would
look like find-function-regexp-alist, just specific to the given symbol,
overriding the "default" associations of find-function-regexp-alist.

I hope this makes sense, sorry for not chiming in earlier.


Regards,

Eshel

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

[Stephen Gildea]

Eshel Yaron <me@eshelyaron.com> wrote:

>   a symbol in ELisp can name multiple things of different types, the same
>   symbol can have definitions as a function, variable, face, feature, etc.
>   It doesn't make sense to talk about "the definition type" of a symbol,
>   because it can have multiple types.

This is quite true.  Many symbols have multiple objects
attached to them.  But not these symbols.

The symbols that need help from 'definition-type' generally
have only one definition.  They tend to be internal symbols
defined by tests, and they tend to have parameterized names
like "formatz-%012:::z-hhmm" or "syntax-br-comments-c-f60".

The design of 'definition-type' affects the complexity and
readability of both the find-function implementation and all
macros that use the property.
(Admittedly the find-function-search-for-symbol complexity is
a minor point, because the price is paid only once.)

I think it is worth aiming primarily to reduce the burden on
all the macro-writers.  We want to make it simple to maintain
the integrity of the property, both in understanding how it
works and in actually writing correct code.

This form, for 'definition-type':

  (put 'my-test-name 'definition-type 'my-test-finding-regexp)

is shorter and easier to understand and write than the form
proposed for 'find-definition-alist':

  (setf (alist-get 'ert-deftest (get 'my-test-name 'find-definition-alist))
        'my-test-finding-regexp)

So, despite its limitations, the simpler design of
'definition-type' seems preferable.

 < Stephen

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

[Eshel Yaron]

Hi,

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

> Eshel Yaron <me@eshelyaron.com> wrote:
>
>>   a symbol in ELisp can name multiple things of different types, the same
>>   symbol can have definitions as a function, variable, face, feature, etc.
>>   It doesn't make sense to talk about "the definition type" of a symbol,
>>   because it can have multiple types.
>
> This is quite true.  Many symbols have multiple objects
> attached to them.  But not these symbols.
>
> The symbols that need help from 'definition-type' generally
> have only one definition.  They tend to be internal symbols
> defined by tests, and they tend to have parameterized names
> like "formatz-%012:::z-hhmm" or "syntax-br-comments-c-f60".

Indeed, for those symbols, this is a minor issue.  But the feature is
introduced and documented as generally applicable, without caveats.
So ideally it should work correctly for any symbol.
Otherwise, it might be a good idea to document this limitation.

> I think it is worth aiming primarily to reduce the burden on
> all the macro-writers.  We want to make it simple to maintain
> the integrity of the property, both in understanding how it
> works and in actually writing correct code.

That's a valid goal, but currently to use this feature correctly,
macro-writers have to make sure they only apply it to distinct symbols
that aren't used anywhere else, which is actually rather burdensome.
Safe interfaces mean less worries for developers, too :)

> This form, for 'definition-type':
>
>   (put 'my-test-name 'definition-type 'my-test-finding-regexp)
>
> is shorter and easier to understand and write than the form
> proposed for 'find-definition-alist':
>
>   (setf (alist-get 'ert-deftest (get 'my-test-name 'find-definition-alist))
>         'my-test-finding-regexp)

Yeah, but the first form is not enough, since in the current
implementation you also need to extend find-function-regexp-alist,
right?

> So, despite its limitations, the simpler design of
> 'definition-type' seems preferable.

I'm not sure it is simpler (see above), but even if it is, I think we
should (and can) find something that is both correct and simple.  ;)

WDYT?


Eshel

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

[Stephen Gildea]

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

Eshel Yaron <me@eshelyaron.com> wrote:

>   Yeah, but the first form is not enough, since in the current
>   implementation you also need to extend find-function-regexp-alist,
>   right?

That is a compelling argument.  I'm pleased to see a design that doesn't
require modifying the global find-function-regexp-alist.  I'm sold.

Here's a complete patch implementing your design.

For the macros that use this functionality, I provide a
convenience function find-function-update-type-alist.

I also fix ERT to always look up its tests with type
'ert--test'; there was a bug where 'ert-describe-test' doesn't
set the type.  With 'definition-type' this didn't matter,
because we overrode the type.  But now that we translate, ERT
has to give us a correct starting type.

 < Stephen


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: change 'definition-type' to 'find-function-type-alist' --]
[-- Type: text/x-diff, Size: 6800 bytes --]

diff --git a/etc/NEWS b/etc/NEWS
index 2f04204ad94..059d765fb44 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1166,11 +1166,14 @@ It offers a more concise way to create a completion table with metadata.
 ** 'all-completions' and 'unintern' no longer support old calling conventions.
 
 +++
-** New symbol property 'definition-type' used by 'find-function' and friends.
+** New symbol property 'find-function-type-alist' used by 'find-function' etc.
 Macros that define an object in a way that 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.
+the macro call site defining the object hard to associate can add an
+entry to the property 'find-function-type-alist' on the object's name to
+provide instructions for finding the definition.
+
+New convenience function 'find-function-update-type-alist' offers a
+concise way to update a symbol's 'find-function-type-alist' property.
 
 \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 643b6aba2a6..f44f48515da 100644
--- a/lisp/emacs-lisp/find-func.el
+++ b/lisp/emacs-lisp/find-func.el
@@ -152,7 +152,11 @@ find-function-regexp-alist
 to be used to substitute the desired symbol name into the regexp.
 Instead of regexp variable, types can be mapped to functions as well,
 in which case the function is called with one argument (the object
-we're looking for) and it should search for it.")
+we're looking for) and it should search for it.
+
+Symbols can have their own version of this alist on
+the property `find-function-type-alist'.
+See the function `find-function-update-type-alist'.")
 (put 'find-function-regexp-alist 'risky-local-variable t)
 
 (define-obsolete-variable-alias 'find-function-source-path
@@ -402,9 +406,9 @@ find-function-search-for-symbol
 
 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'.
+TYPE is looked up in SYMBOL's property `find-function-type-alist'
+(which can be maintained with `find-function-update-type-alist')
+or the variable `find-function-regexp-alist'.
 
 The search is done in the source for library LIBRARY."
   (if (null library)
@@ -413,8 +417,6 @@ 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)
@@ -424,7 +426,9 @@ find-function-search-for-symbol
     (when (string-match "\\.emacs\\(.el\\)\\'" library)
       (setq library (substring library 0 (match-beginning 1))))
     (let* ((filename (find-library-name library))
-	   (regexp-symbol (cdr (assq type find-function-regexp-alist))))
+	   (regexp-symbol
+            (or (alist-get type (get symbol 'find-function-type-alist))
+                (alist-get type find-function-regexp-alist))))
       (with-current-buffer (find-file-noselect filename)
 	(let ((regexp (if (functionp regexp-symbol) regexp-symbol
                         (format (symbol-value regexp-symbol)
@@ -466,6 +470,13 @@ find-function-search-for-symbol
                       (find-function--search-by-expanding-macros
                        (current-buffer) symbol type))))))))))
 
+;;;###autoload
+(defun find-function-update-type-alist (symbol type variable)
+  "Update SYMBOL property `find-function-type-alist' with (TYPE . VARIABLE).
+Property `find-function-type-alist' is a symbol-specific version
+of variable `find-function-regexp-alist' and has the same format."
+  (setf (alist-get type (get symbol 'find-function-type-alist)) variable))
+
 (defun find-function--try-macroexpand (form)
   "Try to macroexpand FORM in full or partially.
 This is a best-effort operation in which if macroexpansion fails,
diff --git a/lisp/emacs-lisp/ert.el b/lisp/emacs-lisp/ert.el
index f25ba8a529c..3106b0dabca 100644
--- a/lisp/emacs-lisp/ert.el
+++ b/lisp/emacs-lisp/ert.el
@@ -2467,7 +2467,9 @@ ert-results-find-test-at-point-other-window
 
 (defun ert--test-name-button-action (button)
   "Find the definition of the test BUTTON belongs to, in another window."
-  (let ((name (button-get button 'ert-test-name)))
+  ;; work with either ert-insert-test-name-button or help-xref-button
+  (let ((name (or (button-get button 'ert-test-name)
+                  (car (button-get button 'help-args)))))
     (ert-find-test-other-window name)))
 
 (defun ert--ewoc-position (ewoc node)
@@ -2814,7 +2816,8 @@ ert-describe-test
                                       (file-name-nondirectory file-name)))
               (save-excursion
                 (re-search-backward (substitute-command-keys "`\\([^`']+\\)'"))
-                (help-xref-button 1 'help-function-def test-name file-name)))
+                (help-xref-button 1 'ert--test-name-button
+                                  test-name file-name)))
             (insert ".")
             (fill-region-as-paragraph (point-min) (point))
             (insert "\n\n")
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index 508ee13a244..058ed9fda14 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -536,9 +536,9 @@ Standard Properties
 related functions.  @xref{Variable Definitions}.
 
 @cindex @code{definition-name} (symbol property)
-@cindex @code{definition-type} (symbol property)
+@cindex @code{find-function-type-alist} (symbol property)
 @item definition-name
-@itemx definition-type
+@itemx find-function-type-alist
 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.
@@ -563,16 +563,19 @@ Standard Properties
 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}
+In such cases, the @code{find-function-type-alist} property of the
+symbol can be an alist that augments @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

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

[Eshel Yaron]

Hi Stephen,

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

> Eshel Yaron <me@eshelyaron.com> wrote:
>
>>   Yeah, but the first form is not enough, since in the current
>>   implementation you also need to extend find-function-regexp-alist,
>>   right?
>
> That is a compelling argument.  I'm pleased to see a design that doesn't
> require modifying the global find-function-regexp-alist.  I'm sold.

I'm glad, thank you for reconsidering!

> Here's a complete patch implementing your design.

Looks great, thanks.  I do see a few remaining references to the
definition-type property in documentation that we'd probably want to
update, namely in functions.text, symbols.texi, tips.text and ert.texi.
I can try and help with those documentation fixes if you want.

> For the macros that use this functionality, I provide a
> convenience function find-function-update-type-alist.
>
> I also fix ERT to always look up its tests with type
> 'ert--test'; there was a bug where 'ert-describe-test' doesn't
> set the type.  With 'definition-type' this didn't matter,
> because we overrode the type.  But now that we translate, ERT
> has to give us a correct starting type.

Makes sense.  BTW I now see that ERT uses both ert--test and ert-deftest
in find-function-regexp-alist, which seems like an oversight.
That's probably a topic for a separate discussion though :)


Best regards,

Eshel

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Tue, 14 Jan 2025 19:14:28 -0800
> 
> Here's a complete patch implementing your design.

Thanks, but shouldn't we document somewhere what form are the elements
of this alist?  It is strange to keep this completely semi-documented
only by reference to another variable, and only in a doc string of a
function.

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

[Stephen Gildea]

Eshel Yaron <me@eshelyaron.com> wrote:

>   I do see a few remaining references to the
>   definition-type property in documentation that we'd probably want to
>   update, namely in functions.text, symbols.texi, tips.text and ert.texi.

The patch I posted updates all the references in those files.

>   BTW I now see that ERT uses both ert--test and ert-deftest
>   in find-function-regexp-alist, which seems like an oversight.
>   That's probably a topic for a separate discussion though :)

Yes, that does look buggy.  It succeeds only because find-function
has a clever fallback.  I'll start a new thread about ERT fixes.

Eli Zaretskii <eliz@gnu.org> wrote:

>   ... shouldn't we document somewhere what form are the elements
>   of this alist?  It is strange to keep this completely semi-documented
>   only by reference to another variable, and only in a doc string of a
>   function.

This bothered me, too.  Looking around the ELisp manual, I
don't see an obvious place.  Perhaps in the node "Defining
Functions".  That might take away from the flow of discussion
of 'defun', 'defalias', and 'defsubst', but I think we could
add a few paragraphs to the end of this section and not overly
burden it.  Other suggestions welcome.

 < Stephen

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Wed, 15 Jan 2025 13:17:11 -0800
> 
> Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >   ... shouldn't we document somewhere what form are the elements
> >   of this alist?  It is strange to keep this completely semi-documented
> >   only by reference to another variable, and only in a doc string of a
> >   function.
> 
> This bothered me, too.  Looking around the ELisp manual, I
> don't see an obvious place.  Perhaps in the node "Defining
> Functions".  That might take away from the flow of discussion
> of 'defun', 'defalias', and 'defsubst', but I think we could
> add a few paragraphs to the end of this section and not overly
> burden it.  Other suggestions welcome.

Why not in the same place where you describe this property?  Just add
the description of the alist value and its elements.

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

[Stephen Gildea]

I am going to break up the pending patch into three pieces:

First, changing definition-type to find-function-type-alist.
There seems to be no objection to this change, and I want to
get it committed before anyone builds on definition-type.
I'll commit this shortly.

Second, the documentation for find-function-type-alist.
I'll respond to this discussion in a separate message on this
thread, but I think this improvement to the manual can be its
own commit.

Third, fixes to ERT's integration with find-func.
These bugs turned out to be more extensive than I first
thought.  I've pulled them out of this patch and into a
separate patch, posted on a separate thread.  I'll wait a bit
to see if anyone wants to review it.  The ert fixes are
necessary before one can use find-function-type-alist with
macros expanding to ert-deftest, but other uses of
find-function-type-alist do not depend on them.

 < Stephen

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

[Stephen Gildea]

Regarding where to document function find-function-update-type-alist and variable find-function-regexp-alist, Eli Zaretskii <eliz@gnu.org> wrote:

>   Why not in the same place where you describe this
>   property?  Just add the description of the alist value and
>   its elements.

We could.  I'd be happy to push this and call it done.

But it feels like it is in the wrong place.  Mostly, the
section "Standard Symbol Properties" is a compact list of all
the standard properties, and mostly it gives a short summary
for each and xrefs the section containing a thorough
discussion.  The part about definition-name and
find-function-type-alist is the only part that is more than
one paragraph long, and this would make it at least two
paragraphs longer.

I'd like to treat definition-name and find-function-type-alist
the same as the others:  discuss them thoroughly in their own
section, and reduce this section to a short paragraph with a
cross reference.

 < Stephen

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Thu, 16 Jan 2025 15:45:11 -0800
> 
> Regarding where to document function find-function-update-type-alist and variable find-function-regexp-alist, Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >   Why not in the same place where you describe this
> >   property?  Just add the description of the alist value and
> >   its elements.
> 
> We could.  I'd be happy to push this and call it done.
> 
> But it feels like it is in the wrong place.  Mostly, the
> section "Standard Symbol Properties" is a compact list of all
> the standard properties, and mostly it gives a short summary
> for each and xrefs the section containing a thorough
> discussion.  The part about definition-name and
> find-function-type-alist is the only part that is more than
> one paragraph long, and this would make it at least two
> paragraphs longer.
> 
> I'd like to treat definition-name and find-function-type-alist
> the same as the others:  discuss them thoroughly in their own
> section, and reduce this section to a short paragraph with a
> cross reference.

That doesn't contradict my suggestion in any way.  I said nothing
about the section where this information should be added.  Describing
these properties in their own section is definitely fine by me.

Thanks.

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

[Stephen Gildea]

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

> I'd like to treat definition-name and find-function-type-alist
> the same as the others:  discuss them thoroughly in their own
> section, and reduce this section to a short paragraph with a
> cross reference.

Here is how that could look.  I have moved the discussion of
definition-name and find-function-type-alist to a new node
immediately after the 'defun' node, and I have added explicit
documentation of variable find-function-regexp-alist and new
function find-function-update-type-alist.

 < Stephen


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: doc for find-function-update-type-alist and find-function-regexp-alist --]
[-- Type: text/x-diff, Size: 7073 bytes --]

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 7f881bae7f5..0d5bbb602e4 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -832,6 +832,93 @@ Defining Functions
   To undefine a function name, use @code{fmakunbound}.
 @xref{Function Cells}.
 
+@node Finding Definitions
+@subsection Finding Definitions
+
+Tools such as Emacs's built-in help command @kbd{C-h f} (@pxref{Help,,,
+emacs, The GNU Emacs Manual}) can find the definition site of functions
+and other Lisp objects in the source code.  To do this, they use the
+variable @code{find-function-regexp-alist}.
+
+@vindex @code{find-function-regexp-alist}
+The alist @code{find-function-regexp-alist} associates object types with
+a regexp or function that finds the definition of that object in its
+source file.  Each element's car is a symbol the describes the type of
+object, or @code{nil} to identify functions defined with @code{defun}.
+Each element's cdr is a symbol: either the value of that symbol is a
+string interpreted as a regexp, or that symbol names a function that can
+find the definition.
+
+A regexp string is actually a format string, and @code{%s} will be
+substituted with the name of the symbol we are looking for.
+
+A function will be called with one argument, the (symbol for) the object
+we are searching for.
+
+@cindex @code{definition-name} (symbol property)
+If the function to be found is defined by a macro, it may be hard for
+Emacs to find the definition site in the source code.  A macro call may
+have an unexpected look to it, and @code{find-function-regexp-alist}
+will fail to identify the definition.
+
+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.  In these and similar cases, the @code{definition-name}
+property of the symbol should be another symbol whose definition can 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.
+
+@cindex @code{find-function-type-alist} (symbol property)
+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{How to Write
+Tests,,,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{find-function-type-alist} property of the symbol can be an
+alist that augments @code{find-function-regexp-alist} telling how to
+find the definition of symbols of this type.
+
+The @code{find-function-regexp-alist} property is most easily maintained
+with the convenience function @code{find-function-update-type-alist}.
+
+@defun find-function-update-type-alist symbol type variable
+Update property @code{find-function-type-alist} of @var{symbol} with
+a new element containing key @var{type} and value @var{variable}.
+@end defun
+
+In the example of a macro defining calls to @code{ert-deftest},
+the macro could put the property @code{find-function-type-alist} on each
+test defined, associating @code{ert--test} (the internal type of ERT
+tests) with the name of a regexp or function that can find the correct
+macro call.  The file defining the macro would also have to provide that
+definition-finding function or regexp.
+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
+       (find-function-update-type-alist
+        ',test-name 'ert--test 'foo-find-test-def-function)
+       (ert-deftest ,test-name ()
+         ,(concat "Test foo with " ...)
+         ...))))
+@end group
+
+@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."
+  (let ((regexp ...))
+    (re-search-forward regexp nil t)))
+@end group
+@end example
+
 @node Calling Functions
 @section Calling Functions
 @cindex function invocation
diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi
index dc6509c1ae3..c334b5d5dfb 100644
--- a/doc/lispref/symbols.texi
+++ b/doc/lispref/symbols.texi
@@ -535,70 +535,12 @@ Standard Properties
 Do not set them directly; they are managed by @code{defcustom} and
 related functions.  @xref{Variable Definitions}.
 
-@cindex @code{definition-name} (symbol property)
-@cindex @code{find-function-type-alist} (symbol property)
 @item definition-name
 @itemx find-function-type-alist
 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
-Functions}).  In these and similar cases, the @code{definition-name}
-property of the symbol should be another symbol whose definition can
-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.
-
-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{How to Write
-Tests,,,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{find-function-type-alist} property of the symbol can be an
-alist that augments @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{find-function-type-alist} on each
-test defined, associating @code{ert--test} (the internal type of ERT
-tests) with the name of a regexp or function that can find the correct
-macro call.  The file defining the macro would also have to provide that
-definition-finding function or regexp.
-Here is an example using a function to find the definition.
-The example updates the property using convenience function
-@code{find-function-update-type-alist}.
-
-@example
-@group
-(defmacro define-foo-test (data)
-  "Define a test of the foo system using DATA."
-  (declare (debu

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Tue, 21 Jan 2025 21:27:33 -0800
> 
> > I'd like to treat definition-name and find-function-type-alist
> > the same as the others:  discuss them thoroughly in their own
> > section, and reduce this section to a short paragraph with a
> > cross reference.
> 
> Here is how that could look.  I have moved the discussion of
> definition-name and find-function-type-alist to a new node
> immediately after the 'defun' node, and I have added explicit
> documentation of variable find-function-regexp-alist and new
> function find-function-update-type-alist.

Looks good, but please remember to update the menu of the parent
section and the detailed menu in elisp.texi with this new subsection.

Thanks.

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

[Stephen Gildea]

Eli Zaretskii <eliz@gnu.org> wrote:

>   Looks good, but please remember to update the menu of the parent
>   section and the detailed menu in elisp.texi with this new subsection.

Done, and documentation commited as aa6d2a396a

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Wed, 22 Jan 2025 19:16:35 -0800
> 
> Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >   Looks good, but please remember to update the menu of the parent
> >   section and the detailed menu in elisp.texi with this new subsection.
> 
> Done, and documentation commited as aa6d2a396a

Thanks.  (I had to follow up with 2 trivial fixes, since makeinfo
reported errors; didn't you see them?)

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

[Stephen Gildea]

Eli Zaretskii <eliz@gnu.org> wrote:

>   > From: Stephen Gildea <stepheng+emacs@gildea.com>
>   > 
>   > Done, and documentation commited as aa6d2a396a
>   
>   Thanks.  (I had to follow up with 2 trivial fixes, since makeinfo
>   reported errors; didn't you see them?)

I'm sorry you had to do clean-up.

I ran "cd doc/lispref && make".  "make" ran
"makeinfo --force --enable-encoding -I ./../emacs -I . --no-split -o ../../info/elisp.info elisp.texi"
and that completed without error.

This is not the first time I've submitted doc changes that
other people report cause errors.  How can I see the same
errors you do?

 < Stephen

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Thu, 23 Jan 2025 09:14:25 -0800
> 
> Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >   > From: Stephen Gildea <stepheng+emacs@gildea.com>
> >   > 
> >   > Done, and documentation commited as aa6d2a396a
> >   
> >   Thanks.  (I had to follow up with 2 trivial fixes, since makeinfo
> >   reported errors; didn't you see them?)
> 
> I'm sorry you had to do clean-up.
> 
> I ran "cd doc/lispref && make".  "make" ran
> "makeinfo --force --enable-encoding -I ./../emacs -I . --no-split -o ../../info/elisp.info elisp.texi"
> and that completed without error.
> 
> This is not the first time I've submitted doc changes that
> other people report cause errors.  How can I see the same
> errors you do?

I don't do anything special, only run "make -jN" in the top-level
directory.  I saw these messages from makeinfo after updating today:

  functions.texi:687: warning: node next pointer for `Defining Functions' is `Calling Functions' but next is `Finding Definitions' in menu
  functions.texi:840: warning: node `Calling Functions' is next for `Finding Definitions' in menu but not in sectioning
  functions.texi:840: warning: node `Defining Functions' is prev for `Finding Definitions' in menu but not in sectioning
  functions.texi:927: warning: node prev pointer for `Calling Functions' is `Defining Functions' but prev is `Finding Definitions' in menu

If you revert my changes and run "make" don't you see those?  If not,
which version of Texinfo do you have installed?

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

[Stephen Gildea]

Eli Zaretskii <eliz@gnu.org> wrote:

>   If you revert my changes and run "make" don't you see those?  If not,
>   which version of Texinfo do you have installed?

No, I do not see those messages.  I had Texinfo 7.1 installed.

I just downloaded Texinfo 7.2, and now I do see the messages.  

I have also heard the complaint that I used a construct
supported only by newer Texinfo.  So apparently I also need to
test with an old version.  How old do you recommend?

 < Stephen

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

[Eli Zaretskii]

> From: Stephen Gildea <stepheng+emacs@gildea.com>
> Date: Thu, 23 Jan 2025 13:52:14 -0800
> 
> Eli Zaretskii <eliz@gnu.org> wrote:
> 
> >   If you revert my changes and run "make" don't you see those?  If not,
> >   which version of Texinfo do you have installed?
> 
> No, I do not see those messages.  I had Texinfo 7.1 installed.
> 
> I just downloaded Texinfo 7.2, and now I do see the messages.  

Those warnings were mistakenly disabled by default in 7.1.  I think
previous versions did have it.

> I have also heard the complaint that I used a construct
> supported only by newer Texinfo.  So apparently I also need to
> test with an old version.  How old do you recommend?

According to Texinfo NEWS, the requirement for punctuation after
cross-reference was removed in version 6.1.

Personally, I find it easier to just remember to follow the closing
brace of a cross-reference with a comma, unless it already has a
period that ends a sentence.