procyberian/emacs
1
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
Show stats 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,
``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
you need to explain the details of how to use the function or