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.
_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel
