Argument names in Elisp Reference vs docstrings

Argument names in Elisp Reference vs docstrings

[Juanma Barranquero]

It is consistency between argument names in docstrings vs argument
names in the Emacs Lisp Reference a goal?

For example:

  FUNCTION           EMACS LISP REFERENCE      DOCSTRING
 -----------------  ------------------------  -----------------------
  setplist           symbol plist              symbol newplist
  defcustom          option default doc ...    symbol value doc ...
  defun              name argument-list ...    name arglist ...
  gethash            key table default         key table dflt
  indirect-function  function                  object
  eval-region        start end stream ...      start end printflag ...
  kbd                keyseq-text               keys
  make-frame         alist                     parameters
  split-window       window size horizontal    window size horflag

These were chosen almost at random, I didn't do a search looking for
differences.

-- 
                    /L/e/k/t/u

Re: Argument names in Elisp Reference vs docstrings

[Richard M. Stallman]

    It is consistency between argument names in docstrings vs argument
    names in the Emacs Lisp Reference a goal?

Yes, more or less.  It is not necessary to fix all such discrepancies,
but in many cases fixing them would be a step forward.  When doing so,
it is important to standardize on the better name, not the worse one.

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

      make-frame         alist                     parameters

PARAMETERS is clearer than ALIST.

      indirect-function  function                  object

FUNCTION is clearer than OBJECT.

But sometimes, in a data-access primitive, there is nothing to say
about the object except for its data type, as here:

      setplist           symbol plist              symbol newplist

SYMBOL is a fine name for the symbol used here..

      gethash            key table default         key table dflt

This is a special case, because `default' is a keyword in C,
so it cannot be used as the argument name.  Therefore, the best thing
to do is add an explicit calling pattern at the end of the doc string.

(That method can be used in other cases too, whenever convenient.)

      eval-region        start end stream ...      start end printflag ...

That looks like a discrepancy of substance, not just of name.
So please check the code and see which one is correct.

Re: Argument names in Elisp Reference vs docstrings

[Juri Linkov]

>     It is consistency between argument names in docstrings vs argument
>     names in the Emacs Lisp Reference a goal?
>
> Yes, more or less.  It is not necessary to fix all such discrepancies,
> but in many cases fixing them would be a step forward.  When doing so,
> it is important to standardize on the better name, not the worse one.

While looking recently at minibuffer reading functions, I noticed that
not only argument names in the Emacs Lisp Reference and docstrings of
each function don't match, but even similar arguments have different
names in related functions.  It is misleading when documentation
refers to a similar argument of another function, but it has a
different name.  Below is a list of arguments with similar names
of minibuffer functions collected from docstrings and descriptions
in the Emacs Lisp Reference:

  prompt, prompt-string
  initial, initial-contents, initial-input
  history, hist
  def, defalt, default, default-value, default-filename, default-dirname
  inherit-input-method
  require-match, mustmatch, must-match, existing
  collection, table, alist
  nospace, hide-spaces
  directory, dir

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.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Argument names in Elisp Reference vs docstrings

[Andreas Schwab]

Juri Linkov <juri@jurta.org> writes:

> Since `default' is a keyword in C, `defaults' is a good replacement.

