GNU Info

Info Node: (elisp)Documentation Basics

(elisp)Documentation Basics


Next: Accessing Documentation Up: Documentation
Enter node , (file) or (file)node

Documentation Basics
====================

   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.  Note: 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.  (Note: Accessing Documentation.)

   In Emacs Lisp, a documentation string is accessible through the
function or variable that it describes:

   * The documentation for a function is stored in the function
     definition itself (Note: Lambda Expressions).  The function
     `documentation' knows how to extract it.

   * The documentation for a variable is stored in the variable's
     property list under the property name `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 (Note:
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 Note:
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'.


automatically generated by info2www version 1.2.2.9