Use of "optional argument" in docstring

[Nick Roberts <nickrob@snap.net.nz>]

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