On Mon, 13 May 2024 20:39:14 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. > > Nizar Benalla has updated the pull request incrementally with one additional > commit since the last revision: > > empty commit and merge Thanks for the thorough review! ------------- PR Comment: https://git.openjdk.org/jdk/pull/18055#issuecomment-2147542776
