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: Use of "optional argument" in docstring Date: Sat, 03 Dec 2005 10:58:09 -0500 Message-ID: References: <22334.1133559098@olgas.newt.com> Reply-To: rms@gnu.org NNTP-Posting-Host: main.gmane.org Content-Type: text/plain; charset=ISO-8859-15 X-Trace: sea.gmane.org 1133625673 21784 80.91.229.2 (3 Dec 2005 16:01:13 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 3 Dec 2005 16:01:13 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 03 17:01:08 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1EiZnJ-00039t-5G for ged-emacs-devel@m.gmane.org; Sat, 03 Dec 2005 16:59:25 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EiZnL-0008Q9-BW for ged-emacs-devel@m.gmane.org; Sat, 03 Dec 2005 10:59:27 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1EiZmK-0007RM-HS for emacs-devel@gnu.org; Sat, 03 Dec 2005 10:58:24 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1EiZmI-0007Ne-4H for emacs-devel@gnu.org; Sat, 03 Dec 2005 10:58:22 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EiZmF-0007NC-SF for emacs-devel@gnu.org; Sat, 03 Dec 2005 10:58:21 -0500 Original-Received: from [199.232.76.164] (helo=fencepost.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.34) id 1EiZmQ-0005h3-F5 for emacs-devel@gnu.org; Sat, 03 Dec 2005 10:58:30 -0500 Original-Received: from rms by fencepost.gnu.org with local (Exim 4.34) id 1EiZm5-0005uE-4J; Sat, 03 Dec 2005 10:58:09 -0500 Original-To: Bill Wohler In-reply-to: <22334.1133559098@olgas.newt.com> (message from Bill Wohler on Fri, 02 Dec 2005 13:31:38 -0800) 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:46936 Archived-At: Is there a convention regarding the use of explicitly using the word "optional" when describing an optional argument in the docstring? It is not a firm convention, and I would rather not make it one, since that would entail a lot of changes all around Emacs. So do what you think is best. However, "second optional argument" could be misleading. In (log arg &optional base) BASE is the second argument, but it is not the second optional argument. Therefore, the current text is bad. "Optional second argument" would avoid that problem. However, when there are so few arguments, it is not particularly helpful to mention the numeric position of an argument. Thus, deleting "second" would be good here. I will do that. I also think the documentation often reads better if the number and the word "argument" is dropped. For example, in the example above, "If BASE is given..." I think that would be clear enough. Howewer, I think "the optional argument" doesn't hurt, and it reads well here. So I see no reason to delete it. I suspect that the convention of using "optional second argument" comes from a day before Emacs printed the function spec in the *Help* buffer. If that had been the case, that docstring convention would have been imperative. It seems possible that the reason to use "optional second argument" no longer exists. That is what I recall, too.