RFR JDK-8067127: Tags cleanup

mark.reinhold at oracle.com mark.reinhold at oracle.com
Wed Dec 10 16:16:02 UTC 2014

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

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

More information about the core-libs-dev mailing list