Next: Accessing Documentation, Up: Documentation
A documentation string is written using the Lisp syntax for strings, with double-quote characters surrounding the text of the string. This is because it really is a Lisp string object. The string serves as documentation when it is written in the proper place in the definition of a function or variable. In a function definition, the documentation string follows the argument list. In a variable definition, the documentation string follows the initial value of the variable.
When you write a documentation string, make the first line a
complete sentence (or two complete sentences) since some commands,
such as apropos, show only the first line of a multi-line
documentation string. Also, you should not indent the second line of
a documentation string, if it has one, because that looks odd when you
use C-h f (describe-function) or C-h v
(describe-variable) to view the documentation string. There
are many other conventions for doc strings; see Documentation Tips.
Documentation strings can contain several special substrings, which stand for key bindings to be looked up in the current keymaps when the documentation is displayed. This allows documentation strings to refer to the keys for related commands and be accurate even when a user rearranges the key bindings. (See Keys in Documentation.)
In Emacs Lisp, a documentation string is accessible through the function or variable that it describes:
documentation knows how to extract it. You can also put
function documentation in the function-documentation property
of the function name. That is useful with definitions such as
keyboard macros that can't hold a documentation string.
variable-documentation. The
function documentation-property knows how to retrieve it.
To save space, the documentation for preloaded functions and variables (including primitive functions and autoloaded functions) is stored in the file emacs/etc/DOC-version—not inside Emacs. The documentation strings for functions and variables loaded during the Emacs session from byte-compiled files are stored in those files (see Docs and Compilation).
The data structure inside Emacs has an integer offset into the file, or
a list containing a file name and an integer, in place of the
documentation string. The functions documentation and
documentation-property use that information to fetch the
documentation string from the appropriate file; this is transparent to
the user.
For information on the uses of documentation strings, see Help↗.
The emacs/lib-src directory contains two utilities that you can use to print nice-looking hardcopy for the file emacs/etc/DOC-version. These are sorted-doc and digest-doc.