From: Eli Zaretskii Date: Thu, 23 Nov 2023 15:26:09 +0000 (+0200) Subject: ; Improve function documentation tips X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=5a5e36d2aad77a4eb80249895d809187630eacc8;p=emacs.git ; Improve function documentation tips * doc/lispref/tips.texi (Documentation Tips): Clarify the good style of descriptions in doc strings. --- 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