RE: Argument names in Elisp Reference vs docstrings

[Drew Adams]

    > I think it hasn't been decided whether to allow more than one
    default value
    > in the upcoming release.

    IIUC, Richard decided to allow more than one default value,
    since this is a quite trivial change.

I didn't realize this was already decided. Are these default values accessed
via repeated M-n? Is there any limit (or guideline) on their number?

    > In that case, "defaults" is misleading (that is, incorrect).
    > I suggest "default-value", which is clearer, anyway.
    > Similarly, I think "initial-value" or "init-value" is clearer than
    > "initial".

    I think neither "initial-value" nor "default-value" make the semantics
    of arguments clearer than "initial" or "default".  To understand the
    difference between them, programmers still should consult the
    documentation.

"default" is OK, if there is no problem with the C name conflict. "default"
is commonly abused as shorthand for "default value", at least in software.
(People speak of "the default".)

Yes, to understand the difference between an initial value and a default
value, the doc must be consulted, and that is true _regardless_ of the names
we use. That was not my point about "initial", however - I didn't claim that
"initial-value" would make that distinction clear.

My point was that "init" or "initial" does not by itself indicate an initial
_value_. There are other things that might be initial in this context.
"initial" is not clear in the same way that "default" is clear. People don't
say, "What is the "initial?"

All of the following are clearer than "initial": "init-val", "init-value",
"initial-value".

    > "Init" clearly stands for "initial", but the "value" part is
    > important - "initial" by itself doesn't mean much (initial what?).

    Perhaps simply "init" would be good: it's short, and since it is not
    a real word, it doesn't require a noun like "-value".

I don't get your response here. It's not because "initial" is a real word
that it requires a noun - it's because it's just an adjective. I granted
that "init" abbreviates "initial" adequately. The question is, initial what?
The "value" part is important. "init-val" takes only 2 more characters than
"initial", if that's the worry.