Use of "optional argument" in docstring

Use of "optional argument" in docstring

[Bill Wohler]

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 <wohler@newt.com>  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.

Use of "optional argument" in docstring

[Nick Roberts]

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

Re: Use of "optional argument" in docstring

[Lennart Borgman]

Nick Roberts wrote:

>Bill Wohler writes:
>
> > 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.
>  
>
To me this looks better, "is given" is enough.

Re: Use of "optional argument" in docstring

[Bill Wohler]

Nick Roberts <nickrob@snap.net.nz> wrote:

> In all the examples that I looked at optional arguments are explicitly
> described as such.

Old, or new functions? I see it predominantly in older functions and
less so in new functions.

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

Yes, of course, but we're not talking about that. I'm asking what one
should use for new functions (or functions one is editing).

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.

-- 
Bill Wohler <wohler@newt.com>  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.

Re: Use of "optional argument" in docstring

[Nick Roberts]

 > > In all the examples that I looked at optional arguments are explicitly
 > > described as such.
 > 
 > Old, or new functions? I see it predominantly in older functions and
 > less so in new functions.

Yes, you're right.  I only looked at old functions.

Nick

Re: Use of "optional argument" in docstring

[Richard M. Stallman]

    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.