[Top][All Lists]

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

Re: Argument names in Elisp Reference vs docstrings

From: Juri Linkov
Subject: Re: Argument names in Elisp Reference vs docstrings
Date: Fri, 16 Sep 2005 01:03:02 +0300
User-agent: Gnus/5.110004 (No Gnus v0.4) Emacs/22.0.50 (gnu/linux)

>     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
  require-match, mustmatch, must-match, existing
  collection, table, alist
  nospace, hide-spaces
  directory, dir

I propose to standardize on the following arguments names:


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

reply via email to

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