ELisp: Docstring Markup

By Xah Lee. Date: . Last updated: .

Emacs lisp function doc string support markup to indicate links, parameters, keybinding, etc that are shown when you Alt+x describe-function.

Emacs Lisp Docstring Markup

Function parameter names are in ALLCAPS by Emacs convention. No special behavior.
Link to a function's doc.
see `sort-lines'
variable `name'
Link to a variable's doc. Some elisp names are both function and variable.

The word variable can also be option, command.

see variable `buffer-file-name'
Keybinding of a command.
Type \\[find-file] to open a file.
No visible effect. Tell emacs to use this keymap for interpreting \\[command_name] for the rest of this doc string.
Type \\[dired-flag-file-deletion] to flag a file for deletion.
List of keybindings of a given keymap.

By convention, commands that invoke a major mode will show its keybinding at the end of document. [see ELisp: Create Keymap for Major Mode]

Single quote, such as when showing some lisp code in docstring.


should be written as


else, it may be rendered as


(since Emacs 28 (Released 2022-04) )


URL `url'
Link to URL.
URL `http://example.org/'
Info node `info_node_name'
Link to Info doc page.

When in a info page, press c to 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]

see Info node `(emacs) Dired'.

Emacs Lisp Docstring Example

(defun xx (arg1 arg2)
  "One short line summary. Should be Less than 67 chars.

Detail here. Mention return value. No indentation.

ARG1 spec.

ARG2 spec.

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.
  (message "%s" "something.")

Here's how it shows:

elisp function doc string 2022-05-25
emacs describe-function output. note the clickable links, italics, and keybinding.


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

Emacs Lisp Function

Emacs Text Quoting Conversion in Docstring