14.5.1 Functions and Similar Entities

This section describes the commands for describing functions and similar entities:

@deffn category name arguments…

The @deffn command is the general definition command for functions, interactive commands, and similar entities that may take arguments. You must choose a term to describe the category of entity being defined; for example, “Function” could be used if the entity is a function. The @deffn command is written at the beginning of a line and is followed on the same line by the category of entity being described, the name of this particular entity, and its arguments, if any. Terminate the definition with @end deffn on a line of its own.

For example, here is a definition:

@deffn Command forward-char nchars
Move point forward @var{nchars} characters.
@end deffn

This shows a rather terse definition for a “command” named forward-char with one argument, nchars.

@deffn prints argument names such as nchars in slanted type in the printed output, because we think of these names as metasyntactic variables—they stand for the actual argument values. Within the text of the description, however, write an argument name explicitly with @var to refer to the value of the argument. In the example above, we used ‘@var{nchars}’ in this way.

In the extremely unusual case when an argument name contains ‘--’, or another character sequence which is treated specially (see Conventions), use @code around the special characters. This avoids the conversion to typographic en-dashes and em-dashes.

The template for @deffn is:

@deffn category name arguments…
body-of-definition
@end deffn

@defun name arguments…

The @defun command is the definition command for functions. @defun is equivalent to ‘@deffn Function …’. Terminate the definition with @end defun on a line of its own. Thus, the template is:

@defun function-name arguments…
body-of-definition
@end defun

@defmac name arguments…

The @defmac command is the definition command for macros. @defmac is equivalent to ‘@deffn Macro …’ and works like @defun.

@defspec name arguments…

The @defspec command is the definition command for special forms. (In Lisp, a special form is an entity much like a function; see Special Forms in GNU Emacs Lisp Reference Manual.) @defspec is equivalent to ‘@deffn {Special Form} …’ and works like @defun.

All these commands create entries in the index of functions.