ELisp: Docstring Markup

Emacs Lisp Docstring Markup

ALLCAPS

Function parameter names are in ALLCAPS by Emacs convention. No special behavior.

`function_name'

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

\\[command_name]

Keybinding of a command.

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

"
\\<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. [see ELisp: Create Keymap for Major Mode]

"
\\{emacs-lisp-mode-map}
"

\\='

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

'symbol

should be written as

\\='symbol

else, it may be rendered as

’symbol

(since Emacs 28 (Released 2022-04) )

see:

• Emacs 29 Byte Compile Unescaped Single Quote Warning
• Emacs: text-quoting-style

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

Here's how it shows: