[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Use of "optional argument" in docstring

From: Bill Wohler
Subject: Use of "optional argument" in docstring
Date: Fri, 02 Dec 2005 13:31:38 -0800

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 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).

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..." 

Bill Wohler <address@hidden>  http://www.newt.com/wohler/  GnuPG ID:610BD9AD
Maintainer of comp.mail.mh FAQ and MH-E. Vote Libertarian!
If you're passed on the right, you're in the wrong lane.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]