Mercurial > emacs
comparison lispref/tips.texi @ 40970:fb31125d0d7b
Say what questions first line of doc string should answer.
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Tue, 13 Nov 2001 02:20:53 +0000 |
parents | ec17075b77aa |
children | 7359d6d75a9c |
comparison
equal
deleted
inserted
replaced
40969:57ff4380e1fe | 40970:fb31125d0d7b |
---|---|
487 complete sentences that stand on their own as a summary. @kbd{M-x | 487 complete sentences that stand on their own as a summary. @kbd{M-x |
488 apropos} displays just the first line, and if that line's contents don't | 488 apropos} displays just the first line, and if that line's contents don't |
489 stand on their own, the result looks bad. In particular, start the | 489 stand on their own, the result looks bad. In particular, start the |
490 first line with a capital letter and end with a period. | 490 first line with a capital letter and end with a period. |
491 | 491 |
492 The documentation string is not limited to one line; use as many lines | 492 For a function, the first line should briefly answer the question, |
493 as you need to explain the details of how to use the function or | 493 ``What does this function do?'' For a variable, the first line should |
494 variable. Please use complete sentences in the additional lines. | 494 briefly answer the question, ``What does this value mean?'' |
495 | |
496 Don't limit the documentation string to one line; use as many lines as | |
497 you need to explain the details of how to use the function or | |
498 variable. Please use complete sentences for the rest of the text too. | |
495 | 499 |
496 @item | 500 @item |
497 For consistency, phrase the verb in the first sentence of a function's | 501 For consistency, phrase the verb in the first sentence of a function's |
498 documentation string as an imperative--for instance, use ``Return the | 502 documentation string as an imperative--for instance, use ``Return the |
499 cons of A and B.'' in preference to ``Returns the cons of A and B@.'' | 503 cons of A and B.'' in preference to ``Returns the cons of A and B@.'' |