First line of function doc string should mention the most important

args, in order.

diff --git a/lispref/tips.texi b/lispref/tips.texi
index 592a0015e7563536a857bd4a17e757b826bcf9d2..f10108d2d5834b8fd9534fab8ce6bcd4010c9d86 100644 (file)
--- a/lispref/tips.texi
+++ b/lispref/tips.texi
@@ -507,6 +507,14 @@ 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
 variable.  Please use complete sentences for the rest of the text too.
 
+@item
+The first line should mention all the important arguments of the
+function, and should mention them in the order that they are written
+in a function call.  If the function has many arguments, then it is
+not feasible to mention them all in the first line; in that case, the
+first line should mention the first few arguments, including the most
+important arguments.
+
 @item
 For consistency, phrase the verb in the first sentence of a function's
 documentation string as an imperative--for instance, use ``Return the