13.6.1 Functions and Similar Entities

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

@deffn category name arguments

The @deffn command is the general definition command for functions, interactive commands, and similar entities that may take simple 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.

Where the output format allows, @deffn uses a typewriter font for name, and a slanted font for the rest of the arguments, as would be produced by @var.

Within the text of the description, 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 General Syntactic Conventions), use @code around the special characters. This avoids the conversion to typographic en-dashes and em-dashes.

@defun name arguments

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

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