It took me a long time to arrive at the fact that it is only possible to know that Emacs has already been idle for SECS seconds when we are executing a callback for a run-with-idle-timer call with a delay arg of SECS seconds. The docstring could state this in more detail.
> I think the part that makes it a bit confusing is
> that we are talking about calling run-with-idle-timer
> with a lower value of SECS from an already executing
> callback for another run-with-idle-timer.
Gee, what could possibly be confusing about that? ;-)
(Especially if we don't say that explicitly.)