RE: Argument names in Elisp Reference vs docstrings

[Drew Adams]

        > 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.

I would think that plural would be OK for any plural entity (i.e. collection
;-)). (The function case is a bit exceptional, or indirect - it is
essentially an iterator that generates the elements of a plural entity.)

Another term I use for this is (completion) "candidates", because the user
chooses one of them (if completion is used). But that doesn't escape your
problem with using a plural term.

Whether we use a singular or plural term to represent the collective entity
doesn't change much. We can pick "set", "sequence" (except it is also a Lisp
datatype name), "collection", etc. Or we can speak of the "elements",
"completions", "candidates", "items", "members", etc. in such a collective
entity. Changing plural to singular changes doesn't change much, IMO.

And I doubt that people will assume it is a list simply because we use a
plural term. The doc explains the meaning, and you can only signify so much
in the name itself.

        >       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.

I don't have time to check the guidelines right now, but shouldn't a boolean
argument's name end in "-p"? That is, wouldn't "must-match-p" be
conventional (and clearer)?

In any case, I agree with your comments about "must-match" and "existing" -
it is more important for the meaning to be clear wrt the particular function
than for consistency to be attained without exception.

It might help to mention in the manual that the "existing" of `read-buffer'
corresponds more or less to the "must-match" of `completing-read'. It is
generally good to make some connections (cross-refs) between all of these
similar functions, and to point out some of their differences - as we do
with `read-from-minibuffer' and `completing-read'.