[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: Argument names in Elisp Reference vs docstrings

From: Drew Adams
Subject: RE: Argument names in Elisp Reference vs docstrings
Date: Mon, 19 Sep 2005 08:54:01 -0700

        [completions] doesn't quite fit for an alist, an obarray, or a
        hash table, or a function to test them.

    Unfortunately, `collection' does best.  `completions' fails utterly.
    Moreover, is not the focus on the whole group, not on its individual
    elements, members, or items?

    I agree, another word would be better, but `completions' is not it,
    nor are any of the words that direct attention to components.

There are at least two dimensions to consider here:

a. singular (collective) vs plural noun ("the whole group" vs its
b. meaning/use of argument vs its datatype

RMS on (b):

    In general, a name that describes the meaning is clearer than
    a name that describes only the data type

Is (a) more important than (b), in general, or even in this case? To me, (b)
is more important than (a), both in general and in this case. It is more
important to convey that the argument represents or manifests a set of
completions, than it is to worry about whether it names that set in a
singular or plural way.

Regardless of whether the datatype is alist, obarray, hash table, or
function, it represents an ordered set of completion candidates.

It's been said that use of a plural implies or suggests datatype `list'. I
think that's wrong, and is the root of the naming conundrum here. Plural
should simply indicate, well, plural! - that is, a collection.

The word "collection" doesn't tell us anything about what the argument
represents or is used for - it tells us only something (very little, in
fact) about how it is represented: it is some collective entity.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]