timer.el API (was: undo-auto--undoable-change infloop)

[Stefan Monnier]

> I thought I had a valid use case for calling timer--activate on an
> already active timer.
[...]
> Which uses an internal function, but I thought my timer-activate was
> legitimate to extend the timer.  Maybe I should have approached the
> problem differently?

Sigh!  `timer.el` has no doc at all (other than the docstrings) and
almost all the definitions are named "normally" (only
`cancel-timer-internal` and `internal-timer-start-idle` are somehow
labeled as internal), so it's a mess.

My reading of the `timer.el` code and the way it's used
"out there" leads me to think that `timer-activate` should be
considered internal.

And its effect is very poorly defined in its docstring.  So whichever
behavior we choose for it, I'm sure someone can come up with
a legitimate case where that precise behavior is indeed needed.

Someone™ should probably take a step back, decide what the exposed API
*should* be, rename the rest to use internal names, and then add
obsolete aliases to temporarily preserve backward compatibility.


        Stefan