comparison lispref/tips.texi @ 71957:61cb5aae3bc3

Put period and comma inside quotes.

71956:1caee6e0cbe1

use @code{defvar} instead, start the doc string with a @samp{*}.
@xref{Defining Variables}.

@item
The documentation string for a variable that is a yes-or-no flag should
start with words such as ``Non-nil means@dots{}'', to make it clear that
all non-@code{nil} values are equivalent and indicate explicitly what
@code{nil} and non-@code{nil} mean.

@item
The documentation string for a function that is a yes-or-no predicate
should start with words such as ``Return t if @dots{}'', to indicate
explicitly what constitutes ``truth''.  The word ``return'' avoids
starting the sentence with lower-case ``t'', which is somewhat
distracting.

@item
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

have the form (KEY . VALUE).  Here, KEY is ...
@end example

@item
Never change the case of a Lisp symbol when you mention it in a doc
string.  If the symbol's name is @code{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
@emph{value} is not the same thing as the @emph{symbol} which the

71957:61cb5aae3bc3

use @code{defvar} instead, start the doc string with a @samp{*}.
@xref{Defining Variables}.

@item
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 that
all non-@code{nil} values are equivalent and indicate explicitly what
@code{nil} and non-@code{nil} mean.

@item
The documentation string for a function that is a yes-or-no predicate
should start with words such as ``Return t if,'' to indicate
explicitly what constitutes ``truth.''  The word ``return'' avoids
starting the sentence with lower-case ``t,'' which could be somewhat
distracting.

@item
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

have the form (KEY . VALUE).  Here, KEY is ...
@end example

@item
Never change the case of a Lisp symbol when you mention it in a doc
string.  If the symbol's name is @code{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
@emph{value} is not the same thing as the @emph{symbol} which the