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, 8 insertions, 2 deletions

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)
 {