From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 7 Jan 2023 17:57:30 +0000 (+0200)
Subject: Document the 'definition-name' property.
X-Git-Tag: emacs-29.0.90~809
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=0cb686ffb6bbc017d3b71acbf40ed3e5c1a32863;p=emacs.git

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

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