A DESCRIPTION OF THE REQUEST :
InputStream#available() is documented as follows:

"Returns an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking or {@code 0} when it reaches the end of the input stream."

This should be changed to one of the following:

(a) "Returns an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking, which may be 0, or 0 when it reaches the end of the input stream."

(b) "Returns an estimate of the number of bytes that can be read (or skipped over) from this input stream without blocking, which will always be greater than 0, or 0 when it reaches the end of the input stream."



JUSTIFICATION :
Unclear documentation creates bugs.

I have been assuming interpretation (a) is correct my entire life, but multiple during code review, another developer has used (b) as part of an argument for why they should be allowed to call it. It seems like this problem would be avoided if the method would explicitly document whether 0 is a possible return value in the first case.