<i18n dev> RFR: 8330954: since-checker - Fix remaining `@since` tags in `java.base` [v4]

[Jonathan Gibbons]

On Mon, 13 May 2024 20:14:38 GMT, Nizar Benalla <nbenalla 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
>
> Nizar Benalla has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 11 additional commits since the last revision:
> 
>  - Merge remote-tracking branch 'upstream/master' into 8330954
>  - (C)
>  - (C)
>  - Move security classes changes to pr18373
>  - remove couple extra lines
>  - Pull request is now only about `@since` tags, might add an other commit
>  - add one more `{inheritDoc}` to `CompletableFuture.state`
>  - add `@throws` declarations to javadoc
>  - add ``{@inheritDoc}`` to new javadoc comments
>  - remove two extra spaces
>  - ... and 1 more: https://git.openjdk.org/jdk/compare/39767aaa...b3574b97

I disagree somewhat with the statements in the comments that the checker should follow the javadoc rules, whatever they are.

The important thing is to decide what the rules for `@since` should be, in terms of changes to the set of signatures in the class.  Generally, I think the rule should be that _every_ declaration should have `@since` _except_ that members need not have the tag if it would be the same as for the enclosing class or interface.  As far as adding an overriding method is concerned, if it has the same VM descriptor as the overridden method, it is not a "new" method in the class;  if it has a covariant return type, that is a significant change to the descriptor and so such methods should have `@since`.

As a practical rule for deciding whether any declaration is new or not, imagine writing a test program that refers to the most specific form of the declaration. If that test program does not compile on JDK version N-1 and does compile on version N, then it warrants having `@since N`.  Put another way, `@since N` should identify the first release in which the declaration can be used in the given form.

Note, these rules are stated without reference to what `javadoc` does.  `javadoc` should follow these rules as well; it is a bug if the tool generates incorrect documentation based on `@since` tags following these rules.

Also, while the proposed new Since Checker should follow these rules when analysing declarations, it may go further when making suggestions to correct errors that it finds. For example, instead of simply saying _No `@since` tag found here_, it might analyze the history and say  _No `@since` tag found here; the declaration was introduced in X_ for an appropriate X.

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

PR Comment: https://git.openjdk.org/jdk/pull/18954#issuecomment-2145605004