RE: Argument names in Elisp Reference vs docstrings

["Drew Adams" <drew.adams@oracle.com>]

    > I didn't realize this was already decided. Are these default values
    > accessed via repeated M-n?

    Yes, very much like values from the history list are accessed via
    repeated M-p.

I followed the discussion; I just didn't realize a decision had been made.

    > 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?"

    I agree with your reasoning.  But OTOH there are many argument names
    which are adjectives like "existing" and "special".

When the meaning is clear from the context, there is no problem with using
an adjective. `completing-read' has many arguments, and it's not clear, a
priori, what "initial" might mean in that context.

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

    As there exist already only three different argument names: "initial",
    "initial-contents" and "initial-input", I'd choose one of existing names
    instead of introducing new names like "init-val" or "initial-value".

If you're improving the names, there is no need to settle for a name that
exists, if a better name is available. However, "initial-input" and
"initial-contents" are as good as "initial-value" here.  If you use
"default-value", then "initial-value" is good; if you use
"default-contents", then "initial-contents" is good; etc. - for consistency.
If you use just "default", any of the "init*-*" are fine.

(BTW, there is one way in which "init-value" could be less clear than
"initial-value" in some contexts. It might suggest the act of initializing
some value, e.g. as a flag. However, in the context of completing-read, this
is not a problem.)

Anyway, enough belaboring on my part...  I desist henceforth ;-)