Next: , Up: Documentation

24.1 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) that briefly describes what the function or variable does. 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 documentation strings; see Documentation Tips.

Documentation strings can contain several special text sequences, referring to key bindings which are looked up in the current keymaps when the user views the documentation. This allows the help commands to display the correct keys even if a user rearranges the default key bindings. See Keys in Documentation.

In the documentation string of an autoloaded command (see Autoload), these special text sequences have an additional special effect: they cause C-h f (describe-function) on the command to trigger autoloading. (This is needed for correctly setting up the hyperlinks in the *Help* buffer).

Emacs Lisp mode fills documentation strings to the width specified by emacs-lisp-docstring-fill-column.

Exactly where a documentation string is stored depends on how its function or variable was defined or loaded into memory:

Regardless of where the documentation string is stored, you can retrieve it using the documentation or documentation-property function, described in the next section.