procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document the 'definition-name' property.

Browse source 
* 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)
This commit is contained in:
Eli Zaretskii 2023-01-07 19:57:30 +02:00
parent 7f855b5297
commit 0cb686ffb6
2 changed files with 31 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
doc/lispref/functions.texi
View file

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

17
doc/lispref/symbols.texi
View file

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