RFR JDK-8067127: Tags cleanup

[mark.reinhold at oracle.com]

2014/12/10 6:38 -0800, pavel.rappo at oracle.com:
> ...
> 
> The overall goal of the parent task (JDK-8067126) though is to make it even less
> wordy and more readable where possible:
> 
> * <p> The first byte read is stored into {@code b[0]}, the next
> * one into {@code b[1]}, and so on. The number of bytes read is {@code <=
> * b.length}. Let {@code k} be the number of bytes actually read; these
> * bytes will be stored in elements {@code b[0]..b[k-1]}, leaving elements 
> * {@code b[k]..b[b.length-1]} unaffected.

I'm all for brevity, but 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.

You've also changed the meaning of the specification, since b.length
might not be equal to len.

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.

- Mark