From 5a5e36d2aad77a4eb80249895d809187630eacc8 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Thu, 23 Nov 2023 17:26:09 +0200 Subject: [PATCH] ; 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 -- 2.39.5