From 0cb686ffb6bbc017d3b71acbf40ed3e5c1a32863 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 7 Jan 2023 19:57:30 +0200 Subject: [PATCH] Document the 'definition-name' property. * doc/lispref/symbols.texi (Standard Properties): Document 'definition-name'. * doc/lispref/functions.texi (Defining Functions): Describe how to use 'definition-name' when generating function definitions at run time. (Bug#60568) --- doc/lispref/functions.texi | 14 ++++++++++++++ doc/lispref/symbols.texi | 17 +++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 3a8eddb93ea..f5572e447d3 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -685,6 +685,20 @@ Here are some examples: @end group @end example +@cindex defining functions dynamically +Most Emacs functions are part of the source code of Lisp programs, and +are defined when the Emacs Lisp reader reads the program source before +executing it. However, you can also define functions dynamically at +run time, e.g., by generating @code{defun} calls when your program's +code is executed. If you do this, be aware that Emacs's Help +commands, such as @kbd{C-h f}, which present in the @file{*Help*} +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 +generates such functions easier by using the @code{definition-name} +property, @pxref{Standard Properties}. + @cindex override existing functions @cindex redefine existing functions Be careful not to redefine existing functions unintentionally. diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index 183367c0cda..5b53cbe310a 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -555,6 +555,23 @@ 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} +(@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. 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. + @item disabled If the value is non-@code{nil}, the named function is disabled as a command. @xref{Disabling Commands}. -- 2.39.2