Improve documentation of 'accept-process-output'

* doc/lispref/processes.texi (Accepting Output):
* src/process.c (Faccept_process_output): Document better the
meaning of the timeout of 'accept-process-output' a,d the fact
that it doesn't always return as soon as some output is available.
See https://lists.gnu.org/archive/html/emacs-devel/2025-08/msg00750.html
for more details.

1 files changed, 11 insertions, 1 deletions

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 3d3ec7a5a3c..59f6ddeb63b 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -1989,7 +1989,8 @@ until output arrives from a process.
 
 @defun accept-process-output &optional process seconds millisec just-this-one
 This function allows Emacs to read pending output from processes.  The
-output is given to their filter functions.  If @var{process} is
+output is given to the filter functions set up by the processes
+(@pxref{Filter Functions}).  If @var{process} is
 non-@code{nil} then this function does not return until some output
 has been received from @var{process} or @var{process} has closed the
 connection.
@@ -2020,6 +2021,15 @@ got output from @var{process}, or from any process if @var{process} is
 corresponding connection contains buffered data.  The function returns
 @code{nil} if the timeout expired or the connection was closed before output
 arrived.
+
+Note that this function is not guaranteed to return as soon as some
+output is available from a subprocess, because the main purpose of the
+function is to let Emacs read output from subprocesses, not to wait as
+little as possible.  In particular, if @var{process} is @code{nil}, the
+function should not be expected to return before the specified timeout
+expires.  Thus, if a Lisp program needs to minimize the wait for the
+subprocess output, it should call this function with a non-@code{nil}
+value of a specific @var{process}.
 @end defun
 
 If a connection from a process contains buffered data,