Emacs Lisp: Function Doc String Markup
Emacs lisp function doc string support markup to indicate links, parameters, keybinding, etc that are shown when you Alt + x describe-function.
Example:
(defun xx (arg1 arg2) "One short line summary. Should be Less than 67 chars. Detail here. Mention return value. No indentation. ARG1 spec. ARG2 spec. 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. \\{emacs-lisp-mode-map}" (interactive) (message "%s" "something.") )
Here's how it shows:
describe-function output.
note the clickable links, italics, and keybinding.
docstring markup
ALLCAPS- Function parameter names are in ALLCAPS by Emacs convention. No special behavior.
`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:
\\{emacs-lisp-mode-map}.
[see Emacs Lisp: How to Create Keymap for Major Mode]
Reference
2014-05-27 thanks to jcs [http://irreal.org/blog/?p=2715] for tips.
