sleep-for documentation and how to pause reliably

[Eli Zaretskii]

Am I missing something, or is our current docs of sleep-for misleading?

The doc string says:

  (sleep-for SECONDS &optional MILLISECONDS)

  Pause, without updating display, for SECONDS seconds.

The only way I can interpret this is that sleep-for _always_ pauses
for that number of seconds.

The ELisp manual goes even further:

   -- Function: sleep-for seconds &optional millisec
       This function simply pauses for SECONDS seconds without updating
       the display.  It pays no attention to available input.  It returns
       `nil'.        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

       [...]

       Use `sleep-for' when you wish to guarantee a delay.
                                        ^^^^^^^^^^^^^^^^^

"Guarantee a delay".  No "buts".

However, in fact, sleep-for will return as soon as any input from any
subprocess arrives.  E.g., try this in *scratch*:

  (progn (setq proc (start-process-shell-command "ls" nil "ls"))
         (sleep-for 20)
         (message "hi"))

You will see no delay at all before the message is displayed.

Am I missing something?  If not, apart of fixing the docs, _is_ there
any way to wait reliably when async subprocesses are running and
producing output?