On Mon, 26 Feb 2024 19:35:26 GMT, Lance Andersen <lan...@openjdk.org> wrote:
> This sentence to me seems a bit hard to digest and you basically get the
> point across in the `@deprecated` message
This new text was added after a discussion with Alan (see above) concluded that
the method should specify its behavior when the number exceeds
Integer.MAX_VALUE.
Currently it's not possible for the reader to know if the value is clamped to
Integer.MAX_VALUE or if bits are discareded. We found the simplest way to
specifiy the long standing behavior would be "returns the equivalent of {@code
(int) getBytesRead()}"
As you note, there is a good bit of overlap with the `@deprecated` note. One
way to solve that would be to move the specification part of the sentence into
the deprecation note and just drop this added sentence in the method
specification.
Are we allowed to have normative specification like this inside a deprecation
note, or must this be specified in the outside the `@deprecated` note?
The suggested javadoc would look like this:
/**
* Returns the total number of compressed bytes input so far.
*
* @deprecated This method returns the equivalent of
* {@code (int) getBytesRead()} and therefore cannot return the
* correct value when it is greater than {@link Integer#MAX_VALUE}.
* Use {@link #getBytesRead()} instead.
*
* @return the total number of compressed bytes input so far
*/
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/17919#discussion_r1503292069
