<i18n dev> RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Nizar Benalla]

On Thu, 25 Apr 2024 14:29:27 GMT, Nizar Benalla <duke at openjdk.org> wrote:

> Please review this PR that aims to add all the remaining needed `@since` tags in `java.base`, and group them into a single fix.
> This is related to #18934 and my work around the `@since` checker feature.
> Explicit `@since` tags are needed for some overriding methods for the purpose of the checker.
> 
> I will only give the example with the `CompletableFuture` class but here is the before where the methods only appeared in "Methods declared in interface N"
> 
> <img width="1510" alt="Screenshot 2024-05-06 at 00 06 57" src="https://github.com/openjdk/jdk/assets/96922791/1749a355-133b-4a38-bffe-51ac415b2aac">
> 
> 
> 
> and after where the method has it's own javadoc, the main description is added and the `@since` tags are added as intended.
> 
> I don't have an account on `https://cr.openjdk.org/` but I could host the generated docs somewhere if that is needed.
> 
> <img width="1511" alt="Screenshot 2024-05-06 at 00 07 16" src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043">
> 
> <img width="1505" alt="Screenshot 2024-05-06 at 00 08 06" src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b">
> 
> <img width="1050" alt="Screenshot 2024-05-06 at 00 09 03" src="https://github.com/openjdk/jdk/assets/96922791/fdd75a26-0396-4c5e-8f59-a3717b7d7ec8">
> 
> 
> TIA

Recent [offline] discussions have showed that dealing with `@since` in overriding methods is complicated.
The solution is to add an explicit `@since` to **some** overriding methods that do not have any javadoc as the only `@since` we can infer is that of the enclosing class.
The positive part is that these cases are **very rare**, and would help the checker have precise rules and match those of javadoc.

- We will effectively enforce javadoc comment for some method overrides with the checker (we want to match the rules for `javadoc` tool which doesn't have any special handing for `@since` tags in inherited methods), and for that we need to fix some of the existing tags. But turns out it's not too many as we are only checking JDK 9-current.
 
- Regarding `FileInputStream::readNBytes`, the method `int java.io.FileInputStream.readNBytes(byte[],int,int)` was available since `JDK 9`. 
The one I added an `@since 11` is a different method `byte[] java.io.FileInputStream.readNBytes(int)` with different return type and parameters.
 [Link to JDK 9 docs with the method](https://docs.oracle.com/javase%2F9%2Fdocs%2Fapi%2F%2F/java/io/InputStream.html#readNBytes-byte:A-int-int-)

When I said "For overriding methods we don't look into the supertype" I meant my checker tool doesn't do that.
> It seems you have some trouble understanding that overriding methods without explicit documentation are ignored by javadoc

This is still a **Draft** PR, I meant to add the `{@inheritDoc}` or other needed content to the javadoc and cleanup before opening. Should fix the issue you have with this change.

Others can join the discussion if they want, I'll let them know on monday but you might just get the same answer. For now the decision is that the every time an overload like the ones in this Draft PR is added, we would need to add explicit javadoc comment as we can't infer the `@since` from the overriden method.

I will run `make docs-jdk-api` before and after making changes, and compare the directories before opening. Might include the info in the PR body.

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

PR Comment: https://git.openjdk.org/jdk/pull/18954#issuecomment-2078409463
PR Comment: https://git.openjdk.org/jdk/pull/18954#issuecomment-2079003565
PR Comment: https://git.openjdk.org/jdk/pull/18954#issuecomment-2080962799
PR Comment: https://git.openjdk.org/jdk/pull/18954#issuecomment-2084988616