Emacs Lisp: Inline Docstring Markup

Xah Lee, 2010-01-13

This page is a tutorial on writing the inline doc string for function's definition in emacs.

When you write a elisp function, for example:

(defun insert-p-tag ()
  "Insert <p></p> at cursor point."
  (interactive)
  (insert "<p></p>")
  (backward-char 4))

There are some conventions and some markup you need to know. For example, when you lookup a function's doc by calling describe-function 【F1 f】, you notice that the function's parameters are italized, if the doc contains other function's name, you can click on it to go to that function's doc string. Also, the doc string can contain a clickable URL that takes user to the page using default web browser. You can mention keyboard shortcuts for other commands and it will show correctly even if user have changed it. To have these features, you need to put markups in your inline string.

Tips on Writing Inline Doc

Short Summary in First Line

The first line of your doc string should be a one sentence summary of the function. Because, apropos-command 【F1 a】 will display just that line.

The inline 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.)

Italized Parameter Names

When your function takes arguments, their names in the inline string should be all CAPS. Example:

(defun read-lines (file-path) 
  "Return a list of lines of a file at FILE-PATH." 
  (with-temp-buffer 
    (insert-file-contents file) 
    (split-string (buffer-string) "\n" t)))

This way, when describe-function displays it, the arg will be automatically italized.

Clickable Function Names

If your doc mentions another function, user can click on it, so it takes them to that function's inline doc. To make it clickable, you need to quote it with `…'. Example:

(defun auto-fill-mode (&optional arg)
  "Toggle Auto Fill mode.
With ARG, turn Auto Fill mode on if and only if ARG is positive.
In Auto Fill mode, inserting a space at a column beyond `current-fill-column'
automatically breaks the line at a previous space.

The value of `normal-auto-fill-function' specifies the function to use
for `auto-fill-function' when turning Auto Fill mode on."
  ;…
    ))

Clickable URL

To have a clickable URL, do like this: URL `http://xahlee.org/emacs/emacs.html'. Example:

(defun xlsl-mode ()
  "Major mode for editing LSL (Linden Scripting Language).
…
Complete documentation at URL `http://xahlee.org/sl/ls-emacs.html'."
  ; …
)

Links to Emacs Info Doc

Sometimes you want clickable links to emacs's doc. You can mark it like this: Info node `(elisp)Font Lock Basics'.

(defun xx ()
  "…
 See Info node `(emacs) Dired' and Info node `(elisp)Font Lock Basics'."
  ; …
  )

Remember, each page in info doc is identified by a string, for examples: (emacs) Dired, (elisp)Font Lock Basics. 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”.

But also note, emacs's info node may change or disappear with new emacs versions. 〔☛ Emacs Manual Node Persistency Issues〕

Auto Generate Shortcut Keys

In your inline doc you may need to tell users about pressing a keyboard shortcut to do something. For example, in dired, when you call describe-major-mode, the doc says: “Type C to Copy files.”. If a user has customized dired's keys, the inline doc will correctly display the new key.

To make shortcuts of a command automatically show correctly, you need to quote the command name by \\[…]. Here's a example from dired:

(defun dired-mode (&optional dirname switches)
  "\
Mode for \"editing\" directory listings.
…
Type \\[dired-do-copy] to Copy files.
…"
)

Auto Generated Keybinding List

A major mode usually has its own set of keyboard shortcuts (its own keymap). For example, in c-mode, call describe-major-mode 【F1 m】, 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 \\{…}. 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}"
;…
)

Inline Doc Markup Summary

(info "(elisp)Documentation Tips")