Elisp: Doc String Markup
This page shows emacs function doc string convention and markup.

describe-function
output. (note the clickable links.)
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
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 on xah discord.
Or support me by Buy Xah Emacs Tutorial