comparison lispref/tips.texi @ 42979:7359d6d75a9c

Minor cleanups.

42978:dcc8ffab2cec

by using a comment instead of a documentation string, but that is no
longer the case---documentation strings now take up very little space in
a running Emacs.

@item
The first line of the documentation string should consist of one or two
complete sentences that stand on their own as a summary.  @kbd{M-x
apropos} displays just the first line, and if that line's contents don't
stand on their own, the result looks bad.  In particular, start the
first line with a capital letter and end with a period.

For consistency, phrase the verb in the first sentence of a function's
documentation string as an imperative--for instance, use ``Return the
cons of A and B.'' in preference to ``Returns the cons of A and B@.''
Usually it looks good to do likewise for the rest of the first
paragraph.  Subsequent paragraphs usually look better if each sentence
has a proper subject.

@item
Write documentation strings in the active voice, not the passive, and in
the present tense, not the future.  For instance, use ``Return a list
containing A and B.'' instead of ``A list containing A and B will be

In Dired, visit the file or directory named on this line.
@end example

@item
Do not start or end a documentation string with whitespace.

@item
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 should not be wider than 67 characters
or it will look bad in the output of @code{apropos}.

You can fill the text if that looks good.  However, rather than blindly
filling the entire documentation string, you can often make it much more
readable by choosing certain line breaks with care.  Use blank lines
between topics if the documentation string is long.
 
@item
@strong{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

42979:7359d6d75a9c

by using a comment instead of a documentation string, but that is no
longer the case---documentation strings now take up very little space in
a running Emacs.

@item
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 should not be wider than 67 characters
or it will look bad in the output of @code{apropos}.

You can fill the text if that looks good.  However, rather than blindly
filling the entire documentation string, you can often make it much more
readable by choosing certain line breaks with care.  Use blank lines
between topics if the documentation string is long.

@item
The first line of the documentation string should consist of one or two
complete sentences that stand on their own as a summary.  @kbd{M-x
apropos} displays just the first line, and if that line's contents don't
stand on their own, the result looks bad.  In particular, start the
first line with a capital letter and end with a period.

For consistency, phrase the verb in the first sentence of a function's
documentation string as an imperative--for instance, use ``Return the
cons of A and B.'' in preference to ``Returns the cons of A and B@.''
Usually it looks good to do likewise for the rest of the first
paragraph.  Subsequent paragraphs usually look better if each sentence
is indicative and has a proper subject.

@item
Write documentation strings in the active voice, not the passive, and in
the present tense, not the future.  For instance, use ``Return a list
containing A and B.'' instead of ``A list containing A and B will be

In Dired, visit the file or directory named on this line.
@end example

@item
Do not start or end a documentation string with whitespace.
 
@item
@strong{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