On Mon, 25 Mar 2024 22:51:48 GMT, Nizar Benalla <d...@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
>
> Nizar Benalla has updated the pull request incrementally with one additional
> commit since the last revision:
>
> Update copyright year to 2024
The PR title needs attention: missing `
-------------
PR Comment: https://git.openjdk.org/jdk/pull/18373#issuecomment-2046063891
