Emacs Lisp: Function Doc String 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.

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.
\\{emacs-lisp-mode-map}"
  (interactive)
  (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.

docstring markup

ALLCAPS
Function parameter names are in ALLCAPS by Emacs convention. No special behavior.
`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: \\{emacs-lisp-mode-map}.
[see Emacs Lisp: How to Create Keymap for Major Mode]

Reference

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

Emacs Lisp Function


Lisp Basics

Basics

Lisp Data Structure

Function

Lisp Symbol

Lisp Misc

Working with Elisp