From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Richard M. Stallman" Newsgroups: gmane.emacs.devel Subject: Re: Argument names in Elisp Reference vs docstrings Date: Wed, 14 Sep 2005 10:08:04 -0400 Message-ID: References: Reply-To: rms@gnu.org NNTP-Posting-Host: main.gmane.org Content-Type: text/plain; charset=ISO-8859-15 X-Trace: sea.gmane.org 1126709737 27211 80.91.229.2 (14 Sep 2005 14:55:37 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Wed, 14 Sep 2005 14:55:37 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Sep 14 16:55:35 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1EFYeb-0008TE-3w for ged-emacs-devel@m.gmane.org; Wed, 14 Sep 2005 16:54:29 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EFYea-0004d2-Ih for ged-emacs-devel@m.gmane.org; Wed, 14 Sep 2005 10:54:28 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1EFYS7-0005ws-2C for emacs-devel@gnu.org; Wed, 14 Sep 2005 10:41:37 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1EFYS5-0005wM-TP for emacs-devel@gnu.org; Wed, 14 Sep 2005 10:41:34 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EFYNi-0003hc-Bt for emacs-devel@gnu.org; Wed, 14 Sep 2005 10:37:02 -0400 Original-Received: from [199.232.76.164] (helo=fencepost.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.34) id 1EFXvh-00017i-8U for emacs-devel@gnu.org; Wed, 14 Sep 2005 10:08:05 -0400 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.34) id 1EFXvg-00051B-QQ; Wed, 14 Sep 2005 10:08:04 -0400 Original-To: lekktu@gmail.com In-reply-to: (message from Juanma Barranquero on Tue, 13 Sep 2005 16:46:54 +0200) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:42923 Archived-At: It is consistency between argument names in docstrings vs argument names in the Emacs Lisp Reference a goal? Yes, more or less. It is not necessary to fix all such discrepancies, but in many cases fixing them would be a step forward. When doing so, it is important to standardize on the better name, not the worse one. In general, a name that describes the meaning is clearer than a name that describes only the data type: make-frame alist parameters PARAMETERS is clearer than ALIST. indirect-function function object FUNCTION is clearer than OBJECT. But sometimes, in a data-access primitive, there is nothing to say about the object except for its data type, as here: setplist symbol plist symbol newplist SYMBOL is a fine name for the symbol used here.. gethash key table default key table dflt This is a special case, because `default' is a keyword in C, so it cannot be used as the argument name. Therefore, the best thing to do is add an explicit calling pattern at the end of the doc string. (That method can be used in other cases too, whenever convenient.) eval-region start end stream ... start end printflag ... That looks like a discrepancy of substance, not just of name. So please check the code and see which one is correct.