> ...I don't see how this last version is an > improvement. The phrase "the number of bytes read is <= b.length", in > particular, is jarring since it switches abruptly from prose to symbols; > the original "the number of bytes read is, at most, equal to len" is far > preferable.
Agreed. And yet sometimes javadocs in this area are very wordy: "...If <code>len</code> is not zero..." or "...This value should always be nonnegative and not larger than the value of <code>count</code>..." or "...If the value of the <tt>len</tt> parameter is negative then no characters are written..." etc. > You've also changed the meaning of the specification, since b.length > might not be equal to len. Thanks for pointing this out! My mistake. This example was not reviewed as carefully as the webrev, so yes, it's a mistake. And no, it's not in the webrev. It was taken from the second read that takes byte[] as a sole argument (without offset and length). > The javadoc for JCP-standard API elements is not just documentation, > it's a specification, and so it must be treated with great care. It's > the basis of the conformance tests, and hence a foundation of Java's > overall compatibility story. We must not change its meaning by mistake. Yes, that's why we have code reviews and other processes. In the webrev though there are only markup changes. I believe they are not a part of the spec. -Pavel
