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.
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?”
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.
evalrefers to its first argument as ‘FORM’, because the actual argument name is
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.
nilwithout surrounding punctuation. For example:
CODE can be ‘lambda’, nil, or t.
See Quotation Marks in The GNU Emacs Manual, for how to enter curved single quotes.
Documentation strings can also use an older single-quoting convention, which quotes symbols with grave accent ` and apostrophe ': `like-this' rather than ‘like-this’. This older convention was designed for now-obsolete displays in which grave accent and apostrophe were mirror images. Documentation using this convention is converted to the user’s preferred format when it is copied into a help buffer. See Substituting Key Bindings in Documentation.
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
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 wesite 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.
In Dired, visit the file or directory named on this line.
defcustom. See Defining Global Variables.
nilvalues are equivalent and indicate explicitly what
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.
We do use these occasionally, but try not to overdo it.