The javadocs of some methods in NIO Buffer are missing @since

[Glavo]

I agree that it is a good choice to use -release or set bootclasspath.
However, this is not always realistic.

Using -release means that we will encounter many JPMS problems.
For example, using --add-exports for system modules is not allowed when
using -release.

In addition, sometimes we may want to deliberately bypass the restriction
of -release:
We may use some new APIs of higher Java versions in our code.
As long as we check the Java version at runtime and ensure that the code
path is not executed
when running on a lower version of Java, this is also reasonable.

For setting bootclasspath... Well, although I know it should be like this
in theory, I've never seen anyone set it.
Since I have installed the corresponding version of JDK, why don't I
compile with it directly?

Let's return to this issue. Whether use -release or set bootclasspath, I
think it's just a workaround.
Whether the compiler will check this problem or not, it is our original
task to let users and static analysts
understand this problem from the document.
I think there is no doubt that the lack of @since is an oversight.



On Sat, Dec 31, 2022 at 2:42 AM Joe Darcy <joe.darcy at oracle.com> wrote:

> On 12/30/2022 4:12 AM, Glavo wrote:
> > Java 9 overrides the rewind, flip and other methods of Buffer in
> > subclasses of Buffer such as ByteBuffer.
> > The methods in these subclasses do not add @since 9 to javadoc.
> >
> > I think this is an oversight, because this modification destroys some
> > code.
> > When compiling them with JDK 9+ and using the -target 8 option instead
> > of -release 8,
> > the generated class file crashes when running in Java 8.
>
> Which is exactly why compiling with "javac -source $OLD -target $OLD"
> *without* setting the bootclasspath was not a recommended option and
> started generating a warning as of JDK 7:
>
>
> https://web.archive.org/web/20101225145622/http://blogs.sun.com/darcy/entry/bootclasspath_older_source
>
> >
> > IDEs cannot detect this error because there is no @since document.
> > Therefore, I think it is important to add @since to them, and they
> > need to be back ported to Java 11/17.
>
>
> The solution to a misconfigured build is to configure the build
> properly, which includes using --release $FOO where available.
>
> -Joe
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/core-libs-dev/attachments/20221231/b56c8b27/attachment.htm>