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