(lispref.info)Function Documentation


Prev: Argument List Up: Lambda Expressions

Documentation Strings of Functions
----------------------------------

   A lambda expression may optionally have a "documentation string" just
after the lambda list.  This string does not affect execution of the
function; it is a kind of comment, but a systematized comment which
actually appears inside the Lisp world and can be used by the Emacs help
facilities.  Note: Documentation, for how the DOCUMENTATION-STRING is
accessed.

   It is a good idea to provide documentation strings for all commands,
and for all other functions in your program that users of your program
should know about; internal functions might as well have only comments,
since comments don't take up any room when your program is loaded.

   The first line of the documentation string should stand on its own,
because `apropos' displays just this first line.  It should consist of
one or two complete sentences that summarize the function's purpose.

   The start of the documentation string is usually indented, but since
these spaces come before the starting double-quote, they are not part of
the string.  Some people make a practice of indenting any additional
lines of the string so that the text lines up.  *This is a mistake.*
The indentation of the following lines is inside the string; what looks
nice in the source code will look ugly when displayed by the help
commands.

   You may wonder how the documentation string could be optional, since
there are required components of the function that follow it (the body).
Since evaluation of a string returns that string, without any side
effects, it has no effect if it is not the last form in the body.
Thus, in practice, there is no confusion between the first form of the
body and the documentation string; if the only body form is a string
then it serves both as the return value and as the documentation.


automatically generated by info2www