RE: Argument names in Elisp Reference vs docstrings

[Drew Adams]

    I propose to standardize on the following arguments names:

      prompt
      initial
      history
      defaults
      inherit-im
      must-match
      collection
      no-space
      directory

    Most of these names are shorter than current names, but still
    intelligible.
    Since `default' is a keyword in C, `defaults' is a good replacement.
    `inherit-im' is twice shorter than `inherit-input-method' and the `IM'
    abbreviation is already mentioned in the Emacs manual.

I think it hasn't been decided whether to allow more than one default value
in the upcoming release. 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". "Init" clearly stands for "initial", but the "value" part is
important - "initial" by itself doesn't mean much (initial what?).

BTW, must the C parameter (implementation) name be identical to the Lisp
name? It seems a bit limiting that we cannot pick a name ("default"), simply
because C already has "default" as a reserved word. That suggests to me that
there might be too tight a coupling between the C language and its use in
coding Emacs primitives. If it is just a question of a coding convention
that might be stretched or even violated, I would think that ease in
understanding by _users_ would trump respect of the coding convention - an
appropriate comment could clarify any non-standard name used in the
implementation code.