From: Richard M. Stallman <rms@gnu.org>
Date: Mon, 24 Feb 2003 16:48:54 +0000 (+0000)
Subject: First line of function doc string should mention the most important
X-Git-Tag: ttn-vms-21-2-B4~11049
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=7878d6b6c14e7d71980a2e30dd6b46177763c346;p=emacs.git

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 592a0015e75..f10108d2d58 100644
--- 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