[Top][All Lists]

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

Re: Use of "optional argument" in docstring

From: Richard M. Stallman
Subject: Re: Use of "optional argument" in docstring
Date: Sat, 03 Dec 2005 10:58:09 -0500

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

reply via email to

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