Introduction tests for `@since` Tags in OpenJDK

[Nizar Benalla]

Hello JDK folk,

This is a follow-up to my previous email[1] regarding `@since` tests.

These tests look at the ​`@since`​ tag in the documentation comment, compare it to the release in which the element first appeared, and report an error if the values don't match.

The releases used to determine the expected value of ​`@since`​ are taken from the historical data built into javac. We process JDK 9-current (classfiles only) and build a map with a unique ID for each element and the versions in which it appeared. We then compare the values in the map to the ones in the source code.

The spec for `@since` has been updated[2]

There is an option to pass an exclude list, which can be used to work around any temporary issues that may occur.

[1]: https://mail.openjdk.org/pipermail/jdk-dev/2024-June/009160.html
[2]: https://download.java.net/java/early_access/jdk24/docs/specs/javadoc/doc-comment-spec.html#since
________________________________
From: Nizar Benalla
Sent: Wednesday, June 26, 2024 9:42 AM
To: jdk-dev at openjdk.org <jdk-dev at openjdk.org>
Subject: Introduction tests for `@since` Tags in OpenJDK

Hello OpenJDK Developers,

This note is to inform you about a new effort regarding `@since` tags in our codebase. Starting now, their values will be tested by a collection of Tier 3 tests.

Tests:
- A test will be implemented for each module.
- To run all tests before a push, use:
  ```
  make test TEST=jdk_since_checks
  ```
- To run a test for a specific module using jtreg, you can provide a directory path. For example, for the `java.base` module:
  ```
  jtreg [OPTIONS] test/jdk/tools/sincechecker/modules/java_base/CheckSince_javaBase.java
  ```

2. Performance:
- Running the test for the `java.base` module only takes 20 seconds.
- Running the test for other modules can take 10 seconds.
- Running all of the tests can take up to 5 minutes.

Context:
The `@since` information is now of increased importance due to its role in the "new API in JDK$N" pages. The accuracy of this data is crucial for developers to track new features and changes.  As a rule, every declaration should have an @since tag, except for members where it would be the same as for the enclosing class or interface. The rules for determining @since tags are detailed in this [CSR][2].

Additional Information:
- Scope: The tests currently focus on code from JDK 9 onwards.
- Preview Features: Handling of preview elements is as described in [JEP 12][3].
- Covariant Overrides: These are treated as new methods, requiring a new `@since` tag.

We will be making a few fixes to add missing @since tags in the documentation. After these fixes, this process should prevent such mistakes from happening in the future.

Thank you,
Nizar

[1]: https://docs.oracle.com/en/java/javase/22/docs/api/new-list.html
[2]: https://bugs.openjdk.org/browse/JDK-8334325
[3]: https://openjdk.org/jeps/12
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jdk-dev/attachments/20241014/8c09b033/attachment-0001.htm>