483 |
a running Emacs. |
a running Emacs. |
484 |
|
|
485 |
@item |
@item |
486 |
|
Format the documentation string so that it fits in an Emacs window on an |
487 |
|
80-column screen. It is a good idea for most lines to be no wider than |
488 |
|
60 characters. The first line should not be wider than 67 characters |
489 |
|
or it will look bad in the output of @code{apropos}. |
490 |
|
|
491 |
|
You can fill the text if that looks good. However, rather than blindly |
492 |
|
filling the entire documentation string, you can often make it much more |
493 |
|
readable by choosing certain line breaks with care. Use blank lines |
494 |
|
between topics if the documentation string is long. |
495 |
|
|
496 |
|
@item |
497 |
The first line of the documentation string should consist of one or two |
The first line of the documentation string should consist of one or two |
498 |
complete sentences that stand on their own as a summary. @kbd{M-x |
complete sentences that stand on their own as a summary. @kbd{M-x |
499 |
apropos} displays just the first line, and if that line's contents don't |
apropos} displays just the first line, and if that line's contents don't |
514 |
cons of A and B.'' in preference to ``Returns the cons of A and B@.'' |
cons of A and B.'' in preference to ``Returns the cons of A and B@.'' |
515 |
Usually it looks good to do likewise for the rest of the first |
Usually it looks good to do likewise for the rest of the first |
516 |
paragraph. Subsequent paragraphs usually look better if each sentence |
paragraph. Subsequent paragraphs usually look better if each sentence |
517 |
has a proper subject. |
is indicative and has a proper subject. |
518 |
|
|
519 |
@item |
@item |
520 |
Write documentation strings in the active voice, not the passive, and in |
Write documentation strings in the active voice, not the passive, and in |
538 |
|
|
539 |
@item |
@item |
540 |
Do not start or end a documentation string with whitespace. |
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. |
|
541 |
|
|
542 |
@item |
@item |
543 |
@strong{Do not} indent subsequent lines of a documentation string so |
@strong{Do not} indent subsequent lines of a documentation string so |