Hi Brian,
The use of the word 'equivalent' regardless of the context, only says
the behavior is the same
it does not mandate the implementation except that it behaves the same.
Since the behavior of the method is already specified, adding the
'equivalent' statement
only makes it easier for the developer to understand the behavior so it
would be
fine in an apiNote or just part of the description. Either way, from a
conformance point of
view, the statement should be ignored.
If it was in an @implSpec clause, then I'd expect to be able to write a
test that
checks that the behavior is the same using only the API and not making
any assumption
about that the API invokes.
$.02, Roger
On 3/21/2018 5:23 PM, Brian Burkhalter wrote:
On Mar 21, 2018, at 2:21 PM, Stuart Marks <stuart.ma...@oracle.com> wrote:
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.
I can see what you are saying now. It would be good to have comments from
someone else as well.
Thanks,
Brian
