RFR JDK-8067127: Tags cleanup

[roger riggs]

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
>