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'll notice these features:
To have these features, you need to put markups in your inline string.
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.)
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.
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." ;… ))
To have a clickable URL, do like this:
URL `http://example.org/'. Example:
(defun xlsl-mode () "… See URL `http://xahsl.org/sl/ls-emacs.html'." )
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'." )
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〕
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. …" )
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}" ;… )
| Example | Purpose |
|---|---|
ALLCAPS | function arguments |
`sort-lines' | link to other functions |
URL `http://example.org/' | link to URL |
Info node `(emacs) Dired' | link to Info doc node |
\\[backward-word] | Keyboard shortcut for a command |
\\{c-mode-map} | list of keybindings |