emacs-29 5a5e36d2aad: ; Improve function documentation tips

[Eli Zaretskii]

branch: emacs-29
commit 5a5e36d2aad77a4eb80249895d809187630eacc8
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Improve function documentation tips
    
    * doc/lispref/tips.texi (Documentation Tips): Clarify the good
    style of descriptions in doc strings.
---
 doc/lispref/tips.texi | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index db9f64aa8a0..f0d4753e41b 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -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