[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Use of "optional argument" in docstring
From: |
Nick Roberts |
Subject: |
Use of "optional argument" in docstring |
Date: |
Sat, 3 Dec 2005 10:49:42 +1300 |
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