Integrated: 8328501: Incorrect `@since` tags for java security interfaces

[Nizar Benalla]

On Tue, 19 Mar 2024 11:15:56 GMT, Nizar Benalla <duke at openjdk.org> wrote:

> 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.
> 
> 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

This pull request has now been integrated.

Changeset: ae60d845
Author:    Nizar Benalla <nizar.benalla at oracle.com>
Committer: Weijun Wang <weijun at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/ae60d845007c7137895e3a5f86623d0731fee81f
Stats:     24 lines in 12 files changed: 0 ins; 10 del; 14 mod

8328501: Incorrect `@since` tags for java security interfaces

Reviewed-by: mullan

-------------

PR: https://git.openjdk.org/jdk/pull/18373