Here are some tips and conventions for the writing of documentation strings. You can check many of these conventions by running the command M-x checkdoc-minor-mode.
apropos
.
You can fill the text if that looks good. Emacs Lisp mode fills
documentation strings to the width specified by
emacs-lisp-docstring-fill-column
. However, you can sometimes
make a documentation string much more readable by adjusting its line
breaks with care. Use blank lines between sections if the
documentation string is long.
For a function, the first line should briefly answer the question, “What does this function do?” For a variable, the first line should briefly answer the question, “What does this value mean?” Prefer to answer these questions in a way that will make sense to users and callers of the function or the variable. In particular, do not tell what the function does by enumerating the actions of its code; instead, describe the role of these actions and the function’s contract.
Don’t limit the documentation string to one line; use as many lines as you need to explain the details of how to use the function or variable. Please use complete sentences for the rest of the text too.
eval
refers to its first argument as ‘FORM’, because the
actual argument name is form
:
Evaluate FORM and return its value.
Also write metasyntactic variables in capital letters, such as when you show the decomposition of a list or vector into subunits, some of which may vary. ‘KEY’ and ‘VALUE’ in the following example illustrate this practice:
The argument TABLE should be an alist whose elements have the form (KEY . VALUE). Here, KEY is ...
foo
, write “foo”, not
“Foo” (which is a different symbol).
This might appear to contradict the policy of writing function argument values, but there is no real contradiction; the argument value is not the same thing as the symbol that the function uses to hold the value.
If this puts a lower-case letter at the beginning of a sentence and that annoys you, rewrite the sentence so that the symbol is not at the start of it.
t
and nil
without surrounding
punctuation. For example:
CODE can be `lambda', nil, or t.
Note that when Emacs displays these doc strings, Emacs will usually display ‘`’ (grave accent) as ‘‘’ (left single quotation mark) and ‘'’ (apostrophe) as ‘’’ (right single quotation mark), if the display supports displaying these characters. See Substituting Key Bindings in Documentation. (Some previous versions of this section recommended using the non-ASCII single quotation marks directly in doc strings, but this is now discouraged, since that leads to broken help string displays on terminals that don’t support displaying those characters.)
Help mode automatically creates a hyperlink when a documentation string uses a single-quoted symbol name, if the symbol has either a function or a variable definition. You do not need to do anything special to make use of this feature. However, when a symbol has both a function definition and a variable definition, and you want to refer to just one of them, you can specify which one by writing one of the words ‘variable’, ‘option’, ‘function’, or ‘command’, immediately before the symbol name. (Case makes no difference in recognizing these indicator words.) For example, if you write
This function sets the variable `buffer-file-name'.
then the hyperlink will refer only to the variable documentation of
buffer-file-name
, and not to its function documentation.
If a symbol has a function definition and/or a variable definition, but those are irrelevant to the use of the symbol that you are documenting, you can write the words ‘symbol’ or ‘program’ before the symbol name to prevent making any hyperlink. For example,
If the argument KIND-OF-RESULT is the symbol `list', this function returns a list of all the objects that satisfy the criterion.
does not make a hyperlink to the documentation, irrelevant here, of the
function list
.
Normally, no hyperlink is made for a variable without variable documentation. You can force a hyperlink for such variables by preceding them with one of the words ‘variable’ or ‘option’.
Hyperlinks for faces are only made if the face name is preceded or followed by the word ‘face’. In that case, only the face documentation will be shown, even if the symbol is also defined as a variable or as a function.
To make a hyperlink to Info documentation, write the single-quoted name of the Info node (or anchor), preceded by ‘info node’, ‘Info node’, ‘info anchor’ or ‘Info anchor’. The Info file name defaults to ‘emacs’. For example,
See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
To make a hyperlink to a man page, write the single-quoted name of the man page, preceded by ‘Man page’, ‘man page’, or ‘man page for’. For example,
See the man page `chmod(1)' for details.
The Info documentation is always preferable to man pages, so be sure
to link to an Info manual where available. For example,
chmod
is documented in the GNU Coreutils manual, so it is
better to link to that instead of the man page.
To link to a customization group, write the single-quoted name of the group, preceded by ‘customization group’ (the first character in each word is case-insensitive). For example,
See the customization group `whitespace' for details.
Finally, to create a hyperlink to URLs, write the single-quoted URL, preceded by ‘URL’. For example,
The GNU project website has more information (see URL `https://www.gnu.org/').
forward-char
.
(This is normally ‘C-f’, but it may be some other character if the
user has moved key bindings.) See Substituting Key Bindings in Documentation.
Each use of ‘\\[…]’ slows the display of the documentation string by a tiny amount. If you use a lot of them, these tiny slowdowns will add up, and might become tangible, especially on slow systems. So our recommendation is not to over-use them; e.g., try to avoid using more than one reference to the same command in the same doc string.
dired-find-file
is:
In Dired, visit the file or directory named on this line.
defcustom
. See Defining Global Variables.
nil
values are equivalent and indicate explicitly what
nil
and non-nil
mean.
The argument FOO can be either a number \(a buffer position) or a string (a file name).
This avoids a bug in Emacs versions older than 27.1, where the ‘(’ was treated as the start of a defun (see Defuns in The GNU Emacs Manual). If you do not anticipate anyone editing your code with older Emacs versions, there is no need for this work-around.