From: "Richard M. Stallman" <rms@gnu.org>
Cc: emacs-devel@gnu.org
Subject: Re: Argument names in Elisp Reference vs docstrings
Date: Wed, 14 Sep 2005 10:08:04 -0400 [thread overview]
Message-ID: <E1EFXvg-00051B-QQ@fencepost.gnu.org> (raw)
In-Reply-To: <f7ccd24b0509130746d753356@mail.gmail.com> (message from Juanma Barranquero on Tue, 13 Sep 2005 16:46:54 +0200)
It is consistency between argument names in docstrings vs argument
names in the Emacs Lisp Reference a goal?
Yes, more or less. It is not necessary to fix all such discrepancies,
but in many cases fixing them would be a step forward. When doing so,
it is important to standardize on the better name, not the worse one.
In general, a name that describes the meaning is clearer than
a name that describes only the data type:
make-frame alist parameters
PARAMETERS is clearer than ALIST.
indirect-function function object
FUNCTION is clearer than OBJECT.
But sometimes, in a data-access primitive, there is nothing to say
about the object except for its data type, as here:
setplist symbol plist symbol newplist
SYMBOL is a fine name for the symbol used here..
gethash key table default key table dflt
This is a special case, because `default' is a keyword in C,
so it cannot be used as the argument name. Therefore, the best thing
to do is add an explicit calling pattern at the end of the doc string.
(That method can be used in other cases too, whenever convenient.)
eval-region start end stream ... start end printflag ...
That looks like a discrepancy of substance, not just of name.
So please check the code and see which one is correct.
next prev parent reply other threads:[~2005-09-14 14:08 UTC|newest]
Thread overview: 20+ messages / expand[flat|nested] mbox.gz Atom feed top
2005-09-13 14:46 Argument names in Elisp Reference vs docstrings Juanma Barranquero
2005-09-14 14:08 ` Richard M. Stallman [this message]
2005-09-15 22:03 ` Juri Linkov
2005-09-16 12:02 ` Andreas Schwab
2005-09-16 22:14 ` Juri Linkov
2005-09-16 12:59 ` Richard M. Stallman
2005-09-16 22:16 ` Juri Linkov
2005-09-17 13:39 ` Richard M. Stallman
2005-09-17 14:30 ` Drew Adams
2005-09-17 20:20 ` Robert J. Chassell
2005-09-19 15:54 ` Drew Adams
2005-09-19 17:15 ` Robert J. Chassell
2005-09-19 1:31 ` Richard M. Stallman
2005-09-19 8:04 ` Kim F. Storm
2005-09-16 14:59 ` Drew Adams
2005-09-16 15:28 ` Juanma Barranquero
2005-09-16 22:17 ` Juri Linkov
2005-09-16 23:19 ` Drew Adams
2005-09-16 23:48 ` Juri Linkov
2005-09-17 0:53 ` Drew Adams
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
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=E1EFXvg-00051B-QQ@fencepost.gnu.org \
--to=rms@gnu.org \
--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 public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).