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/