`default' is special cased: you can spell it `defalt' in the C code and
still get `DEFAULT' in the doc string.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Argument names in Elisp Reference vs docstrings

[Richard M. Stallman]

      Below is a list of arguments with similar names
    of minibuffer functions collected from docstrings and descriptions
    in the Emacs Lisp Reference:

      prompt, prompt-string
      initial, initial-contents, initial-input
      history, hist
      def, defalt, default, default-value, default-filename, default-dirname
      inherit-input-method
      require-match, mustmatch, must-match, existing
      collection, table, alist
      nospace, hide-spaces
      directory, dir

It is not necessarily desirable to make them uniform.  That may or may
not be an improvement, depending on the details.  Thus, the changes
you propose may be good in some cases, but not necessarily in each
one.

So I do not want to make these decisions in a blanket fashion.
How about if you pick one of these groups of alternatives,
make the changes to standardize that group, and send the diff here
to be looked at?

      inherit-input-method

THat is not an inconsistency, just long.

      collection, table, alist

I don't like "collection" very much.

      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.

      history, hist

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

      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.

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.

Re: Argument names in Elisp Reference vs docstrings

[Juanma Barranquero]

On 9/16/05, Drew Adams <drew.adams@oracle.com> wrote:

> BTW, must the C parameter (implementation) name be identical to the Lisp
> name?

No. The "usage:" directive in docstrings of C-defined DEFUNs allows
using any name desired for Lisp argument names in the docstring,
irrespective of the implementation names used in C code.

-- 
                    /L/e/k/t/u

Re: Argument names in Elisp Reference vs docstrings

[Juri Linkov]

> Juri Linkov <juri@jurta.org> writes:
>
>> Since `default' is a keyword in C, `defaults' is a good replacement.
>
> `default' is special cased: you can spell it `defalt' in the C code and
> still get `DEFAULT' in the doc string.

Thanks for the hint.  Now I see that make-docfile explicitly converts
`defalt' to `default' in docstrings.  It's strange that no one function
in Emacs uses this trick for the `default'-like arguments.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Argument names in Elisp Reference vs docstrings

[Juri Linkov]

> So I do not want to make these decisions in a blanket fashion.
> How about if you pick one of these groups of alternatives,
> make the changes to standardize that group, and send the diff here
> to be looked at?

I will send diffs for final reviews when most names will be basically
agreed.

>       collection, table, alist
>
> 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'.

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

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

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

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

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Argument names in Elisp Reference vs docstrings

[Juri Linkov]

> I think it hasn't been decided whether to allow more than one default value
> in the upcoming release.

IIUC, Richard decided to allow more than one default value, since this is a
quite trivial change.

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

I think neither "initial-value" nor "default-value" make the semantics
of arguments clearer than "initial" or "default".  To understand the
difference between them, programmers still should consult the documentation.

> "Init" clearly stands for "initial", but the "value" part is
> important - "initial" by itself doesn't mean much (initial what?).

Perhaps simply "init" would be good: it's short, and since it is not
a real word, it doesn't require a noun like "-value".

-- 
Juri Linkov
http://www.jurta.org/emacs/

RE: Argument names in Elisp Reference vs docstrings

[Drew Adams]

    > I think it hasn't been decided whether to allow more than one
    default value
    > in the upcoming release.

    IIUC, Richard decided to allow more than one default value,
    since this is a quite trivial change.

I didn't realize this was already decided. Are these default values accessed
via repeated M-n? Is there any limit (or guideline) on their number?

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

    I think neither "initial-value" nor "default-value" make the semantics
    of arguments clearer than "initial" or "default".  To understand the
    difference between them, programmers still should consult the
    documentation.

"default" is OK, if there is no problem with the C name conflict. "default"
is commonly abused as shorthand for "default value", at least in software.
(People speak of "the default".)

Yes, to understand the difference between an initial value and a default
value, the doc must be consulted, and that is true _regardless_ of the names
we use. That was not my point about "initial", however - I didn't claim that
"initial-value" would make that distinction clear.

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

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

    > "Init" clearly stands for "initial", but the "value" part is
    > important - "initial" by itself doesn't mean much (initial what?).

    Perhaps simply "init" would be good: it's short, and since it is not
    a real word, it doesn't require a noun like "-value".

I don't get your response here. It's not because "initial" is a real word
that it requires a noun - it's because it's just an adjective. I granted
that "init" abbreviates "initial" adequately. The question is, initial what?
The "value" part is important. "init-val" takes only 2 more characters than
"initial", if that's the worry.

Re: Argument names in Elisp Reference vs docstrings

[Juri Linkov]

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

> Is there any limit (or guideline) on their number?

Do you mean a cardinal or ordinal number?

Their amount is limited by the length of the list of default values.

There are no guidelines for their ordinal number in the minibuffer,
like there are no guidelines for the history list.

> 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".  And "initial" is
widely used too.  My goal was not to make such arguments clearer, but
to make argument names of related functions consistent between each other
and between docstrings and manuals.

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

-- 
Juri Linkov
http://www.jurta.org/emacs/

RE: Argument names in Elisp Reference vs docstrings

[Drew Adams]

    > 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 ;-)

Re: Argument names in Elisp Reference vs docstrings

[Richard M. Stallman]

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

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

Re: Argument names in Elisp Reference vs docstrings

[Robert J. Chassell]

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

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: Argument names in Elisp Reference vs docstrings

[Richard M. Stallman]

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

Sorry, you haven't changed my mind about it.  We can use `collection'
if we can't find something better, but it isn't very good.

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

No.  The `-p' convention is for functions (predicates) only.

Re: Argument names in Elisp Reference vs docstrings

[Kim F. Storm]

"Richard M. Stallman" <rms@gnu.org> writes:

>     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)?
>
> No.  The `-p' convention is for functions (predicates) only.

Some code use -flag on boolean vars.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

RE: Argument names in Elisp Reference vs docstrings

[Drew Adams]

        [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
"components")
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.

Re: Argument names in Elisp Reference vs docstrings

[Robert J. Chassell]

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

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

True, but I do not think of it as a set of completion candidates.  (I
think of completion candidates as possible _text_ to save typing, like
the word `typing' which I just got by typing `ty' and M-/
(dabbrev-expand).)  I agree that the word `collection' doesn't tell us
much, but I cannot think of anything better.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc