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_node_name'

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 the node's name. [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 interpreting \\[command_name] for the rest of this doc string. Example: \\<dired-mode-map> Type \\[dired-flag-file-deletion] to flag a file for deletion.

\\{keymap_name}

List of keybindings of a given keymap. By convention, commands that invoke a major mode will show its keybinding at the end of document. Example: \\{c-mode-map}.
[see Elisp: How to Create Keymap for Major Mode]

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.)

Reference

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

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