(elisp)Documentation Tips


Next: Comment Tips Prev: Compilation Tips Up: Tips

Tips for Documentation Strings
==============================

   Here are some tips for the writing of documentation strings.

   * Every command, function or variable intended for users to know
     about should have a documentation string.

   * An internal subroutine of a Lisp program need not have a
     documentation string, and you can save space by using a comment
     instead.

   * The first line of the documentation string should consist of one
     or two complete sentences which stand on their own as a summary.
     In particular, start the line with a capital letter and end with a
     period.

     The documentation string can have additional lines which expand on
     the details of how to use the function or variable.  The
     additional lines should be made up of complete sentences also, but
     they may be filled if that looks good.

   * Do not start or end a documentation string with whitespace.

   * Format the documentation string so that it fits in an Emacs window
     on an 80 column screen.  It is a good idea for most lines to be no
     wider than 60 characters.  The first line can be wider if
     necessary to fit the information that ought to be there.

     However, rather than simply filling the entire documentation
     string, you can make it much more readable by choosing line breaks
     with care.  Use blank lines between topics if the documentation
     string is long.

   * *Do not* indent subsequent lines of a documentation string so that
     the text is lined up in the source code with the text of the first
     line.  This looks nice in the source code, but looks bizarre when
     users view the documentation.  Remember that the indentation
     before the starting double-quote is not part of the string!

   * A variable's documentation string should start with `*' if the
     variable is one that users would want to set interactively often.
     If the value is a long list, or a function, or if the variable
     would only be set in init files, then don't start the
     documentation string with `*'.  Note: Defining Variables.

   * The documentation string for a variable that is a yes-or-no flag
     should start with words such as "Non-nil means...", to make it
     clear both that the variable only has two meaningfully distinct
     values and which value means "yes".

   * When a function's documentation string mentions the value of an
     argument of the function, use the argument name in capital letters
     as if it were a name for that value.  Thus, the documentation
     string of the function `/' refers to its second argument as
     `DIVISOR'.

     Also use all caps for meta-syntactic variables, such as when you
     show the decomposition of a list or vector into subunits, some of
     which may be variable.

   * When a documentation string refers to a Lisp symbol, write it as it
     would be printed (which usually means in lower case), with
     single-quotes around it.  For example: ``lambda''.  There are two
     exceptions: write `t' and `nil' without single-quotes.

   * Don't write key sequences directly in documentation strings.
     Instead, use the `\\[...]' construct to stand for them.  For
     example, instead of writing `C-f', write `\\[forward-char]'.  When
     the documentation string is printed, Emacs will substitute
     whatever key is currently bound to `forward-char'.  This will
     usually be `C-f', but if the user has moved key bindings, it will
     be the correct key for that user.  Note: Keys in Documentation.

   * In documentation strings for a major mode, you will want to refer
     to the key bindings of that mode's local map, rather than global
     ones.  Therefore, use the construct `\\<...>' once in the
     documentation string to specify which key map to use.  Do this
     before the first use of `\\[...]'.  The text inside the `\\<...>'
     should be the name of the variable containing the local keymap for
     the major mode.

     It is not practical to use `\\[...]' very many times, because
     display of the documentation string will become slow.  So use this
     to describe the most important commands in your major mode, and
     then use `\\{...}' to display the rest of the mode's keymap.

   * Don't use the term "Elisp", since that is or was a trademark.  Use
     the term "Emacs Lisp".


automatically generated by info2www