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.