Elisp: Doc String Markup

This page shows emacs function doc string convention and markup.

When you lookup a function's doc by Alt+x describe-function, you'll notice these features:

• Function's parameters are italicized.
• Mention of other function names are shown in blue and can be clicked to jump to.
• URL can be clicked to open it in web browser.
• Keyboard shortcuts will show correctly even if user have changed it.

To have these features, you need to put markups in your inline string.

Here's the docstring markup:

ALLCAPS

Function argument.

`function_name'

Link to a function. Example: `sort-lines'

variable `name'

Link to a variable. Some elisp names are both function and variable. (For example, global-display-line-numbers-mode). In that case, if you want emacs to link to the variable, precede it with the word “variable” or any of the word {variable, option, command}.

URL `url'

Link to URL. Example: URL `http://example.org/'

Info node `info_id'

Link to Info doc node. Example: Info node `(emacs) Dired'.

Each page in info doc is identified by a string, for examples: (elisp) Visiting Functions . The first part in paren is the doc name, followed by the node's name. When you are in info page, pressing c will copy this node's id to the kill-ring. [see Emacs: View Info Page]

Note, emacs's info node may change or disappear with new emacs versions. [see Emacs Manual Node Persistency Issues]

\\[command_name]

Keybinding of a command. Example: Type \\[find-file] to open a file.

\\<keymap_name>

No visible effect. Tell emacs to use this keymap for displaying keys in the rest of this doc string. Example: \\<c-mode-map>

\\{keymap_name}

List of keybindings of a given keymap. Example: \\{c-mode-map}

Example:

(defun xyz (arg1 arg2)
  "one short line summary. Less than 67 chars is good.

Detail here. Mention return value. No indentation.

ARG1 something, ARG2 something.

See URL `http://example.com/'.

See `dired'.

See Info node `(emacs) Dired'.

Type \\[dired] to go into dired.

clickable list of all keys of a given keymap name.
\\{c-mode-map}"
  (interactive)
  (message "%s" "do something.")
  )

Here's how it shows:

The following are conventions.

Short Summary in First Line

The first line of your doc string should be a one sentence summary of the function. Should be no more than 67 characters. Because, apropos-command 【Ctrl+h a】 will display just that line.

The doc string should be formatted into lines each about 70 chars, instead of one long line of hundreds chars. (you can use fill-paragraph for this.)

Auto Generate Shortcut Keys

In your doc string you may need to tell users about pressing a keyboard shortcut to do something. For example, in dired, when you Alt+x describe-mode, the doc says: “Type C to Copy files.”. If a user has customized dired's keys, the doc string will correctly display the new key.

To make the key of a command automatically show correctly, you need to quote the command name by \\[command_name]. Here's a example from dired:

(defun dired-mode (&optional dirname switches)
  "\
Mode for \"editing\" directory listings.
…
Type \\[dired-do-copy] to Copy files.
…"
)

Sometimes the command you mentioned may have different keys in your mode or in global mode. You can be specific by including \\<key_map_name> before \\[command_name].

The \\<key_map_name> won't be displayed, it just tells emacs what keymap to use for processing the rest of doc string. Example:

(defun dired-mode (&optional dirname switches)
  "…

You can move using the usual cursor motion commands.\\<dired-mode-map>
The buffer is read-only.  Digits are prefix arguments.
Type \\[dired-flag-file-deletion] to flag a file `D' for deletion.
Type \\[dired-mark] to Mark a file or subdirectory for later commands.
…"
)

Auto Generated Keybinding List

A major mode usually has its own set of keyboard shortcuts (its own keymap). For example, in c-mode, Alt+x describe-mode, you'll see this:

Key bindings:
key             binding
---             -------

C-c             Prefix Command
C-d             c-electric-delete-forward
TAB             c-indent-line-or-region
…

This is automatically generated. You just need to quote the keymap name by \\{keymap_name}. By convention, you put it at the end of your major mode's documentation. Example:

(defun c-mode ()
  "Major mode for editing K&R and ANSI C code.
To submit a problem report, enter `\\[c-submit-bug-report]' from a
c-mode buffer.  This automatically sets up a mail buffer with version
information already added.  You just need to add a description of the
problem, including a reproducible test case, and send the message.

To see what version of CC Mode you are running, enter `\\[c-version]'.

The hook `c-mode-common-hook' is run with no args at mode
initialization, then `c-mode-hook'.

Key bindings:
\\{c-mode-map}"
;…
)

Reference

• (info "(elisp)Documentation Tips")
• (info "(elisp) Keys in Documentation")

2014-05-27 thanks to jcs [http://irreal.org/blog/?p=2715] for tips.