RFR JDK-8067127: Tags cleanup

Pavel Rappo 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
> preferable.

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
are written..."


> 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 mailing list