Re: sit-for arg old-nodisp not documented

[Juanma Barranquero <lekktu@gmail.com>]

> `sit-for' has an argument old-nodisp that is not described in the doc
> string.

Not exactly. If you read it again carefully, you'll notice `sit-for'
has two modes of invocation:

  - (modern):  (sit-for SECONDS &optional NODISP)
  - (old): (sit-for SECONDS &optional MILLISECONDS NODISP)

So the function is really defined as

  (sit-for SECONDS &optional NODISP OLD-NODISP)

which is accurate, but does not help argument highlighting
(MILLISECONDS is not highlighted) and does not match the description
(which uses NODISP for the OLD-NODISP argument).

The "correct" thing to do would be to define the function (or at
least, the docstring) as

  (sit-for SECONDS &optional NODISP-OR-MILLISECONDS IGNORED-OR-NODISP)

but that would be ugly.

After the 22.1 release I'll take a deep look at the many docstrings
that still have irregularities which are not easy to resolve. I don't
want to be forced to add "\(fn ...)" sections to more docstrings
(there are already too many, I'd like to remove some), and also don't
want to start changing argument names because of dynamic binding
issues (sometimes is difficult to see whether an argument is used as a
local binding in another function higher in the call stack).

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