On Thu, 29 Feb 2024 09:45:35 GMT, Nizar Benalla <nbena...@openjdk.org> wrote:
> I added `@since` tags for methods/constructors that do not match the `@since` > of the enclosing class. > > The `write` method already existed in `PrintStream` in earlier versions and > instances of it could always call this method, since it extends > `FilterOutputStream` [which has the > method](https://github.com/openjdk/jdk6/blob/3e49aa876353eaa215cde71eb21acc9b7f9872a0/jdk/src/share/classes/java/io/FilterOutputStream.java#L96). > > for `MappedByteBuffer slice()` and `MappedByteBuffer slice(int index, int > length)`, the return type changed from `ByteBuffer ` to `MappedByteBuffer`. > And the checker tool differentiates between them because of that. > > 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: e0bab786 Author: Nizar Benalla <nbena...@openjdk.org> Committer: Jaikiran Pai <j...@openjdk.org> URL: https://git.openjdk.org/jdk/commit/e0bab786402d70e9a74d1816c029c772ea01f697 Stats: 24 lines in 7 files changed: 19 ins; 2 del; 3 mod 8326951: since-checker - missing @ since tags Reviewed-by: jpai ------------- PR: https://git.openjdk.org/jdk/pull/18055
