Hi Pavel,
I'd stick to just fixing the html formatting; leave the language alone.
If the wording is changed even slightly, it makes the review more difficult
and usually does not make a significant improvement.
BTW, some of the JCK test tools are keyed off the exact wording (think
checksum)
and changing the wording means a manual review of the tests in question.
It might also trigger the need for a CCC.
Roger
On 12/10/2014 12:07 PM, Pavel Rappo wrote:
...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
