RFR: JDK-8328501 Incorrect @since` tags for java security interfaces [v3]

[Jonathan Gibbons]

On Mon, 25 Mar 2024 22:51:48 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
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update copyright year to 2024

[wangweij](https://github.com/wangweij) commented [3 weeks ago](https://github.com/openjdk/jdk/pull/18373#issuecomment-2007161883)
I'd like to hear opinions from compiler experts.

@wangweij you probably mean javadoc experts, not compiler experts ;-)

The rules are currently quite simple, and can be expressed in effectively two ways.   Ignoring preview API and nested classes for now:

1. `javadoc` is very simple minded when it comes to handling `@since` tags -- 
    *  if a `@since` tag is present in a documentation comment, it will result in a `Since:` entry in the generated documentation.   
    * if there is no `@since` tag in the documentation comment, there will be no `Since:` info in the generated documentation
    
2. Every declaration should have an `@since` tag indicating when it was first introduced -- except for members of a class or interface if the `@since` value would be the same as for the enclosing class or interface.

* There are no special rules for inferring values for overriding methods.
* There are some special rules for Preview API outlines in [JEP 12](https://openjdk.org/jeps/12)
* There is a PR in progress for `javadoc`, such that if a nested class or interface has no `@since` tag of its own, the info from its enclosing class or interface will be used to generate `Since:` info fir the generate API docs for the nested class.

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

PR Comment: https://git.openjdk.org/jdk/pull/18373#issuecomment-2046188650