Elisp: Doc String Markup

By Xah Lee. Date: . Last updated: .

This page shows emacs function doc string convention and markup.

emacs describe-function 2020-12-04 qxy5z
emacs describe-function output. (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_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:

emacs doc string 2020-12-04 BJ4qG
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.)

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

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