On Tue, 27 Feb 2024 15:10:37 GMT, Nizar Benalla <d...@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. This pull request has now been integrated. Changeset: 3b8227ba Author: Nizar Benalla <nizar.bena...@oracle.com> Committer: Adam Sotona <asot...@openjdk.org> URL: https://git.openjdk.org/jdk/commit/3b8227ba24c7bc05a8ea23801e3816e8fc80de4e Stats: 2 lines in 1 file changed: 2 ins; 0 del; 0 mod 8326836: Incorrect `@since` tags for ClassSignature methods Reviewed-by: asotona ------------- PR: https://git.openjdk.org/jdk/pull/18030