RFR JDK-8067127: Tags cleanup
pavel.rappo at oracle.com
Wed Dec 10 17:07:54 UTC 2014
> ...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
Agreed. And yet sometimes javadocs in this area are very wordy:
"...If <code>len</code> is not zero..."
"...This value should always be nonnegative and not larger than the value of
"...If the value of the <tt>len</tt> parameter is negative then no characters
> 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.
More information about the core-libs-dev