Re: Argument names in Elisp Reference vs docstrings

["Richard M. Stallman" <rms@gnu.org>]

    > I don't like "collection" very much.

    "collection" is used in the Emacs Lisp Reference Manual for the
    functions `try-completion', `all-completions', `test-completion'
    and `completing-read'.

`collection' is the best name I could think of for this purpose,
but I don't think it is a very good one.  It would be nice to
find something better.

    Perhaps a better name for this argument is "completions".

It doesn't feel right to me, because usually we use plural
names as arguments when they refer to a list of values.
`completions' would be appropriate for a list of completions,
but it doesn't quite fit for an alist, an obarray, or a hash table,
or a function to test them.

    >       nospace, hide-spaces
    >
    > "nospace" and "hide-spaces" suggest different meanings.  I don't know
    > how they are actually used, but it is possible that it is better to
    > keep them both.

    Both argument names are used for the same function `all-completions':
    "hide-spaces" is used in the docstring, and "nospace" - in the
    Emacs Lisp Reference Manual.

I think `nospace' is clearer for this meaning.

    >       history, hist
    >
    > The only possible reason not to change "hist" to "history"
    > is to save space.

    If the meaning of "hist" is as clear as "history", then it could
    be used consistently in other functions as well.

`hist' is not quite as clear.  If there is plenty of space, `history'
is better than `hist'.

    >       require-match, mustmatch, must-match, existing
    >
    > This seems like a good case to standardize, but it is possible
    > that there is a reason to use "existing" in a specific case.

    "existing" is used only in the Emacs Lisp Reference Manual.

For the function `read-buffer', the name `existing' fits better
semantically, since t means the argument must name an existing buffer.
You could say that it "must match" the name of an existing buffer, but
that is not as natural.  Likewise for `read-file-name' and perhaps
other similar functions.

However, for `completing-read', the concept of `match' fits better.
So `must-match' would be the best name ot use.