> For context, I am writing tests to check for accurate use of `@since` tags in
> documentation comments in source code.
> We're following these rules for now:
>
> ### Rule 1: Introduction of New Elements
>
> - If an element is new in JDK N, with no equivalent in JDK N-1, it must
> include `@since N`.
> - Exception: Member elements (fields, methods, nested classes) may omit
> `@since` if their version matches the value specified for the enclosing class
> or interface.
>
> ### Rule 2: Existing Elements in Subsequent JDK Versions
>
> - If an element exists in JDK N, with an equivalent in JDK N-1, it should not
> include `@since N`.
>
> ### Rule 3: Handling Missing `@since` Tags in methods if there is no `@since`
>
> - When inspecting methods, prioritize the `@since` annotation of the
> supertype's overridden method.
> - If unavailable or if the enclosing class's `@since` is newer, use the
> enclosing element's `@since`.
>
> I.e. if A extends B, and we add a method to B in JDK N, and add an override
> of the method to A in JDK M (M > N), we will use N as the effective `@since`
> for the method.
> Here's an illustration using Markdown and Java code:
>
> The override of `getParams` in these interfaces was done in in JDK 22 and an
> `@since 22` was, but this method has been inherited to these interfaces for a
> long time.
>
> As pointed out by my mentor Jan,
>
>
> import javax.crypto.interfaces.DHPublicKey;
>
> public class DhkeyTest {
>
> public static void main(DHPublicKey key) {
> System.err.println(key.getParams());
> }
>
> }
>
>
> this compiles using JDK 8 without any compile-time errors. The @ since tag
> shouldn't be here
>
>
> - the same goes for these other interfaces
>
> java.security.interfaces.DSAPublicKey
> java.security.interfaces.XECPublicKey
> java.security.interfaces.DSAPrivateKey
> java.security.interfaces.ECPrivateKey
> java.security.interfaces.XECPrivateKey
> java.security.interfaces.EdECPrivateKey
> java.security.interfaces.ECPublicKey
> java.security.interfaces.EdECPublicKey
> javax.crypto.interfaces.DHPrivateKey
> javax.crypto.interfaces.DHPublicKey
> java.security.interfaces.RSAPublicKey
> java.security.interfaces.RSAPrivateKey
Nizar Benalla has updated the pull request incrementally with one additional
commit since the last revision:
Update copyright year to 2024
-------------
Changes:
- all: https://git.openjdk.org/jdk/pull/18373/files
- new: https://git.openjdk.org/jdk/pull/18373/files/7ef8b4ee..b04a75e5
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=18373&range=02
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=18373&range=01-02
Stats: 12 lines in 12 files changed: 0 ins; 0 del; 12 mod
Patch: https://git.openjdk.org/jdk/pull/18373.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18373/head:pull/18373
PR: https://git.openjdk.org/jdk/pull/18373
