bug#37875: 27.0.50; `run-with-timer' not documented in (elisp)Timers

[Phil Sainty <psainty@orcon.net.nz>]

On 30/10/19 12:20 AM, Lars Ingebrigtsen wrote:
> Not really -- I wondered why there were two functions (run-with-timer
> and run-at-time) that are identical.
> 
> It could be made into a defalias at least -- the run-at-time doc string
> is much better than the run-with-timer one.

I think the point is this:

(run-with-idle-timer SECS REPEAT FUNCTION &rest ARGS)
(run-with-timer      SECS REPEAT FUNCTION &rest ARGS)
(run-at-time         TIME REPEAT FUNCTION &rest ARGS)

`run-with-timer' is the non-idle analog of `run-with-idle-timer',
with a documented expectation that one passes it a number of
seconds as its first argument SECS, being the timeout to use.

So if I see either `run-with-timer' or `run-with-idle-timer' then
I know I'm looking at a timeout argument in seconds.

`run-with-time' has a different argument, TIME, which *may* be a
number of seconds (and therefore `run-with-timer' can be defined
in terms of this); but ostensibly it's a more general function.

I'd argue for keeping them both.  If anything, I'd be inclined to
add validation to `run-with-timer' to check that an integer was
passed.


-Phil