From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Nick Roberts Newsgroups: gmane.emacs.devel Subject: Use of "optional argument" in docstring Date: Sat, 3 Dec 2005 10:49:42 +1300 Message-ID: <17296.49526.166588.17581@kahikatea.snap.net.nz> References: <22334.1133559098@olgas.newt.com> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1133560343 5243 80.91.229.2 (2 Dec 2005 21:52:23 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Fri, 2 Dec 2005 21:52:23 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 02 22:52:21 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1EiInI-0006Ir-NW for ged-emacs-devel@m.gmane.org; Fri, 02 Dec 2005 22:50:17 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EiInI-0001hu-PY for ged-emacs-devel@m.gmane.org; Fri, 02 Dec 2005 16:50:16 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1EiIn4-0001he-26 for emacs-devel@gnu.org; Fri, 02 Dec 2005 16:50:02 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1EiIn2-0001hO-EF for emacs-devel@gnu.org; Fri, 02 Dec 2005 16:50:01 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1EiIn2-0001hL-7U for emacs-devel@gnu.org; Fri, 02 Dec 2005 16:50:00 -0500 Original-Received: from [202.37.101.8] (helo=viper.snap.net.nz) by monty-python.gnu.org with esmtp (Exim 4.34) id 1EiIn4-0004oB-Ei for emacs-devel@gnu.org; Fri, 02 Dec 2005 16:50:02 -0500 Original-Received: from kahikatea.snap.net.nz (p233-tnt1.snap.net.nz [202.124.110.233]) by viper.snap.net.nz (Postfix) with ESMTP id EC3A5731578; Sat, 3 Dec 2005 10:49:55 +1300 (NZDT) Original-Received: by kahikatea.snap.net.nz (Postfix, from userid 500) id A222F8420; Sat, 3 Dec 2005 10:49:42 +1300 (NZDT) Original-To: Bill Wohler In-Reply-To: <22334.1133559098@olgas.newt.com> X-Mailer: VM 7.19 under Emacs 22.0.50.11 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:46907 Archived-At: Bill Wohler writes: > Is there a convention regarding the use of explicitly using the word > "optional" when describing an optional argument in the docstring? > > For example: > > (log arg &optional base) > > Return the natural logarithm of ARG. > If second optional argument BASE is given, return log arg using that base. > ^^^^^^^^ I think that should read: If optional second argument BASE is given, return log arg using that base. Given that BASE is the *only* optional argument, I think it could also read: If optional argument BASE is given, return log arg using that base. > I didn't see one in "Documentation Tips" and a brief survey of the code > shows that folks go either way. > > It seems redundant to me since the text "&optional" appears in the > function's spec in the *Help* buffer. However, I'd prefer to go with the > flow (if I knew what it was). In all the examples that I looked at optional arguments are explicitly described as such. > 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..." Maybe but it would be a lot of work to change now. Nick