RFR: JDK-8326836 Incorrect @since Tags for ClassSignature methods

[Chen Liang]

On Tue, 27 Feb 2024 15:10:37 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.

Good spotting! I didn't think this was necessary as FFM API had similar new method additions before, yet they didn't add `@since` tags in existing files :(

First, the `ClassSig superclassSignature()` method has replaced the old one returning `TypeSig`, thus it's a new method (different descriptors, breaking binary compatibility, somewhat source compatible) and should get a `@since` tag.

Also, what's the definition of a signature? Do we introduce a new `@since` tag if the generic signature differs, i.e. `List<RefTypeSig>` vs `List<ClassTypeSig>`?

If we do introduce a `@since` tag for a generic signature change (but no change in bytecode descriptor), we should add a `@since` tag to `List<Signature.ClassTypeSig> superinterfaceSignatures()`, as its generic signature has changed.

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

PR Comment: https://git.openjdk.org/jdk/pull/18030#issuecomment-1968058662