DocString

A documentation string, or doc string, documents an EmacsLisp object (typically a function or variable) associated with a symbol. Doc strings are an important part of SelfDocumentation. For example, the various ‘describe-*’ commands use doc strings.

A doc string might explain to a user what a function or variable is for, what possible arguments a function understands and what it returns, what other functions or variables the user might be interested in, where to find more information and so on.

Doc strings are defined when you define the function or variable. For example ‘defun’, the command to define new functions, has the syntax (defun NAME ARGLIST [DOCSTRING] BODY...), where the optional argument for defining the string can be seen. Thus in the example

    (defun hello-world nil
      "Greet the world.
    This function implements the canonical example program."
      (interactive)
      (message "Hello world!"))

the doc string, which can be obtained with (documentation ‘hello-world), is

      "Greet the world.
    This function implements the canonical example program.".

Remember that doc strings and comments are different. Comments are visible only to someone who takes a look at the source code. They are typically directed at developers of the code, not at its users. Doc strings are primarily for users.

With good CodingStyle the first line of a doc string should be a complete sentence that gives a summary description of the object. More verbose text can follow. See also: CheckDoc.

More information about doc strings can be found in the Emacs Lisp Manual.

Documentation formats

Look at the manual node for complete information. But here are the formats for some rich text in doc strings:

Arguments
All caps, e.g., ARG in ARG is used as...
Elisp symbols (variable/function/etc)
Surround single quote, e.g, ‘car’. You can easily type single quotes with ‘electric-quote-mode’ enabled.
Info node
Also surround with a single quote, but also preceded with ‘info node’, ‘Info node’, ‘info anchor’ or ‘Info anchor’, e.g, Info node ‘(elisp)Font Lock Basics’ where “Font Lock Basics” is the node title.
URL
Similar to Info node, surround with single quotes and stick ‘URL’ in the front - URL ‘http://https://www.emacswiki.org/’
Key binding for commands
\\[function] will display the current key binding for ‘function’, e.g., \\[forward-char], which is usually rendered to C-f.
Keymap
\\<map> displays the keymap ‘map’, use this before key bindings and the functions’ keybinding will be interpreted as in ‘map’. E.g., \\<html-mode-map>
List all the keys of a keymap
\\{map}. This lists all the keys in ‘map’ like what you would see in a major mode’s doc string.
Change function signature in the documentation
Add \(fn signature) to the end of doc string. E.g., in ‘dolist’ they have this line \(fn (VAR LIST [RESULT]) BODY...). This changes the actual signature (spec &rest body) to (VAR LIST [RESULT] BODY...) which is clearly more helpful.

CategoryDocumentation CategoryHelp CategoryCode CategoryGlossary