RFR JDK-8067127: Tags cleanup

[Pavel Rappo]

> ...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