Re: wait_reading_process_ouput hangs in certain cases (w/ patches)

[Eli Zaretskii <eliz@gnu.org>]

> Cc: ml_emacs-lists@binary-island.eu, emacs-devel@gnu.org
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Mon, 13 Nov 2017 11:42:50 -0800
> 
> Hmm, well, since I wrote some of that commentary and code, I can state 
> that it was my understanding that the caller should not care about the 
> exact value of wait_reading_process_output's result (only whether it is 
> negative, zero, or positive), and that my understanding of this API has 
> survived until the present day. Partly this was because I did not want 
> to change the type of the result if we should ever increase the buffer 
> size from 4096 to a value that might not fit in 'int'. In other words, 
> the documentation is written the way it's written in order to give the 
> implementation some freedom that could be useful in the future.

Since this is not a library which should not change its API contract,
we don't really need such a freedom.  We can change the meaning of the
return value whenever we want.  So I'd rather we documented the
meaning of the return value.  More importantly, if we sometimes return
the number of bytes and sometimes just 1, we should tell when each one
happens, because this will make it easier for others to use this
function without being privy to its details and history.