From: Nick Roberts <nickrob@snap.net.nz>
Cc: emacs-devel@gnu.org
Subject: Use of "optional argument" in docstring
Date: Sat, 3 Dec 2005 10:49:42 +1300 [thread overview]
Message-ID: <17296.49526.166588.17581@kahikatea.snap.net.nz> (raw)
In-Reply-To: <22334.1133559098@olgas.newt.com>
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
next prev parent reply other threads:[~2005-12-02 21:49 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2005-12-02 21:31 Use of "optional argument" in docstring Bill Wohler
2005-12-02 21:49 ` Nick Roberts [this message]
2005-12-02 21:55 ` Lennart Borgman
2005-12-02 22:25 ` Bill Wohler
2005-12-02 22:43 ` Nick Roberts
2005-12-03 15:58 ` Richard M. Stallman
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=17296.49526.166588.17581@kahikatea.snap.net.nz \
--to=nickrob@snap.net.nz \
--cc=emacs-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.