On 3/21/18 1:27 PM, Brian Burkhalter wrote:
On Mar 21, 2018, at 1:23 PM, Stuart Marks <stuart.ma...@oracle.com
<mailto:stuart.ma...@oracle.com>> wrote:
Perhaps instead the verbiage just needs to be changed to, e.g.,
“The implementation in this class simply invokes {@link
#write(byte[],int,int) write(b, 0, b.length)}.”
I don't think you want to specify this detail about the implementation.
Consider a possible future refactoring, where writeBytes() calls some
internal method instead of calling write(b, 0, b.length). This might be done,
for example, to leverage an intrinsic, or to avoid unnecessary bounds checks,
or for some other reason we can't imagine at the moment.
Such a refactoring would be prohibited by an @implSpec.
Why then not an @implNote instead of an @apiNote?
The statement that was proposed:
This method is equivalent to write(b, 0, b.length).
is a statement about the semantics of writeBytes(b). Put another way, it states
that the requirements on the behavior of writeBytes(b) are equivalent to those
on write(b, 0, b.length). Those are statements about the API.
I don't think anything needs to be said about implementation.
s'marks
