procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; Improve function documentation tips

Browse source 
* doc/lispref/tips.texi (Documentation Tips): Clarify the good
style of descriptions in doc strings.
This commit is contained in:
Eli Zaretskii 2023-11-23 17:26:09 +02:00
parent 86016d8ecd
commit 5a5e36d2aa
1 changed files with 6 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

7
doc/lispref/tips.texi
View file

@ -631,7 +631,12 @@ first line with a capital letter and end it with a period.
For a function, the first line should briefly answer the question, For a function, the first line should briefly answer the question,
``What does this function do?'' For a variable, the first line should ``What does this function do?'' For a variable, the first line should
briefly answer the question, ``What does this value mean?'' briefly answer the question, ``What does this value mean?'' Prefer to
answer these questions in a way that will make sense to users and
callers of the function or the variable. In particular, do @emph{not}
tell what the function does by enumerating the actions of its code;
instead, describe the role of these actions and the function's
contract.
Don't limit the documentation string to one line; use as many lines as Don't limit the documentation string to one line; use as many lines as
you need to explain the details of how to use the function or you need to explain the details of how to use the function or