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

[Stephen Gildea]

> 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

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 (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
+of the source file, as when the symbol is defined by a macro.
+@xref{Finding Definitions}.
 
 @item disabled
 If the value is non-@code{nil}, the named function is disabled as a
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 1bf52886971..31716ffa9e1 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -229,7 +229,7 @@ Coding Conventions
 If your macro cannot be written in this style, the macro can still
 help these tools find the defining call by putting the property
 @code{definition-name} or @code{find-function-type-alist} on the name.
-@xref{Standard Properties}.
+@xref{Finding Definitions}.
 
 @item
 In some other systems there is a convention of choosing variable names
diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi
index 0e03afc98ff..4617453d06d 100644
--- a/doc/misc/ert.texi
+++ b/doc/misc/ert.texi
@@ -525,7 +525,7 @@ How to Write Tests
 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{find-function-type-alist} on the test name.
-@xref{Standard Properties,,,elisp, GNU Emacs Lisp Reference Manual}.
+@xref{Finding Definitions,,,elisp, GNU Emacs Lisp Reference Manual}.
 
 
 @menu