From 40adabe2ef8787daa375eaddfb1e265ef5fb18a3 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 20 Sep 2025 12:32:21 +0300
Subject: [PATCH] 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.
---
 doc/lispref/processes.texi | 12 +++++++++++-
 src/process.c              | 10 ++++++++--
 2 files changed, 19 insertions(+), 3 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,
diff --git a/src/process.c b/src/process.c
index 75416b8e52a..2804409f51e 100644
--- a/src/process.c
+++ b/src/process.c
@@ -4865,7 +4865,7 @@ deactivate_process (Lisp_Object proc)
 DEFUN ("accept-process-output", Faccept_process_output, Saccept_process_output,
        0, 4, 0,
        doc: /* Allow any pending output from subprocesses to be read by Emacs.
-It is given to their filter functions.
+The subprocess output is given to the respective process filter functions.
 Optional argument PROCESS means to return only after output is
 received from PROCESS or PROCESS closes the connection.
 
@@ -4880,7 +4880,13 @@ from PROCESS only, suspending reading output from other processes.
 If JUST-THIS-ONE is an integer, don't run any timers either.
 Return non-nil if we received any output from PROCESS (or, if PROCESS
 is nil, from any process) before the timeout expired or the
-corresponding connection was closed.  */)
+corresponding connection was closed.
+
+Note that it is not guaranteed that this function will return as
+soon as some output is received.  In particular, if PROCESS is nil,
+the function should not be expected to return before the timeout
+expires.  The main purpose of this function is to allow process output
+to be read by Emacs, not to return as soon as any output is read.  */)
   (Lisp_Object process, Lisp_Object seconds, Lisp_Object millisec,
    Lisp_Object just_this_one)
 {