RFR: JDK-8326836 Incorrect `@since` Tags for ClassSignature methods [v2]

[Adam Sotona]

On Wed, 20 Mar 2024 02:10:35 GMT, Nizar Benalla <duke at openjdk.org> wrote:

>> # Issue
>> - [JDK-8326836](https://bugs.openjdk.org/browse/JDK-8326836): changes were made to the method signatures but this modification isn't reflected in the @ since tags. The @ since tags need to be updated.
>> 
>> I changed the `@since` tags to better accurately show when the methods were introduced. This is similar to #18032 and #18373 
>> 
>> 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.
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   update the copyright year to 2024

Looks good, thanks.

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

Marked as reviewed by asotona (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18030#pullrequestreview-1989118816