Elisp: Doc String Markup

By Xah Lee. Date: . Last updated: .

This page shows emacs function doc string convention and markup.

emacs describe-function query-replace 2020-12-04 FKhM5
emacs describe-function screen. (note the clickable links.)

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

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:

screenshot 2020-12-04 pw9sR
emacs inline doc string sample

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-commandCtrl+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

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

If you have a question, put $5 at patreon and message me.
Or Buy Xah Emacs Tutorial
Or buy JavaScript in Depth

Emacs Tutorial

Emacs Init

Emacs Keys

ELisp

ELisp Examples

ELisp Write Major Mode


Emacs Lisp

Basics

Basic Functions

Writing Command

Writing Script

Lisp Data Structure

Lisp Symbol

Elisp Misc