Integrated: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation

[Nizar Benalla]

On Fri, 19 Jul 2024 11:11:38 GMT, Nizar Benalla  wrote:

> Can I get a review for this change that fixes some broken links in javadoc 
> comments? The new docs are hosted 
> [here](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336039-warnings-links/).
> 
> It's mostly fixing some relative links.
> If using `{@docroot}` isn't ideal I can change it.
> 
> Here is the result of running `diff -r docs-master docs` on the docs from 
> master vs and after these changes 
> 
> 
> diff -r 
> docs-master/api/java.base/java/lang/classfile/components/CodeStackTracker.html
>  docs/api/java.base/java/lang/classfile/components/CodeStackTracker.html
> 106c106
> <  
> ---
>>  
> diff -r docs-master/api/java.base/java/lang/classfile/package-summary.html 
> docs/api/java.base/java/lang/classfile/package-summary.html
> 99c99
> <  
> ---
>> 
> 106c106
> <  
> ---
>> 
> 618c618
> <  
> ---
>> 
> 755c755
> <  
> ---
>> 
> 783c783
> < 
> ---
>> 
> diff -r docs-master/api/java.base/java/lang/foreign/Arena.html 
> docs/api/java.base/java/lang/foreign/Arena.html
> 142c142
> <  the segments allocated by it) becomes  href="../../../java/lang/ref/package.html#reachability">unreachable,
> ---
>>  the segments allocated by it) becomes > href="../../../java/lang/ref/package-summary.html#reachability">unreachable,
> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.Scope.html 
> docs/api/java.base/java/lang/foreign/MemorySegment.Scope.html
> 120c120
> <  as long as it is  href="../../../java/lang/ref/package.html#reachability">reachable.
> ---
>>  as long as it is > href="../../../java/lang/ref/package-summary.html#reachability">reachable.
> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.html 
> docs/api/java.base/java/lang/foreign/MemorySegment.html
> 1420c1420
> <   kept  href="../../../java/lang/ref/package.html#reachability">reachable
> ---
>>   kept > href="../../../java/lang/ref/package-summary.html#reachability">reachable
> 1833c1833
> <href="../../../java/lang/ref/package.html#reachability">unreachable.
> ---
>>   > href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
> 1899c1899
> <href="../../../java/lang/ref/package.html#reachability">unreachable.
> ---
>>   > href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
> diff -r docs-master/api/java.base/java/lang/foreign/SymbolLookup.html 
> docs/api/java.base/java/lang/foreign/SymbolLookup.html
> 395c395
> <   href="../../../java/lang/ref/package.html#reachability">unreachable. The
> ---
>>  https://git.openjdk.org/jdk/commit/92de2b2d5f21af38380b437af51e49c7ac142258
Stats: 20 lines in 8 files changed: 0 ins; 1 del; 19 mod

8336039: Doccheck: HTML warnings, broken links and missing files in java.base 
documentation

Reviewed-by: liach, djelinski

-

PR: https://git.openjdk.org/jdk/pull/20251

Re: RFR: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation [v5]

[Nizar Benalla]

On Sun, 21 Jul 2024 21:15:03 GMT, Nizar Benalla  wrote:

>> Can I get a review for this change that fixes some broken links in javadoc 
>> comments? The new docs are hosted 
>> [here](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336039-warnings-links/).
>> 
>> It's mostly fixing some relative links.
>> If using `{@docroot}` isn't ideal I can change it.
>> 
>> Here is the result of running `diff -r docs-master docs` on the docs from 
>> master vs and after these changes 
>> 
>> 
>> diff -r 
>> docs-master/api/java.base/java/lang/classfile/components/CodeStackTracker.html
>>  docs/api/java.base/java/lang/classfile/components/CodeStackTracker.html
>> 106c106
>> <  
>> ---
>>>  
>> diff -r docs-master/api/java.base/java/lang/classfile/package-summary.html 
>> docs/api/java.base/java/lang/classfile/package-summary.html
>> 99c99
>> <  
>> ---
>>> 
>> 106c106
>> <  
>> ---
>>> 
>> 618c618
>> <  
>> ---
>>> 
>> 755c755
>> <  
>> ---
>>> 
>> 783c783
>> < 
>> ---
>>> 
>> diff -r docs-master/api/java.base/java/lang/foreign/Arena.html 
>> docs/api/java.base/java/lang/foreign/Arena.html
>> 142c142
>> <  the segments allocated by it) becomes > href="../../../java/lang/ref/package.html#reachability">unreachable,
>> ---
>>>  the segments allocated by it) becomes >> href="../../../java/lang/ref/package-summary.html#reachability">unreachable,
>> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.Scope.html 
>> docs/api/java.base/java/lang/foreign/MemorySegment.Scope.html
>> 120c120
>> <  as long as it is > href="../../../java/lang/ref/package.html#reachability">reachable.
>> ---
>>>  as long as it is >> href="../../../java/lang/ref/package-summary.html#reachability">reachable.
>> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.html 
>> docs/api/java.base/java/lang/foreign/MemorySegment.html
>> 1420c1420
>> <   kept > href="../../../java/lang/ref/package.html#reachability">reachable
>> ---
>>>   kept >> href="../../../java/lang/ref/package-summary.html#reachability">reachable
>> 1833c1833
>> <   > href="../../../java/lang/ref/package.html#reachability">unreachable.
>> ---
>>>   >> href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
>> 1899c1899
>> <   > href="../../../java/lang/ref/package.html#reachability">unreachable.
>> ---
>>>   >> href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
>> diff -r docs-master/api/java.base/java/lang/foreign/SymbolLookup.html 
>> docs/api/java.base/java/lang/foreign/SymbolLookup.html
>> 395c395
>> ...
>
> Nizar Benalla has updated the pull request incrementally with one additional 
> commit since the last revision:
> 
>   undo changes to StructuredTaskScope

thank you for the reviews, again.

-

PR Comment: https://git.openjdk.org/jdk/pull/20251#issuecomment-2242906326

Re: RFR: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation [v4]

[Nizar Benalla]

On Sat, 20 Jul 2024 15:10:10 GMT, Alan Bateman  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional 
>> commit since the last revision:
>> 
>>   Update src/java.base/share/classes/java/lang/foreign/MemorySegment.java
>>   
>>   forgot this one
>>   
>>   Co-authored-by: Chen Liang 
>
> src/java.base/share/classes/java/util/concurrent/StructuredTaskScope.java 
> line 1200:
> 
>> 1198:  *  Construction captures the current thread's {@linkplain 
>> ScopedValue scoped
>> 1199:  * value} bindings for inheritance by threads started in the 
>> task scope. The
>> 1200:  * {@linkplain StructuredTaskScope##TreeStructure Tree 
>> Structure} section in the class description
> 
> You can drop the changes to STS if you want as we have an update coming that 
> replaces these paragraphs/links.

Done, thanks for the heads up!

-

PR Review Comment: https://git.openjdk.org/jdk/pull/20251#discussion_r1685812825

Re: RFR: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation [v5]

[Nizar Benalla]

> Can I get a review for this change that fixes some broken links in javadoc 
> comments? The new docs are hosted 
> [here](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336039-warnings-links/).
> 
> It's mostly fixing some relative links.
> If using `{@docroot}` isn't ideal I can change it.
> 
> Here is the result of running `diff -r docs-master docs` on the docs from 
> master vs and after these changes 
> 
> 
> diff -r 
> docs-master/api/java.base/java/lang/classfile/components/CodeStackTracker.html
>  docs/api/java.base/java/lang/classfile/components/CodeStackTracker.html
> 106c106
> <  
> ---
>>  
> diff -r docs-master/api/java.base/java/lang/classfile/package-summary.html 
> docs/api/java.base/java/lang/classfile/package-summary.html
> 99c99
> <  
> ---
>> 
> 106c106
> <  
> ---
>> 
> 618c618
> <  
> ---
>> 
> 755c755
> <  
> ---
>> 
> 783c783
> < 
> ---
>> 
> diff -r docs-master/api/java.base/java/lang/foreign/Arena.html 
> docs/api/java.base/java/lang/foreign/Arena.html
> 142c142
> <  the segments allocated by it) becomes  href="../../../java/lang/ref/package.html#reachability">unreachable,
> ---
>>  the segments allocated by it) becomes > href="../../../java/lang/ref/package-summary.html#reachability">unreachable,
> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.Scope.html 
> docs/api/java.base/java/lang/foreign/MemorySegment.Scope.html
> 120c120
> <  as long as it is  href="../../../java/lang/ref/package.html#reachability">reachable.
> ---
>>  as long as it is > href="../../../java/lang/ref/package-summary.html#reachability">reachable.
> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.html 
> docs/api/java.base/java/lang/foreign/MemorySegment.html
> 1420c1420
> <   kept  href="../../../java/lang/ref/package.html#reachability">reachable
> ---
>>   kept > href="../../../java/lang/ref/package-summary.html#reachability">reachable
> 1833c1833
> unreachable.
> ---
>>   > href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
> 1899c1899
> unreachable.
> ---
>>   > href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
> diff -r docs-master/api/java.base/java/lang/foreign/SymbolLookup.html 
> docs/api/java.base/java/lang/foreign/SymbolLookup.html
> 395c395
> <   href="../../../java/lang/ref/package.html#reachability">unreachable. The
> ---
>>  https://git.openjdk.org/jdk/pull/20251/files
  - new: https://git.openjdk.org/jdk/pull/20251/files/d8aeca9e..4d5d8784

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=20251=04
 - incr: https://webrevs.openjdk.org/?repo=jdk=20251=03-04

  Stats: 3 lines in 1 file changed: 0 ins; 0 del; 3 mod
  Patch: https://git.openjdk.org/jdk/pull/20251.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/20251/head:pull/20251

PR: https://git.openjdk.org/jdk/pull/20251

Re: RFR: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation [v4]

[Nizar Benalla]

> Can I get a review for this change that fixes some broken links in javadoc 
> comments? The new docs are hosted 
> [here](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336039-warnings-links/).
> 
> It's mostly fixing some relative links.
> If using `{@docroot}` isn't ideal I can change it.
> 
> Here is the result of running `diff -r docs-master docs` on the docs from 
> master vs and after these changes 
> 
> 
> diff -r 
> docs-master/api/java.base/java/lang/classfile/components/CodeStackTracker.html
>  docs/api/java.base/java/lang/classfile/components/CodeStackTracker.html
> 106c106
> <  
> ---
>>  
> diff -r docs-master/api/java.base/java/lang/classfile/package-summary.html 
> docs/api/java.base/java/lang/classfile/package-summary.html
> 99c99
> <  
> ---
>> 
> 106c106
> <  
> ---
>> 
> 618c618
> <  
> ---
>> 
> 755c755
> <  
> ---
>> 
> 783c783
> < 
> ---
>> 
> diff -r docs-master/api/java.base/java/lang/foreign/Arena.html 
> docs/api/java.base/java/lang/foreign/Arena.html
> 142c142
> <  the segments allocated by it) becomes  href="../../../java/lang/ref/package.html#reachability">unreachable,
> ---
>>  the segments allocated by it) becomes > href="../../../java/lang/ref/package-summary.html#reachability">unreachable,
> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.Scope.html 
> docs/api/java.base/java/lang/foreign/MemorySegment.Scope.html
> 120c120
> <  as long as it is  href="../../../java/lang/ref/package.html#reachability">reachable.
> ---
>>  as long as it is > href="../../../java/lang/ref/package-summary.html#reachability">reachable.
> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.html 
> docs/api/java.base/java/lang/foreign/MemorySegment.html
> 1420c1420
> <   kept  href="../../../java/lang/ref/package.html#reachability">reachable
> ---
>>   kept > href="../../../java/lang/ref/package-summary.html#reachability">reachable
> 1833c1833
> unreachable.
> ---
>>   > href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
> 1899c1899
> unreachable.
> ---
>>   > href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
> diff -r docs-master/api/java.base/java/lang/foreign/SymbolLookup.html 
> docs/api/java.base/java/lang/foreign/SymbolLookup.html
> 395c395
> <   href="../../../java/lang/ref/package.html#reachability">unreachable. The
> ---
>>  https://git.openjdk.org/jdk/pull/20251/files
  - new: https://git.openjdk.org/jdk/pull/20251/files/c4e46f91..d8aeca9e

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=20251=03
 - incr: https://webrevs.openjdk.org/?repo=jdk=20251=02-03

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/20251.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/20251/head:pull/20251

PR: https://git.openjdk.org/jdk/pull/20251

Re: RFR: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation [v3]

[Nizar Benalla]

> Can I get a review for this change that fixes some broken links in javadoc 
> comments? The new docs are hosted 
> [here](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336039-warnings-links/).
> 
> It's mostly fixing some relative links.
> If using `{@docroot}` isn't ideal I can change it.
> 
> Here is the result of running `diff -r docs-master docs` on the docs from 
> master vs and after these changes 
> 
> 
> diff -r 
> docs-master/api/java.base/java/lang/classfile/components/CodeStackTracker.html
>  docs/api/java.base/java/lang/classfile/components/CodeStackTracker.html
> 106c106
> <  
> ---
>>  
> diff -r docs-master/api/java.base/java/lang/classfile/package-summary.html 
> docs/api/java.base/java/lang/classfile/package-summary.html
> 99c99
> <  
> ---
>> 
> 106c106
> <  
> ---
>> 
> 618c618
> <  
> ---
>> 
> 755c755
> <  
> ---
>> 
> 783c783
> < 
> ---
>> 
> diff -r docs-master/api/java.base/java/lang/foreign/Arena.html 
> docs/api/java.base/java/lang/foreign/Arena.html
> 142c142
> <  the segments allocated by it) becomes  href="../../../java/lang/ref/package.html#reachability">unreachable,
> ---
>>  the segments allocated by it) becomes > href="../../../java/lang/ref/package-summary.html#reachability">unreachable,
> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.Scope.html 
> docs/api/java.base/java/lang/foreign/MemorySegment.Scope.html
> 120c120
> <  as long as it is  href="../../../java/lang/ref/package.html#reachability">reachable.
> ---
>>  as long as it is > href="../../../java/lang/ref/package-summary.html#reachability">reachable.
> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.html 
> docs/api/java.base/java/lang/foreign/MemorySegment.html
> 1420c1420
> <   kept  href="../../../java/lang/ref/package.html#reachability">reachable
> ---
>>   kept > href="../../../java/lang/ref/package-summary.html#reachability">reachable
> 1833c1833
> unreachable.
> ---
>>   > href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
> 1899c1899
> unreachable.
> ---
>>   > href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
> diff -r docs-master/api/java.base/java/lang/foreign/SymbolLookup.html 
> docs/api/java.base/java/lang/foreign/SymbolLookup.html
> 395c395
> <   href="../../../java/lang/ref/package.html#reachability">unreachable. The
> ---
>>  https://git.openjdk.org/jdk/pull/20251/files
  - new: https://git.openjdk.org/jdk/pull/20251/files/31649c74..c4e46f91

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=20251=02
 - incr: https://webrevs.openjdk.org/?repo=jdk=20251=01-02

  Stats: 9 lines in 6 files changed: 0 ins; 0 del; 9 mod
  Patch: https://git.openjdk.org/jdk/pull/20251.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/20251/head:pull/20251

PR: https://git.openjdk.org/jdk/pull/20251

Re: RFR: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation [v2]

[Nizar Benalla]

On Fri, 19 Jul 2024 13:08:06 GMT, Nizar Benalla  wrote:

>> Can I get a review for this change that fixes some broken links in javadoc 
>> comments? The new docs are hosted 
>> [here](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336039-warnings-links/).
>> 
>> It's mostly fixing some relative links.
>> If using `{@docroot}` isn't ideal I can change it.
>> 
>> Here is the result of running `diff -r docs-master docs` on the docs from 
>> master vs and after these changes 
>> 
>> 
>> diff -r 
>> docs-master/api/java.base/java/lang/classfile/components/CodeStackTracker.html
>>  docs/api/java.base/java/lang/classfile/components/CodeStackTracker.html
>> 106c106
>> <  
>> ---
>>>  
>> diff -r docs-master/api/java.base/java/lang/classfile/package-summary.html 
>> docs/api/java.base/java/lang/classfile/package-summary.html
>> 99c99
>> <  
>> ---
>>> 
>> 106c106
>> <  
>> ---
>>> 
>> 618c618
>> <  
>> ---
>>> 
>> 755c755
>> <  
>> ---
>>> 
>> 783c783
>> < 
>> ---
>>> 
>> diff -r docs-master/api/java.base/java/lang/foreign/Arena.html 
>> docs/api/java.base/java/lang/foreign/Arena.html
>> 142c142
>> <  the segments allocated by it) becomes > href="../../../java/lang/ref/package.html#reachability">unreachable,
>> ---
>>>  the segments allocated by it) becomes >> href="../../../java/lang/ref/package-summary.html#reachability">unreachable,
>> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.Scope.html 
>> docs/api/java.base/java/lang/foreign/MemorySegment.Scope.html
>> 120c120
>> <  as long as it is > href="../../../java/lang/ref/package.html#reachability">reachable.
>> ---
>>>  as long as it is >> href="../../../java/lang/ref/package-summary.html#reachability">reachable.
>> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.html 
>> docs/api/java.base/java/lang/foreign/MemorySegment.html
>> 1420c1420
>> <   kept > href="../../../java/lang/ref/package.html#reachability">reachable
>> ---
>>>   kept >> href="../../../java/lang/ref/package-summary.html#reachability">reachable
>> 1833c1833
>> <   > href="../../../java/lang/ref/package.html#reachability">unreachable.
>> ---
>>>   >> href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
>> 1899c1899
>> <   > href="../../../java/lang/ref/package.html#reachability">unreachable.
>> ---
>>>   >> href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
>> diff -r docs-master/api/java.base/java/lang/foreign/SymbolLookup.html 
>> docs/api/java.base/java/lang/foreign/SymbolLookup.html
>> 395c395
>> ...
>
> Nizar Benalla has updated the pull request incrementally with one additional 
> commit since the last revision:
> 
>   remove docroot based on review

I replaced usages of `href` with `@linkplain` and removed unnecessary `` tags

-

PR Comment: https://git.openjdk.org/jdk/pull/20251#issuecomment-2239258426

Re: RFR: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation [v2]

[Nizar Benalla]

On Fri, 19 Jul 2024 12:44:47 GMT, Daniel Jeliński  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional 
>> commit since the last revision:
>> 
>>   remove docroot based on review
>
> src/java.base/share/classes/java/util/concurrent/StructuredTaskScope.java 
> line 1013:
> 
>> 1011:  *  Construction captures the current thread's {@linkplain 
>> ScopedValue scoped
>> 1012:  * value} bindings for inheritance by threads started in the 
>> task scope. The
>> 1013:  * > href="{@docRoot}/java.base/java/util/concurrent/StructuredTaskScope.html#TreeStructure">Tree
>>  Structure section in the class description
> 
> (untested, but should work)
> Suggestion:
> 
>  * {@linkplain StructuredTaskScope##TreeStructure Tree Structure} 
> section in the class description

Fixed in 
[31649c7](https://github.com/openjdk/jdk/pull/20251/commits/31649c743e709cd67bd132774636e3484939890c),
 thanks.

> src/java.base/share/classes/javax/security/auth/Subject.java line 111:
> 
>> 109:  * input type and exceptions thrown are slightly different.
>> 110:  *
>> 111:  * These methods behave differently depending 
>> on
> 
> Suggestion:
> 
>  * These methods behave differently depending on
> 
> We seem to mix ` fine, and the `https://git.openjdk.org/jdk/pull/20251#discussion_r1684348983
PR Review Comment: https://git.openjdk.org/jdk/pull/20251#discussion_r1684349446

Re: RFR: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation [v2]

[Nizar Benalla]

> Can I get a review for this change that fixes some broken links in javadoc 
> comments? The new docs are hosted 
> [here](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336039-warnings-links/).
> 
> It's mostly fixing some relative links.
> If using `{@docroot}` isn't ideal I can change it.
> 
> Here is the result of running `diff -r docs-master docs` on the docs from 
> master vs and after these changes 
> 
> 
> diff -r 
> docs-master/api/java.base/java/lang/classfile/components/CodeStackTracker.html
>  docs/api/java.base/java/lang/classfile/components/CodeStackTracker.html
> 106c106
> <  
> ---
>>  
> diff -r docs-master/api/java.base/java/lang/classfile/package-summary.html 
> docs/api/java.base/java/lang/classfile/package-summary.html
> 99c99
> <  
> ---
>> 
> 106c106
> <  
> ---
>> 
> 618c618
> <  
> ---
>> 
> 755c755
> <  
> ---
>> 
> 783c783
> < 
> ---
>> 
> diff -r docs-master/api/java.base/java/lang/foreign/Arena.html 
> docs/api/java.base/java/lang/foreign/Arena.html
> 142c142
> <  the segments allocated by it) becomes  href="../../../java/lang/ref/package.html#reachability">unreachable,
> ---
>>  the segments allocated by it) becomes > href="../../../java/lang/ref/package-summary.html#reachability">unreachable,
> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.Scope.html 
> docs/api/java.base/java/lang/foreign/MemorySegment.Scope.html
> 120c120
> <  as long as it is  href="../../../java/lang/ref/package.html#reachability">reachable.
> ---
>>  as long as it is > href="../../../java/lang/ref/package-summary.html#reachability">reachable.
> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.html 
> docs/api/java.base/java/lang/foreign/MemorySegment.html
> 1420c1420
> <   kept  href="../../../java/lang/ref/package.html#reachability">reachable
> ---
>>   kept > href="../../../java/lang/ref/package-summary.html#reachability">reachable
> 1833c1833
> unreachable.
> ---
>>   > href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
> 1899c1899
> unreachable.
> ---
>>   > href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
> diff -r docs-master/api/java.base/java/lang/foreign/SymbolLookup.html 
> docs/api/java.base/java/lang/foreign/SymbolLookup.html
> 395c395
> <   href="../../../java/lang/ref/package.html#reachability">unreachable. The
> ---
>>  https://git.openjdk.org/jdk/pull/20251/files
  - new: https://git.openjdk.org/jdk/pull/20251/files/ddcdbc72..31649c74

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=20251=01
 - incr: https://webrevs.openjdk.org/?repo=jdk=20251=00-01

  Stats: 4 lines in 2 files changed: 0 ins; 0 del; 4 mod
  Patch: https://git.openjdk.org/jdk/pull/20251.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/20251/head:pull/20251

PR: https://git.openjdk.org/jdk/pull/20251

RFR: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation

[Nizar Benalla]

Can I get a review for this change that fixes some broken links in javadoc 
comments? The new docs are hosted 
[here](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336039-warnings-links/).

It's mostly fixing some relative links.
If using `{@docroot}` isn't ideal I can change it.

Here is the result of running `diff -r docs-master docs` on the docs from 
master vs and after these changes 


diff -r 
docs-master/api/java.base/java/lang/classfile/components/CodeStackTracker.html 
docs/api/java.base/java/lang/classfile/components/CodeStackTracker.html
106c106
<  
---
>  
diff -r docs-master/api/java.base/java/lang/classfile/package-summary.html 
docs/api/java.base/java/lang/classfile/package-summary.html
99c99
<  
---
> 
106c106
<  
---
> 
618c618
<  
---
> 
755c755
<  
---
> 
783c783
< 
---
> 
diff -r docs-master/api/java.base/java/lang/foreign/Arena.html 
docs/api/java.base/java/lang/foreign/Arena.html
142c142
<  the segments allocated by it) becomes unreachable,
---
>  the segments allocated by it) becomes  href="../../../java/lang/ref/package-summary.html#reachability">unreachable,
diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.Scope.html 
docs/api/java.base/java/lang/foreign/MemorySegment.Scope.html
120c120
<  as long as it is reachable.
---
>  as long as it is  href="../../../java/lang/ref/package-summary.html#reachability">reachable.
diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.html 
docs/api/java.base/java/lang/foreign/MemorySegment.html
1420c1420
<   kept reachable
---
>   kept  href="../../../java/lang/ref/package-summary.html#reachability">reachable
1833c1833
<   unreachable.
---
>href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
1899c1899
<   unreachable.
---
>href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
diff -r docs-master/api/java.base/java/lang/foreign/SymbolLookup.html 
docs/api/java.base/java/lang/foreign/SymbolLookup.html
395c395
<  unreachable. 
The
---
>   href="../../../java/lang/ref/package-summary.html#reachability">unreachable.
>  The
diff -r 
docs-master/api/java.base/java/net/spi/InetAddressResolver.LookupPolicy.html 
docs/api/java.base/java/net/spi/InetAddressResolver.LookupPolicy.html
117c117
<  System Properties which 
affect
---
>  System Properties 
> which affect
diff -r docs-master/api/java.base/java/text/MessageFormat.html 
docs/api/java.base/java/text/MessageFormat.html
433,434c433
< 
<  
---
>  
diff -r 
docs-master/api/java.base/java/util/concurrent/StructuredTaskScope.ShutdownOnFailure.html
 
docs/api/java.base/java/util/concurrent/StructuredTaskScope.ShutdownOnFailure.html
245c245
<  Tree Structure section in the class description
---
>   href="../../../../java.base/java/util/concurrent/StructuredTaskScope.html#TreeStructure">Tree
>  Structure section in the class description
diff -r 
docs-master/api/java.base/java/util/concurrent/StructuredTaskScope.ShutdownOnSuccess.html
 
docs/api/java.base/java/util/concurrent/StructuredTaskScope.ShutdownOnSuccess.html
242c242
<  Tree Structure section in the class description
---
>   href="../../../../java.base/java/util/concurrent/StructuredTaskScope.html#TreeStructure">Tree
>  Structure section in the class description
diff -r docs-master/api/java.base/javax/security/auth/Subject.html 
docs/api/java.base/javax/security/auth/Subject.html
207,208c207,208
<  whether a security manager is
<  allowed or 
disallowed:
---
>  whether a security manager is
>   href="../../../java/lang/SecurityManager.html#set-security-manager">allowed 
> or disallowed:

-

Commit messages:
 - (C)
 - Merge remote-tracking branch 'upstream/master' into 
fix-broken-links-java-base
 - remove html warnings, broken links

Changes: https://git.openjdk.org/jdk/pull/20251/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk=20251=00
  Issue: https://bugs.openjdk.org/browse/JDK-8336039
  Stats: 23 lines in 9 files changed: 0 ins; 1 del; 22 mod
  Patch: https://git.openjdk.org/jdk/pull/20251.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/20251/head:pull/20251

PR: https://git.openjdk.org/jdk/pull/20251

Integrated: 8336259: Wrong link to stylesheet.css in JavaDoc API documentation

[Nizar Benalla]

On Thu, 11 Jul 2024 20:55:29 GMT, Nizar Benalla  wrote:

> Can I please get a review for this small change, the relative link to the 
> stylesheet isn't needed as it wasn't used anyway in the generated HTML. The 
> correct link to the stylesheet is already in the generated HTML.
> 
> This is the difference between the generated docs before and after this 
> change, by running `diff -r` on the docs before and after the change.
> 
> 
> GeneratedDocs % diff -r 8336259-stylesheet old-docs   
> diff -r 8336259-stylesheet/api/java.base/java/lang/doc-files/ValueBased.html 
> old-docs/api/java.base/java/lang/doc-files/ValueBased.html
> 13a14
>> > title="Style">
> diff -r 
> 8336259-stylesheet/api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html
>  old-docs/api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html
> 13a14
>> > title="Style">
> 
> 
> Here is the link for the generated docs after the change, no visual change is 
> seen but the erronous link is gone.
> Value based classes 
> [before](https://docs.oracle.com/en%2Fjava%2Fjavase%2F22%2Fdocs%2Fapi%2F%2F/java.base/java/lang/doc-files/ValueBased.html)
>  - 
> [after](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336259-stylesheet/api/java.base/java/lang/doc-files/ValueBased.html)
> 
> Java Thread Primitive Deprecation 
> [before](https://docs.oracle.com/en%2Fjava%2Fjavase%2F22%2Fdocs%2Fapi%2F%2F/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html)
>  - 
> [after](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336259-stylesheet/api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html)

This pull request has now been integrated.

Changeset: 5bc86f33
Author:Nizar Benalla 
Committer: Chen Liang 
URL:   
https://git.openjdk.org/jdk/commit/5bc86f332986e3fffc1363f569029bb73a706064
Stats: 4 lines in 2 files changed: 0 ins; 2 del; 2 mod

8336259: Wrong link to stylesheet.css in JavaDoc API documentation

Reviewed-by: jjg, liach

-

PR: https://git.openjdk.org/jdk/pull/20145

Re: RFR: 8336259: Wrong link to stylesheet.css in JavaDoc API documentation

[Nizar Benalla]

On Thu, 11 Jul 2024 20:55:29 GMT, Nizar Benalla  wrote:

> Can I please get a review for this small change, the relative link to the 
> stylesheet isn't needed as it wasn't used anyway in the generated HTML. The 
> correct link to the stylesheet is already in the generated HTML.
> 
> This is the difference between the generated docs before and after this 
> change, by running `diff -r` on the docs before and after the change.
> 
> 
> GeneratedDocs % diff -r 8336259-stylesheet old-docs   
> diff -r 8336259-stylesheet/api/java.base/java/lang/doc-files/ValueBased.html 
> old-docs/api/java.base/java/lang/doc-files/ValueBased.html
> 13a14
>> > title="Style">
> diff -r 
> 8336259-stylesheet/api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html
>  old-docs/api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html
> 13a14
>> > title="Style">
> 
> 
> Here is the link for the generated docs after the change, no visual change is 
> seen but the erronous link is gone.
> Value based classes 
> [before](https://docs.oracle.com/en%2Fjava%2Fjavase%2F22%2Fdocs%2Fapi%2F%2F/java.base/java/lang/doc-files/ValueBased.html)
>  - 
> [after](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336259-stylesheet/api/java.base/java/lang/doc-files/ValueBased.html)
> 
> Java Thread Primitive Deprecation 
> [before](https://docs.oracle.com/en%2Fjava%2Fjavase%2F22%2Fdocs%2Fapi%2F%2F/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html)
>  - 
> [after](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336259-stylesheet/api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html)

Thank you both for the review

-

PR Comment: https://git.openjdk.org/jdk/pull/20145#issuecomment-2224891104

RFR: 8336259: Wrong link to stylesheet.css in JavaDoc API documentation

[Nizar Benalla]

Can I please get a review for this small change, the relative link to the 
stylesheet isn't needed as it wasn't used anyway in the generated HTML. The 
correct link to the stylesheet is already in the generated HTML.

This is the difference between the generated docs before and after this change, 
by running `diff -r` on the docs before and after the change.


GeneratedDocs % diff -r 8336259-stylesheet old-docs   
diff -r 8336259-stylesheet/api/java.base/java/lang/doc-files/ValueBased.html 
old-docs/api/java.base/java/lang/doc-files/ValueBased.html
13a14
>  title="Style">
diff -r 
8336259-stylesheet/api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html
 old-docs/api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html
13a14
>  title="Style">


Here is the link for the generated docs after the change, no visual change is 
seen but the erronous link is gone.
Value based classes 
[before](https://docs.oracle.com/en%2Fjava%2Fjavase%2F22%2Fdocs%2Fapi%2F%2F/java.base/java/lang/doc-files/ValueBased.html)
 - 
[after](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336259-stylesheet/api/java.base/java/lang/doc-files/ValueBased.html)

Java Thread Primitive Deprecation 
[before](https://docs.oracle.com/en%2Fjava%2Fjavase%2F22%2Fdocs%2Fapi%2F%2F/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html)
 - 
[after](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336259-stylesheet/api/java.base/java/lang/doc-files/threadPrimitiveDeprecation.html)

-

Commit messages:
 - (C)
 - remove incorrect link to stylesheet

Changes: https://git.openjdk.org/jdk/pull/20145/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk=20145=00
  Issue: https://bugs.openjdk.org/browse/JDK-8336259
  Stats: 4 lines in 2 files changed: 0 ins; 2 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/20145.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/20145/head:pull/20145

PR: https://git.openjdk.org/jdk/pull/20145

Withdrawn: 8335727: since-checker: Add `@since` tags to ClassFile::transformClass and CodeBuilder

[Nizar Benalla]

On Thu, 4 Jul 2024 18:04:27 GMT, Nizar Benalla  wrote:

> Please review this simple doc only change.
> Some methods in ClassFile API were renamed recently as part of 
> [JDK-8335290](https://bugs.openjdk.org/browse/JDK-8335290) and 
> [JDK-8335110](https://bugs.openjdk.org/browse/JDK-8335110) and need to have 
> `@since 24`, as they are essentially new methods.
> 
> Thanks!

This pull request has been closed without being integrated.

-

PR: https://git.openjdk.org/jdk/pull/20041

Re: RFR: 8335727: since-checker: Add `@since` tags to ClassFile::transformClass and CodeBuilder

[Nizar Benalla]

On Thu, 4 Jul 2024 18:04:27 GMT, Nizar Benalla  wrote:

> Please review this simple doc only change.
> Some methods in ClassFile API were renamed recently as part of 
> [JDK-8335290](https://bugs.openjdk.org/browse/JDK-8335290) and 
> [JDK-8335110](https://bugs.openjdk.org/browse/JDK-8335110) and need to have 
> `@since 24`, as they are essentially new methods.
> 
> Thanks!

I will close this for now.

-

PR Comment: https://git.openjdk.org/jdk/pull/20041#issuecomment-2213666198

Re: RFR: 8335727: since-checker: Add `@since` tags to ClassFile::transformClass and CodeBuilder

[Nizar Benalla]

On Thu, 4 Jul 2024 18:04:27 GMT, Nizar Benalla  wrote:

> Please review this simple doc only change.
> Some methods in ClassFile API were renamed recently as part of 
> [JDK-8335290](https://bugs.openjdk.org/browse/JDK-8335290) and 
> [JDK-8335110](https://bugs.openjdk.org/browse/JDK-8335110) and need to have 
> `@since 24`, as they are essentially new methods.
> 
> Thanks!

Thank you, I created this PR because the test in #18934 failed when I was 
running it. If ClassFile goes final before the checker is integrated then this 
should be fine.

-

PR Comment: https://git.openjdk.org/jdk/pull/20041#issuecomment-2213612055

Re: RFR: 8335727: since-checker: Add `@since` tags to ClassFile::transformClass and CodeBuilder

[Nizar Benalla]

On Thu, 4 Jul 2024 18:04:27 GMT, Nizar Benalla  wrote:

> Please review this simple doc only change.
> Some methods in ClassFile API were renamed recently as part of 
> [JDK-8335290](https://bugs.openjdk.org/browse/JDK-8335290) and 
> [JDK-8335110](https://bugs.openjdk.org/browse/JDK-8335110) and need to have 
> `@since 24`, as they are essentially new methods.
> 
> Thanks!

No worries! I noticed these by chance today.

-

PR Comment: https://git.openjdk.org/jdk/pull/20041#issuecomment-2209713867

RFR: 8335727: since-checker: Add `@since` tags to ClassFile::transformClass and CodeBuilder

[Nizar Benalla]

Please review this simple doc only change.
Some methods in ClassFile API were renamed recently as part of 
[JDK-8335290](https://bugs.openjdk.org/browse/JDK-8335290) and 
[JDK-8335110](https://bugs.openjdk.org/browse/JDK-8335110) and need to have 
`@since 24`, as they are essentially new methods.

Thanks!

-

Commit messages:
 - add `@since` tags to ClassFile API

Changes: https://git.openjdk.org/jdk/pull/20041/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk=20041=00
  Issue: https://bugs.openjdk.org/browse/JDK-8335727
  Stats: 8 lines in 2 files changed: 8 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/20041.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/20041/head:pull/20041

PR: https://git.openjdk.org/jdk/pull/20041

Integrated: 8330954: since-checker - Fix remaining @ since tags in java.base

[Nizar Benalla]

On Thu, 25 Apr 2024 14:29:27 GMT, Nizar Benalla  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"
> 
>  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.
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/fdd75a26-0396-4c5e-8f59-a3717b7d7ec8;>
> 
> 
> TIA

This pull request has now been integrated.

Changeset: f4fa35e2
Author:Nizar Benalla 
Committer: Chen Liang 
URL:   
https://git.openjdk.org/jdk/commit/f4fa35e28b9881729ac47c8518e758bba676fdec
Stats: 71 lines in 12 files changed: 67 ins; 2 del; 2 mod

8330954: since-checker - Fix remaining @ since tags in java.base

Reviewed-by: liach, naoto

-

PR: https://git.openjdk.org/jdk/pull/18954

Re: RFR: 8330954: since-checker - Fix remaining @ since tags in java.base [v7]

[Nizar Benalla]

On Fri, 28 Jun 2024 11:11:51 GMT, Nizar Benalla  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"
>> 
>> > 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.
>> 
>> > src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>
>> 
>> > src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>
>> 
>> > 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 14 additional 
> commits since the last revision:
> 
>  - Merge remote-tracking branch 'upstream/master' into 8330954
>  - Add new line when having multi-line doc comment
>  - Merge remote-tracking branch 'upstream/master' into 8330954
>  - 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`
>  - ... and 4 more: https://git.openjdk.org/jdk/compare/f122d936...afca07bf

Thank you Naoto for checking, and thanks Chen!

-

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

Integrated: 8332072: Convert package.html files in `java.naming` to package-info.java

[Nizar Benalla]

On Mon, 3 Jun 2024 17:26:52 GMT, Nizar Benalla  wrote:

> Can I please get a review for this small change? The motivation is that javac 
> does not recognize `package.html` files.
> 
> The conversion was simple, I used a script to rename the files, append "*" on 
> the left and remove some HTML tags like `` and ``. I did the 
> conversion in place, renaming them in git but with the big amount of change 
> `git` thinks it's a new file.
> 
> I also added a new `package-info.java` file to `javax.naming.ldap.spi`. I 
> hope that's fine.

This pull request has now been integrated.

Changeset: 6a472797
Author:Nizar Benalla 
Committer: Aleksei Efimov 
URL:   
https://git.openjdk.org/jdk/commit/6a472797a410a6fa27f50371b255054af0cd3c99
Stats: 1431 lines in 11 files changed: 717 ins; 714 del; 0 mod

8332072: Convert package.html files in `java.naming` to package-info.java
8335213: Code snippet in javax.naming.ldap package summary does not compile

Reviewed-by: aefimov

-

PR: https://git.openjdk.org/jdk/pull/19529

Re: RFR: 8332072: Convert package.html files in `java.naming` to package-info.java [v4]

[Nizar Benalla]

On Tue, 2 Jul 2024 16:24:49 GMT, Nizar Benalla  wrote:

>> Can I please get a review for this small change? The motivation is that 
>> javac does not recognize `package.html` files.
>> 
>> The conversion was simple, I used a script to rename the files, append "*" 
>> on the left and remove some HTML tags like `` and ``. I did the 
>> conversion in place, renaming them in git but with the big amount of change 
>> `git` thinks it's a new file.
>> 
>> I also added a new `package-info.java` file to `javax.naming.ldap.spi`. I 
>> hope that's fine.
>
> Nizar Benalla has updated the pull request incrementally with one additional 
> commit since the last revision:
> 
>   remove two unnecessary tags

Thank you Aleksei for your review!

-

PR Comment: https://git.openjdk.org/jdk/pull/19529#issuecomment-2206291461

Re: RFR: 8332072: Convert package.html files in `java.naming` to package-info.java [v3]

[Nizar Benalla]

On Tue, 2 Jul 2024 15:09:49 GMT, Aleksei Efimov  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional 
>> commit since the last revision:
>> 
>>   Improve package description based on  Efimov's suggestion
>
> src/java.naming/share/classes/javax/naming/event/package-info.java line 60:
> 
>> 58:  * An application, for example, can register its interest in changes to
>> 59:  * objects in a context as follows:
>> 60:  * 
> 
> The leftover `` can be removed:
> Suggestion:

Fixed both in 
[657ef5c](https://github.com/openjdk/jdk/pull/19529/commits/657ef5c7532bc587cdead80d35486f30bb931d5e),
 thank you.

-

PR Review Comment: https://git.openjdk.org/jdk/pull/19529#discussion_r1662823840

Re: RFR: 8332072: Convert package.html files in `java.naming` to package-info.java [v4]

[Nizar Benalla]

> Can I please get a review for this small change? The motivation is that javac 
> does not recognize `package.html` files.
> 
> The conversion was simple, I used a script to rename the files, append "*" on 
> the left and remove some HTML tags like `` and ``. I did the 
> conversion in place, renaming them in git but with the big amount of change 
> `git` thinks it's a new file.
> 
> I also added a new `package-info.java` file to `javax.naming.ldap.spi`. I 
> hope that's fine.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  remove two unnecessary tags

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/19529/files
  - new: https://git.openjdk.org/jdk/pull/19529/files/0104e4ac..657ef5c7

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=19529=03
 - incr: https://webrevs.openjdk.org/?repo=jdk=19529=02-03

  Stats: 2 lines in 1 file changed: 0 ins; 2 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/19529.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/19529/head:pull/19529

PR: https://git.openjdk.org/jdk/pull/19529

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v11]

[Nizar Benalla]

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  Skip over files and packages that aren't found

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18934/files
  - new: https://git.openjdk.org/jdk/pull/18934/files/62aebb0b..12d410af

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18934=10
 - incr: https://webrevs.openjdk.org/?repo=jdk=18934=09-10

  Stats: 39 lines in 1 file changed: 10 ins; 7 del; 22 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v10]

[Nizar Benalla]

On Tue, 25 Jun 2024 08:29:42 GMT, Nizar Benalla  wrote:

>> This checker checks the values of the `@since` tag found in the 
>> documentation comment for an element against the release in which the 
>> element first appeared.
>> 
>> Real since value of an API element is computed as the oldest release in 
>> which the given API element was introduced. That is:
>> - for modules, classes and interfaces, the release in which the element with 
>> the given qualified name was introduced
>> - for constructors, the release in which the constructor with the given VM 
>> descriptor was introduced
>> - for methods and fields, the release in which the given method or field 
>> with the given VM descriptor became a member of its enclosing class or 
>> interface, whether direct or inherited
>> 
>> Effective since value of an API element is computed as follows:
>> - if the given element has a `@since` tag in its javadoc, it is used
>> - in all other cases, return the effective since value of the enclosing 
>> element
>> 
>> The since checker verifies that for every API element, the real since value 
>> and the effective since value are the same, and reports an error if they are 
>> not.
>> 
>> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
>> consistently going forward then the checker doesn't need to be updated with 
>> every release. The checker has explicit knowledge of preview elements that 
>> came before `JDK 14` because they weren't marked in a machine understandable 
>> way and preview elements that came before `JDK 17` that didn't have 
>> `@PreviewFeature`.
>> 
>> Important note : We only check code written since `JDK 9` as the releases 
>> used to determine the expected value of `@since` tags are taken from the 
>> historical data built into `javac` which only goes back that far
>> 
>> The intial comment at the beginning of `SinceChecker.java` holds more 
>> information into the program.
>> 
>> I already have filed issues and fixed some wrong tags like in #18640, 
>> #18032, #18030, #18055, #18373, #18954, #18972.
>
> Nizar Benalla has updated the pull request with a new target base due to a 
> merge or a rebase. The pull request now contains 20 commits:
> 
>  - Move the tests to module/module_name directory for clearer naming
>  - (C)
>  - Merge remote-tracking branch 'upstream/master' into 
> source-based-since-checker
>
># Conflicts:
>    #  test/jdk/TEST.groups
>  - Improve checker report messages
>  - Merge branch 'master' into source-based-since-checker
>  - - removed unused parameter `i`
>- make rest of methods private
>- ".toString" instead of "toString"
>
>Signed-off-by: Nizar Benalla 
>  - Add a few more legacy methods, needed a few more after changes to the 
> checker
>  - checking for null values directly rather than catching NPE
>  - Merge remote-tracking branch 'upstream/master' into 
> source-based-since-checker
>  - Now only skipping the common methods that every record class will have, 
> and will never need a new `@since`
>  - ... and 10 more: https://git.openjdk.org/jdk/compare/7baddc20...62aebb0b

I have a couple of small changes after the first approval, mainly improving the 
error messages. And avoiding false reports in case a file doesn't exist in 
`src.zip`

-

PR Comment: https://git.openjdk.org/jdk/pull/18934#issuecomment-219691

Re: RFR: 8330954: since-checker - Fix remaining @ since tags in java.base [v7]

[Nizar Benalla]

> 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"
> 
>  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.
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>
> 
>  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 14 additional commits 
since the last revision:

 - Merge remote-tracking branch 'upstream/master' into 8330954
 - Add new line when having multi-line doc comment
 - Merge remote-tracking branch 'upstream/master' into 8330954
 - 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`
 - ... and 4 more: https://git.openjdk.org/jdk/compare/f0a4fbe9...afca07bf

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18954/files
  - new: https://git.openjdk.org/jdk/pull/18954/files/91df97f7..afca07bf

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18954=06
 - incr: https://webrevs.openjdk.org/?repo=jdk=18954=05-06

  Stats: 4488 lines in 130 files changed: 3244 ins; 715 del; 529 mod
  Patch: https://git.openjdk.org/jdk/pull/18954.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18954/head:pull/18954

PR: https://git.openjdk.org/jdk/pull/18954

Re: RFR: 8332072: Convert package.html files in `java.naming` to package-info.java [v2]

[Nizar Benalla]

On Thu, 27 Jun 2024 10:27:03 GMT, Aleksei Efimov  wrote:

>> 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 four additional 
>> commits since the last revision:
>> 
>>  - use javadoc standards
>>  - Merge remote-tracking branch 'upstream/master' into naming
>>  - remove whitespace
>>  - 8332072: Convert package.html files in `java.naming` to package-info.java
>
> src/java.naming/share/classes/javax/naming/ldap/spi/package-info.java line 29:
> 
>> 27:  *
>> 28:  * Extends the {@code javax.naming.ldap} package to provide the classes
>> 29:  * and interfaces for the Service Provider Interface (SPI) for LDAP
> 
> The `javax.naming.ldap.spi` package only contains SPI classes that can 
> customize DNS lookups when performing LDAP operations. It was added by 
> [JDK-8160768](https://bugs.openjdk.org/browse/JDK-8160768)/[CSR](https://bugs.openjdk.org/browse/JDK-8192975).
>   
> Since the package only contains classes related to this SPI maybe we could 
> change the wording to something like this:
> Suggestion:
> 
>  * Provides the Service Provider Interface for DNS lookups when
>  * performing LDAP operations.

Thanks, Fixed in 
[0104e4a](https://github.com/openjdk/jdk/pull/19529/commits/0104e4ac5a9bfe143822e72756771c29e0f32731)

-

PR Review Comment: https://git.openjdk.org/jdk/pull/19529#discussion_r1658495820

Re: RFR: 8332072: Convert package.html files in `java.naming` to package-info.java [v3]

[Nizar Benalla]

> Can I please get a review for this small change? The motivation is that javac 
> does not recognize `package.html` files.
> 
> The conversion was simple, I used a script to rename the files, append "*" on 
> the left and remove some HTML tags like `` and ``. I did the 
> conversion in place, renaming them in git but with the big amount of change 
> `git` thinks it's a new file.
> 
> I also added a new `package-info.java` file to `javax.naming.ldap.spi`. I 
> hope that's fine.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  Improve package description based on  Efimov's suggestion

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/19529/files
  - new: https://git.openjdk.org/jdk/pull/19529/files/1826633f..0104e4ac

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=19529=02
 - incr: https://webrevs.openjdk.org/?repo=jdk=19529=01-02

  Stats: 2 lines in 1 file changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/19529.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/19529/head:pull/19529

PR: https://git.openjdk.org/jdk/pull/19529

Re: RFR: 8332072: Convert package.html files in `java.naming` to package-info.java [v2]

[Nizar Benalla]

> Can I please get a review for this small change? The motivation is that javac 
> does not recognize `package.html` files.
> 
> The conversion was simple, I used a script to rename the files, append "*" on 
> the left and remove some HTML tags like `` and ``. I did the 
> conversion in place, renaming them in git but with the big amount of change 
> `git` thinks it's a new file.
> 
> I also added a new `package-info.java` file to `javax.naming.ldap.spi`. I 
> hope that's fine.

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 four additional 
commits since the last revision:

 - use javadoc standards
 - Merge remote-tracking branch 'upstream/master' into naming
 - remove whitespace
 - 8332072: Convert package.html files in `java.naming` to package-info.java

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/19529/files
  - new: https://git.openjdk.org/jdk/pull/19529/files/768eebf5..1826633f

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=19529=01
 - incr: https://webrevs.openjdk.org/?repo=jdk=19529=00-01

  Stats: 67137 lines in 1456 files changed: 42388 ins; 18751 del; 5998 mod
  Patch: https://git.openjdk.org/jdk/pull/19529.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/19529/head:pull/19529

PR: https://git.openjdk.org/jdk/pull/19529

Re: RFR: 8332072: Convert package.html files in `java.naming` to package-info.java [v2]

[Nizar Benalla]

On Wed, 26 Jun 2024 18:09:10 GMT, Nizar Benalla  wrote:

>> Can I please get a review for this small change? The motivation is that 
>> javac does not recognize `package.html` files.
>> 
>> The conversion was simple, I used a script to rename the files, append "*" 
>> on the left and remove some HTML tags like `` and ``. I did the 
>> conversion in place, renaming them in git but with the big amount of change 
>> `git` thinks it's a new file.
>> 
>> I also added a new `package-info.java` file to `javax.naming.ldap.spi`. I 
>> hope that's fine.
>
> 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 four additional 
> commits since the last revision:
> 
>  - use javadoc standards
>  - Merge remote-tracking branch 'upstream/master' into naming
>  - remove whitespace
>  - 8332072: Convert package.html files in `java.naming` to package-info.java

I have converted this to use some of the now-current javadoc convetions.

src/java.naming/share/classes/javax/naming/ldap/package-info.java line 200:

> 198:  * if (respCtls != null) {
> 199:  * // Find the one we want
> 200:  * for (int i = 0; i < respCtls.length; i++) {

This is the only change that isn't a direct 1:1 conversion, I hope this ok.

-

PR Review: https://git.openjdk.org/jdk/pull/19529#pullrequestreview-2142622498
PR Review Comment: https://git.openjdk.org/jdk/pull/19529#discussion_r1655320955

Re: RFR: 8330954: since-checker - Fix remaining @ since tags in java.base [v6]

[Nizar Benalla]

On Wed, 26 Jun 2024 17:59:54 GMT, Naoto Sato  wrote:

>> src/java.base/share/classes/java/text/ChoiceFormat.java line 591:
>> 
>>> 589: /**
>>> 590:  * @since 23
>>> 591:  */
>> 
>> IIUC, this addition will add & inherit the javadoc from `NumberFormat`, 
>> which is not the case before. The description for NumberFormat does not fit 
>> with ChoiceFormat. Probably that needs to be addressed with a different 
>> issue.
>
> My review is for the ChoiceFormat class only. So asking for more Reviews for 
> other area

Thanks, I will leave this open for a few more days to let more people from the 
relevant areas review it.

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18954#discussion_r1655315793

Re: RFR: 8330954: since-checker - Fix remaining @ since tags in java.base [v5]

[Nizar Benalla]

On Wed, 26 Jun 2024 12:36:17 GMT, Chen Liang  wrote:

>> 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 12 additional 
>> commits since the last revision:
>> 
>>  - Merge remote-tracking branch 'upstream/master' into 8330954
>>  - 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
>>  - ... and 2 more: https://git.openjdk.org/jdk/compare/82b51c65...dbef517a
>
> src/java.base/share/classes/java/lang/classfile/ClassSignature.java line 44:
> 
>> 42: List typeParameters();
>> 43: 
>> 44: /** {@return the instantiation of the superclass in this signature}
> 
> Suggestion:
> 
> /**
>  * {@return the instantiation of the superclass in this signature}
> 
> I think this is our preference if we have multi-line specs.

Fixed in 
[91df97f](https://github.com/openjdk/jdk/pull/18954/commits/91df97f7661774bf4f262260e0732507399bce68),
 Thanks.

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18954#discussion_r1655253281

Re: RFR: 8330954: since-checker - Fix remaining @ since tags in java.base [v6]

[Nizar Benalla]

> 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"
> 
>  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.
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/fdd75a26-0396-4c5e-8f59-a3717b7d7ec8;>
> 
> 
> TIA

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  Add new line when having multi-line doc comment

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18954/files
  - new: https://git.openjdk.org/jdk/pull/18954/files/dbef517a..91df97f7

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18954=05
 - incr: https://webrevs.openjdk.org/?repo=jdk=18954=04-05

  Stats: 2 lines in 1 file changed: 1 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/18954.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18954/head:pull/18954

PR: https://git.openjdk.org/jdk/pull/18954

Re: RFR: 8330954: since-checker - Fix remaining @ since tags in java.base [v5]

[Nizar Benalla]

> 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"
> 
>  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.
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>
> 
>  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 12 additional commits 
since the last revision:

 - Merge remote-tracking branch 'upstream/master' into 8330954
 - 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
 - ... and 2 more: https://git.openjdk.org/jdk/compare/5654cccb...dbef517a

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18954/files
  - new: https://git.openjdk.org/jdk/pull/18954/files/b3574b97..dbef517a

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18954=04
 - incr: https://webrevs.openjdk.org/?repo=jdk=18954=03-04

  Stats: 141869 lines in 2684 files changed: 97659 ins; 31514 del; 12696 mod
  Patch: https://git.openjdk.org/jdk/pull/18954.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18954/head:pull/18954

PR: https://git.openjdk.org/jdk/pull/18954

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v10]

[Nizar Benalla]

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

Nizar Benalla has updated the pull request with a new target base due to a 
merge or a rebase. The pull request now contains 20 commits:

 - Move the tests to module/module_name directory for clearer naming
 - (C)
 - Merge remote-tracking branch 'upstream/master' into 
source-based-since-checker
   
   # Conflicts:
   #test/jdk/TEST.groups
 - Improve checker report messages
 - Merge branch 'master' into source-based-since-checker
 - - removed unused parameter `i`
   - make rest of methods private
   - ".toString" instead of "toString"
   
   Signed-off-by: Nizar Benalla 
 - Add a few more legacy methods, needed a few more after changes to the checker
 - checking for null values directly rather than catching NPE
 - Merge remote-tracking branch 'upstream/master' into 
source-based-since-checker
 - Now only skipping the common methods that every record class will have, and 
will never need a new `@since`
 - ... and 10 more: https://git.openjdk.org/jdk/compare/7baddc20...62aebb0b

-

Changes: https://git.openjdk.org/jdk/pull/18934/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk=18934=09
  Stats: 959 lines in 3 files changed: 957 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Re: RFR: 8332072: Convert package.html files in `java.naming` to package-info.java

[Nizar Benalla]

On Mon, 3 Jun 2024 17:26:52 GMT, Nizar Benalla  wrote:

> Can I please get a review for this small change? The motivation is that javac 
> does not recognize `package.html` files.
> 
> The conversion was simple, I used a script to rename the files, append "*" on 
> the left and remove some HTML tags like `` and ``. I did the 
> conversion in place, renaming them in git but with the big amount of change 
> `git` thinks it's a new file.
> 
> I also added a new `package-info.java` file to `javax.naming.ldap.spi`. I 
> hope that's fine.

Sure, I will do it for this one.

-

PR Comment: https://git.openjdk.org/jdk/pull/19529#issuecomment-2148690821

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v9]

[Nizar Benalla]

On Tue, 4 Jun 2024 20:44:30 GMT, Nizar Benalla  wrote:

>> This checker checks the values of the `@since` tag found in the 
>> documentation comment for an element against the release in which the 
>> element first appeared.
>> 
>> Real since value of an API element is computed as the oldest release in 
>> which the given API element was introduced. That is:
>> - for modules, classes and interfaces, the release in which the element with 
>> the given qualified name was introduced
>> - for constructors, the release in which the constructor with the given VM 
>> descriptor was introduced
>> - for methods and fields, the release in which the given method or field 
>> with the given VM descriptor became a member of its enclosing class or 
>> interface, whether direct or inherited
>> 
>> Effective since value of an API element is computed as follows:
>> - if the given element has a `@since` tag in its javadoc, it is used
>> - in all other cases, return the effective since value of the enclosing 
>> element
>> 
>> The since checker verifies that for every API element, the real since value 
>> and the effective since value are the same, and reports an error if they are 
>> not.
>> 
>> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
>> consistently going forward then the checker doesn't need to be updated with 
>> every release. The checker has explicit knowledge of preview elements that 
>> came before `JDK 14` because they weren't marked in a machine understandable 
>> way and preview elements that came before `JDK 17` that didn't have 
>> `@PreviewFeature`.
>> 
>> Important note : We only check code written since `JDK 9` as the releases 
>> used to determine the expected value of `@since` tags are taken from the 
>> historical data built into `javac` which only goes back that far
>> 
>> The intial comment at the beginning of `SinceChecker.java` holds more 
>> information into the program.
>> 
>> I already have filed issues and fixed some wrong tags like in #18640, 
>> #18032, #18030, #18055, #18373, #18954, #18972.
>
> 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 17 additional 
> commits since the last revision:
> 
>  - Improve checker report messages
>  - Merge branch 'master' into source-based-since-checker
>  - - removed unused parameter `i`
>- make rest of methods private
>- ".toString" instead of "toString"
>
>Signed-off-by: Nizar Benalla 
>  - Add a few more legacy methods, needed a few more after changes to the 
> checker
>  - checking for null values directly rather than catching NPE
>  - Merge remote-tracking branch 'upstream/master' into 
> source-based-since-checker
>  - Now only skipping the common methods that every record class will have, 
> and will never need a new `@since`
>  - - Not checking elements enclosed within a record, I doubt a record class 
> will change after being created
>- Added a null check as `toString` can return an exception
>  - - Added some legacy modules that existed long before preview features 
> (they were incubating)
>- Not checking elements enclosed withing a record
>- Only check if the file is readable using `Files.isReadable`
>- Dropped the use of `Files.exists` and `Files.isDirectory`
>- Use `--add-modules` option now to resolve certain modules
>  - mention packages in initial comment
>  - ... and 7 more: https://git.openjdk.org/jdk/compare/026b5fc2...5be962b7

While this might seem like a lot, if a developer runs it before pushing, they 
should only encounter a few reports at most.

-

PR Comment: https://git.openjdk.org/jdk/pull/18934#issuecomment-2148393893

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v8]

[Nizar Benalla]

On Mon, 27 May 2024 12:04:20 GMT, Nizar Benalla  wrote:

>> This checker checks the values of the `@since` tag found in the 
>> documentation comment for an element against the release in which the 
>> element first appeared.
>> 
>> Real since value of an API element is computed as the oldest release in 
>> which the given API element was introduced. That is:
>> - for modules, classes and interfaces, the release in which the element with 
>> the given qualified name was introduced
>> - for constructors, the release in which the constructor with the given VM 
>> descriptor was introduced
>> - for methods and fields, the release in which the given method or field 
>> with the given VM descriptor became a member of its enclosing class or 
>> interface, whether direct or inherited
>> 
>> Effective since value of an API element is computed as follows:
>> - if the given element has a `@since` tag in its javadoc, it is used
>> - in all other cases, return the effective since value of the enclosing 
>> element
>> 
>> The since checker verifies that for every API element, the real since value 
>> and the effective since value are the same, and reports an error if they are 
>> not.
>> 
>> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
>> consistently going forward then the checker doesn't need to be updated with 
>> every release. The checker has explicit knowledge of preview elements that 
>> came before `JDK 14` because they weren't marked in a machine understandable 
>> way and preview elements that came before `JDK 17` that didn't have 
>> `@PreviewFeature`.
>> 
>> Important note : We only check code written since `JDK 9` as the releases 
>> used to determine the expected value of `@since` tags are taken from the 
>> historical data built into `javac` which only goes back that far
>> 
>> The intial comment at the beginning of `SinceChecker.java` holds more 
>> information into the program.
>> 
>> I already have filed issues and fixed some wrong tags like in #18640, 
>> #18032, #18030, #18055, #18373, #18954, #18972.
>
> Nizar Benalla has updated the pull request incrementally with one additional 
> commit since the last revision:
> 
>   - removed unused parameter `i`
>   - make rest of methods private
>   - ".toString" instead of "toString"
>   
>   Signed-off-by: Nizar Benalla 

The checker's report has been improved, the result after running it on 
`java.base` is the following

SinceChecker java.base
STDERR:
src/java.base/java/io/PrintStream.java:685 method: void 
java.io.PrintStream.write(byte[]): `@since` version is 14 but the element 
exists before JDK 10
src/java.base/java/io/FileInputStream.java:374 method: byte[] 
java.io.FileInputStream.readNBytes(int): `@since` version: 9; found: 11
src/java.base/java/lang/classfile/ClassSignature.java:45 method: 
java.lang.classfile.Signature.ClassTypeSig 
java.lang.classfile.ClassSignature.superclassSignature(): `@since` version: 22; 
found: 23
src/java.base/java/lang/classfile/ClassReader.java:131 method: 
java.lang.classfile.constantpool.PoolEntry 
java.lang.classfile.ClassReader.readEntryOrNull(int,java.lang.Class): `@since` 
version: 24; found: 23
src/java.base/java/lang/classfile/constantpool/ConstantPool.java:74 method: 
java.lang.classfile.constantpool.PoolEntry 
java.lang.classfile.constantpool.ConstantPool.entryByIndex(int,java.lang.Class):
 `@since` version: 24; found: 23
src/java.base/java/lang/constant/ClassDesc.java:378 method: java.lang.Class 
java.lang.constant.ClassDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup):
 `@since` version: 12; found: 21
src/java.base/java/lang/constant/MethodTypeDesc.java:226 method: 
java.lang.invoke.MethodType 
java.lang.constant.MethodTypeDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup):
 `@since` version: 12; found: 21
src/java.base/java/lang/constant/MethodHandleDesc.java:210 method: 
java.lang.invoke.MethodHandle 
java.lang.constant.MethodHandleDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup):
 `@since` version: 12; found: 21
src/java.base/java/lang/foreign/MemorySegment.java:622 method: long 
java.lang.foreign.MemorySegment.maxByteAlignment(): `@since` version: 22; 
found: 23
src/java.base/java/lang/invoke/MethodHandles.java:7923 method: 
java.lang.invoke.MethodHandle 
java.lang.invoke.MethodHandles.tableSwitch(java.lang.invoke.MethodHandle,java.lang.invoke.MethodHandle[]):
 `@since` version: 9; found: 17
src/java.base/java/lang/ref/Reference.java:527 method: java.lang.Object 
java.lang.ref.Reference.clone(): `@since` version is 11 but the element exists 
before JDK 10
src/java.base/java/lang/reflect/MalformedParameterizedTypeException.java:54 
method: void

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v9]

[Nizar Benalla]

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

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 17 additional commits 
since the last revision:

 - Improve checker report messages
 - Merge branch 'master' into source-based-since-checker
 - - removed unused parameter `i`
   - make rest of methods private
   - ".toString" instead of "toString"
   
   Signed-off-by: Nizar Benalla 
 - Add a few more legacy methods, needed a few more after changes to the checker
 - checking for null values directly rather than catching NPE
 - Merge remote-tracking branch 'upstream/master' into 
source-based-since-checker
 - Now only skipping the common methods that every record class will have, and 
will never need a new `@since`
 - - Not checking elements enclosed within a record, I doubt a record class 
will change after being created
   - Added a null check as `toString` can return an exception
 - - Added some legacy modules that existed long before preview features (they 
were incubating)
   - Not checking elements enclosed withing a record
   - Only check if the file is readable using `Files.isReadable`
   - Dropped the use of `Files.exists` and `Files.isDirectory`
   - Use `--add-modules` option now to resolve certain modules
 - mention packages in initial comment
 - ... and 7 more: https://git.openjdk.org/jdk/compare/544d8c3f...5be962b7

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18934/files
  - new: https://git.openjdk.org/jdk/pull/18934/files/85b2d1a5..5be962b7

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18934=08
 - incr: https://webrevs.openjdk.org/?repo=jdk=18934=07-08

  Stats: 77006 lines in 1512 files changed: 56440 ins; 13399 del; 7167 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Integrated: 8326951: since-checker - missing @ since tags

[Nizar Benalla]

On Thu, 29 Feb 2024 09:45:35 GMT, Nizar Benalla  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 
Committer: Jaikiran Pai 
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

Re: RFR: 8326951: since-checker - missing @ since tags [v9]

[Nizar Benalla]

On Mon, 13 May 2024 20:39:14 GMT, Nizar Benalla  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

Re: RFR: 8326951: since-checker - missing @ since tags [v9]

[Nizar Benalla]

On Mon, 13 May 2024 20:39:14 GMT, Nizar Benalla  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

Here is a snippet from the report of the checker with the relevant bits for 
this PR

STDERR:
method: void java.io.PrintStream.write(byte[]): `@since` version is 14 but the 
element exists before JDK 10
method: java.lang.invoke.MethodHandle 
java.lang.invoke.MethodHandles.tableSwitch(java.lang.invoke.MethodHandle,java.lang.invoke.MethodHandle[]):
 `@since` version is 9 instead of 17
method: void 
java.lang.reflect.MalformedParameterizedTypeException.(java.lang.String): 
`@since` version is 9 instead of 10
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.slice(): `@since` 
version is 9 instead of 17
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.slice(int,int): 
`@since` version is 9 instead of 17
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.duplicate(): 
`@since` version is 9 instead of 17
method: java.nio.MappedByteBuffer java.nio.MappedByteBuffer.compact(): `@since` 
version is 9 instead of 17
method: void java.util.Properties.(int): `@since` version is 9 instead of 
10
method: float java.util.concurrent.ThreadLocalRandom.nextFloat(float): `@since` 
version is 9 instead of 17
method: float java.util.concurrent.ThreadLocalRandom.nextFloat(float,float): 
`@since` version is 9 instead of 17
method: void java.util.zip.Deflater.setDictionary(java.nio.ByteBuffer): 
`@since` version is 9 instead of 11




Here is the full report

STDERR:
method: void java.io.PrintStream.write(byte[]): `@since` version is 14 but the 
element exists before JDK 10
method: byte[] java.io.FileInputStream.readNBytes(int): `@since` version is 9 
instead of 11
method: java.lang.classfile.Signature.ClassTypeSig 
java.lang.classfile.ClassSignature.superclassSignature(): `@since` version is 
22 instead of 23
method: java.lang.classfile.constantpool.PoolEntry 
java.lang.classfile.ClassReader.readEntryOrNull(int,java.lang.Class): `@since` 
version is 24 instead of 23
method: java.lang.classfile.constantpool.PoolEntry 
java.lang.classfile.constantpool.ConstantPool.entryByIndex(int,java.lang.Class):
 `@since` version is 24 instead of 23
method: java.lang.Class 
java.lang.constant.ClassDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup):
 `@since` version is 12 instead of 21
method: java.lang.invoke.MethodType 
java.lang.constant.MethodTypeDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup):
 `@since` version is 12 instead of 21
method: java.lang.invoke.MethodHandle 
java.lang.constant.MethodHandleDesc.resolveConstantDesc(java.lang.invoke.MethodHandles.Lookup):
 `@since` version is 12 instead of 21
method: long java.lang.foreign.MemorySegment.m

RFR: 8332072: Convert package.html files in `java.naming` to package-info.java

[Nizar Benalla]

Can I please get a review for this small change? The motivation is that javac 
does not recognize `package.html` files.

The conversion was simple, I used a script to rename the files, append "*" on 
the left and remove some HTML tags like  and . I did the conversion 
in place, renaming them in git but with the big amount of change git thinks 
it's a new file.

I also added a new `package-info.java` file to `javax.naming.ldap.spi`. I hope 
that's fine.

-

Commit messages:
 - remove whitespace
 - 8332072: Convert package.html files in `java.naming` to package-info.java

Changes: https://git.openjdk.org/jdk/pull/19529/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk=19529=00
  Issue: https://bugs.openjdk.org/browse/JDK-8332072
  Stats: 1438 lines in 11 files changed: 724 ins; 714 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/19529.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/19529/head:pull/19529

PR: https://git.openjdk.org/jdk/pull/19529

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v8]

[Nizar Benalla]

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  - removed unused parameter `i`
  - make rest of methods private
  - ".toString" instead of "toString"
  
  Signed-off-by: Nizar Benalla 

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18934/files
  - new: https://git.openjdk.org/jdk/pull/18934/files/fc10107a..85b2d1a5

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18934=07
 - incr: https://webrevs.openjdk.org/?repo=jdk=18934=06-07

  Stats: 4 lines in 1 file changed: 0 ins; 0 del; 4 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v7]

[Nizar Benalla]

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  Add a few more legacy methods, needed a few more after changes to the checker

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18934/files
  - new: https://git.openjdk.org/jdk/pull/18934/files/e82dfbf0..fc10107a

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18934=06
 - incr: https://webrevs.openjdk.org/?repo=jdk=18934=05-06

  Stats: 16 lines in 1 file changed: 10 ins; 4 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v5]

[Nizar Benalla]

On Fri, 17 May 2024 15:00:39 GMT, Jan Lahoda  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional 
>> commit since the last revision:
>> 
>>   - Not checking elements enclosed within a record, I doubt a record class 
>> will change after being created
>>   - Added a null check as `toString` can return an exception
>
> test/jdk/tools/sincechecker/SinceChecker.java line 352:
> 
>> 350: }
>> 351: checkElement(te.getEnclosingElement(), te, types, 
>> javadocHelper, version, elementUtils);
>> 352: if( te.getKind() == ElementKind.RECORD){
> 
> This seems a bit too broad. Ignoring all members of a record type may lead to 
> missed members. `Elements.getOrigin` may be unusable here, but I wonder what 
> exactly is the problem which this condition is trying to solve?

I changed my approach in 
[ac4df85](https://github.com/openjdk/jdk/pull/18934/commits/ac4df85615557306da606a712ee02e7155e5412f).
 I beleieve it is a bit clearer now. I am only skipping some very common 
methods (`toString`, `equals` and `hashCode`)

Previously, I failed to get the effective `@since` of some common methods 
eclosed within a record.
I will use this as an example
https://github.com/openjdk/jdk/blob/b92bd671835c37cff58e2cdcecd0fe4277557d7f/src/jdk.jshell/share/classes/jdk/jshell/execution/JdiDefaultExecutionControl.java#L346

`te.getEnclosedElements()` on this record returns the following (I truncated 
`jdk.jshell.execution.JdiDefaultExecutionControl.JdiStarter.TargetDescription` 
into `TargetDescription`)

method: void 
TargetDescription.(com.sun.jdi.VirtualMachine,java.lang.Process) 
method: void TargetDescription.wait(long,int) 
method: java.lang.Process TargetDescription.process() 
method: com.sun.jdi.VirtualMachine TargetDescription.vm() 
method: java.lang.String TargetDescription.toString() 
method: int TargetDescription.hashCode() 
method: java.lang.Object TargetDescription.clone() 
method: java.lang.Class TargetDescription.getClass() 
method: void TargetDescription.finalize() 
method: void TargetDescription.notify() 
method: void TargetDescription.wait(long) 
method: boolean TargetDescription.equals(java.lang.Object) 
method: void TargetDescription.notifyAll() 
method: void TargetDescription.wait() 


Getting the effective `@since` for these 5 methods in particular would fail

method: java.lang.String TargetDescription.toString():
method: int TargetDescription.hashCode(): 
method: boolean TargetDescription.equals(java.lang.Object):
method: com.sun.jdi.VirtualMachine TargetDescription.vm(): 
method: java.lang.Process TargetDescription.process():

It seemed to me that these methods would be added in the same version as the 
record, so I skipped them all.
I didn't think of a user adding a static variable in a later release and that 
it was too broad, my bad.

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1605899531

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v6]

[Nizar Benalla]

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

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 13 additional commits 
since the last revision:

 - checking for null values directly rather than catching NPE
 - Merge remote-tracking branch 'upstream/master' into 
source-based-since-checker
 - Now only skipping the common methods that every record class will have, and 
will never need a new `@since`
 - - Not checking elements enclosed within a record, I doubt a record class 
will change after being created
   - Added a null check as `toString` can return an exception
 - - Added some legacy modules that existed long before preview features (they 
were incubating)
   - Not checking elements enclosed withing a record
   - Only check if the file is readable using `Files.isReadable`
   - Dropped the use of `Files.exists` and `Files.isDirectory`
   - Use `--add-modules` option now to resolve certain modules
 - mention packages in initial comment
 - -Wrap lines at 80-100
   -Changes `e.getMessages` to `e`
   -`File.separator` to be platform indepedant
   -Added a newline character at the end of files
   -Rename `persistElement` to `processElement`
   -Now throwing IllegalArgumentException instead of SkippedException
 - trivial change - extra parentheses
 - General improvements:
   - added more detail to the initial comment
   - ordered imports correctly
   - renamed methods to be more consistent
   - added predicate methods and 'isDocumented' 'isMember'
   - added doc comments describing purpose of 'EffectiveSourceSinceHelper'
 - Add more details to the initial comment
 - ... and 3 more: https://git.openjdk.org/jdk/compare/aed682c5...e82dfbf0

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18934/files
  - new: https://git.openjdk.org/jdk/pull/18934/files/48c87814..e82dfbf0

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18934=05
 - incr: https://webrevs.openjdk.org/?repo=jdk=18934=04-05

  Stats: 77304 lines in 2370 files changed: 38057 ins; 29029 del; 10218 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v5]

[Nizar Benalla]

On Fri, 17 May 2024 14:49:46 GMT, Jan Lahoda  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional 
>> commit since the last revision:
>> 
>>   - Not checking elements enclosed within a record, I doubt a record class 
>> will change after being created
>>   - Added a null check as `toString` can return an exception
>
> test/jdk/tools/sincechecker/SinceChecker.java line 224:
> 
>> 222: }
>> 223: 
>> 224: return LEGACY_PREVIEW_METHODS.containsKey(currentVersion)
> 
> Nit: could probably be `LEGACY_PREVIEW_METHODS.getOrDefault(currentVersion, 
> Map.of()).contains(uniqueId)`

Fixed, thanks.

> test/jdk/tools/sincechecker/SinceChecker.java line 309:
> 
>> 307: error("module-info.java not found or couldn't be opened 
>> AND this module has no unqualified exports");
>> 308: } catch (NullPointerException e) {
>> 309: error("module-info.java does not contain an `@since`");
> 
> Catching a NPE like this feels like a code smell to me. I assume it may 
> happen when `extractSinceVersionFromText(moduleInfoContent)` returns `null` - 
> so just store that in a variable, and check for `null` there.

Fixed in 
[e82dfbf](https://github.com/openjdk/jdk/pull/18934/commits/e82dfbf0f3df1dfcb1e482aac09fb34e39af9be0),
 I tried not catching NPE before but found the extra checks a bit ugly.

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1605898860
PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1605898785

Integrated: 8332101: Add an `@since` to `StandardOperation:REMOVE` in `jdk.dynalink`

[Nizar Benalla]

On Sat, 11 May 2024 15:39:04 GMT, Nizar Benalla  wrote:

> Code cleanup, please review this simple change. I split my changes into 1 PR 
> per module to make reviewing simpler.
> To help with the review, this was added back in 
> https://bugs.openjdk.org/browse/JDK-8191905
> TIA

This pull request has now been integrated.

Changeset: f9f8d0b4
Author:    Nizar Benalla 
Committer: Jaikiran Pai 
URL:   
https://git.openjdk.org/jdk/commit/f9f8d0b48057a02923e36c8e11286b57cc72279e
Stats: 3 lines in 1 file changed: 2 ins; 0 del; 1 mod

8332101: Add an `@since` to `StandardOperation:REMOVE` in `jdk.dynalink`

Reviewed-by: jpai

-

PR: https://git.openjdk.org/jdk/pull/19189

Re: RFR: 8326951: Missing `@since` tags [v9]

[Nizar Benalla]

> 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

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18055/files
  - new: https://git.openjdk.org/jdk/pull/18055/files/d3b8e64c..e66fbf5a

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18055=08
 - incr: https://webrevs.openjdk.org/?repo=jdk=18055=07-08

  Stats: 0 lines in 0 files changed: 0 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/18055.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18055/head:pull/18055

PR: https://git.openjdk.org/jdk/pull/18055

Re: RFR: 8326951: Missing `@since` tags [v8]

[Nizar Benalla]

> 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 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 15 additional commits 
since the last revision:

 - Merge remote-tracking branch 'upstream/master' into add-missing-since-tags
 - deal with methods with different return types - added some spaces for 
readability
 - removed change
 - Update full name
 - update the copyright year to 2024
 - Revert "update the copyright year to 2024"
   
   This reverts commit 9ddd230dcf88bedade76a8e2804db6e120a200f8.
 - update the copyright year to 2024
 - added since tag
 - Revert "fix rest of private/public since tags"
   
   This reverts commit 2c04a9d8e773616b7b6239335d4e5eb955944ad1.
 - Revert "removed unnecessary @ since tags"
   
   This reverts commit 5da3f0d83d19393eeb3a9da68aac40dd999de660.
 - ... and 5 more: https://git.openjdk.org/jdk/compare/893cd607...d3b8e64c

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18055/files
  - new: https://git.openjdk.org/jdk/pull/18055/files/670acaec..d3b8e64c

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18055=07
 - incr: https://webrevs.openjdk.org/?repo=jdk=18055=06-07

  Stats: 592766 lines in 7064 files changed: 99933 ins; 147099 del; 345734 mod
  Patch: https://git.openjdk.org/jdk/pull/18055.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18055/head:pull/18055

PR: https://git.openjdk.org/jdk/pull/18055

Re: RFR: 8330954: Fix remaining `@since` tags in `java.base` [v4]

[Nizar Benalla]

> 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"
> 
>  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.
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>
> 
>  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/14267b99...b3574b97

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18954/files
  - new: https://git.openjdk.org/jdk/pull/18954/files/be91ab80..b3574b97

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18954=03
 - incr: https://webrevs.openjdk.org/?repo=jdk=18954=02-03

  Stats: 52850 lines in 2204 files changed: 24705 ins; 18722 del; 9423 mod
  Patch: https://git.openjdk.org/jdk/pull/18954.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18954/head:pull/18954

PR: https://git.openjdk.org/jdk/pull/18954

Re: RFR: 8330954: Fix remaining `@since` tags in `java.base` [v3]

[Nizar Benalla]

On Mon, 13 May 2024 17:52:23 GMT, Chen Liang  wrote:

>> Nizar Benalla has updated the pull request incrementally with two additional 
>> commits since the last revision:
>> 
>>  - (C)
>>  - (C)
>
> src/java.base/share/classes/java/security/interfaces/RSAPrivateKey.java line 
> 2:
> 
>> 1: /*
>> 2:  * Copyright (c) 1998, 2023, Oracle and/or its affiliates. All rights 
>> reserved.
> 
> This diff is redundant but no-op. You should merge openjdk/jdk's master 
> branch to your PR branch, so the diff displayed by GitHub is up-to-date and 
> this will go away.

I don't want to merge or rebase on an active PR. It should get fixed once this 
is integrated.

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18954#discussion_r1598847527

Re: RFR: 8330954: Fix remaining `@since` tags in `java.base` [v3]

[Nizar Benalla]

> 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"
> 
>  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.
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/fdd75a26-0396-4c5e-8f59-a3717b7d7ec8;>
> 
> 
> TIA

Nizar Benalla has updated the pull request incrementally with two additional 
commits since the last revision:

 - (C)
 - (C)

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18954/files
  - new: https://git.openjdk.org/jdk/pull/18954/files/d38a1c7d..be91ab80

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18954=02
 - incr: https://webrevs.openjdk.org/?repo=jdk=18954=01-02

  Stats: 7 lines in 7 files changed: 0 ins; 0 del; 7 mod
  Patch: https://git.openjdk.org/jdk/pull/18954.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18954/head:pull/18954

PR: https://git.openjdk.org/jdk/pull/18954

RFR: 8332101: Add an `@since` to `StandardOperation:REMOVE` in `jdk.dynalink`

[Nizar Benalla]

Code cleanup, please review this simple change.
To help with the review, this was added back in 
https://bugs.openjdk.org/browse/JDK-8191905
TIA

-

Commit messages:
 - add an `@since` and modify Copyright header

Changes: https://git.openjdk.org/jdk/pull/19189/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk=19189=00
  Issue: https://bugs.openjdk.org/browse/JDK-8332101
  Stats: 3 lines in 1 file changed: 2 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/19189.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/19189/head:pull/19189

PR: https://git.openjdk.org/jdk/pull/19189

Re: RFR: 8332101: Add an `@since` to `StandardOperation:REMOVE` in `jdk.dynalink`

[Nizar Benalla]

On Sat, 11 May 2024 15:39:04 GMT, Nizar Benalla  wrote:

> Code cleanup, please review this simple change.
> To help with the review, this was added back in 
> https://bugs.openjdk.org/browse/JDK-8191905
> TIA

I believe `jdk.nashorn` is under core-libs

-

PR Comment: https://git.openjdk.org/jdk/pull/19189#issuecomment-2105941152

Integrated: 8326836: Incorrect `@since` tags for ClassSignature methods

[Nizar Benalla]

On Tue, 27 Feb 2024 15:10:37 GMT, Nizar Benalla  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 
Committer: Adam Sotona 
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

Re: RFR: 8330954: Fix remaining `@since` tags in `java.base` [v2]

[Nizar Benalla]

> 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"
> 
>  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.
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/fdd75a26-0396-4c5e-8f59-a3717b7d7ec8;>
> 
> 
> TIA

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  Move security classes changes to pr18373

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18954/files
  - new: https://git.openjdk.org/jdk/pull/18954/files/62e623fa..d38a1c7d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18954=01
 - incr: https://webrevs.openjdk.org/?repo=jdk=18954=00-01

  Stats: 2 lines in 2 files changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/18954.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18954/head:pull/18954

PR: https://git.openjdk.org/jdk/pull/18954

Re: RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Nizar Benalla]

On Thu, 25 Apr 2024 14:29:27 GMT, Nizar Benalla  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"
> 
>  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.
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/fdd75a26-0396-4c5e-8f59-a3717b7d7ec8;>
> 
> 
> TIA

Thanks, I read those two links yesterday and was thinking of which project lead 
to mail to be added to the census. Will do so later.

-

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

Re: RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Nizar Benalla]

On Mon, 29 Apr 2024 17:26:53 GMT, Chen Liang  wrote:

>> src/java.base/share/classes/java/io/FileInputStream.java line 345:
>> 
>>> 343:  * @throwsIllegalArgumentException {@inheritDoc}
>>> 344:  * @throwsIOException {@inheritDoc}
>>> 345:  * @throwsOutOfMemoryError {@inheritDoc}
>> 
>> Re: inheriting _unchecked_ exception documentation here and elsewhere in 
>> this PR
>> 
>> This PR's title suggests that the PR has nothing to do with exception 
>> documentation. If you feel that it should be addressed, please file a 
>> separate bug and move these changes there.
>> 
>> FWIW, I agree that `@throws ... {@inheritDoc}` for such exceptions are at 
>> least worth being considered. It's a common misconception that all exception 
>> documentation is inherited automatically.
>
> This is because the tool from #18934 has no easy way to fetch the doc comment 
> from a superclass/superinterface overridden method when this class only has a 
> plain override. Javadoc handles this in complex logic in 
> `VisibleMemberTable`; it's hard for other clients to try to emulate the 
> behavior of doc finding, and the tool just incorrectly assumes such methods 
> (what I have been talking about before) are reusing `@since` from the class 
> docs.

Pavel, can I simply change the PR/issue title to be more descriptive? 
As I want to include the the inherit doc because of the unchecked exceptions, 
rather than clean this up in a different PR

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18954#discussion_r1583479753

Re: RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Nizar Benalla]

On Fri, 26 Apr 2024 14:52:08 GMT, Chen Liang  wrote:

> > We will effectively enforce javadoc comment for some method overrides with 
> > the checker
> 
> Those overriding methods don't even appear on the javadoc output. If you go 
> to search for `CompletableFuture.resultNow` on 
> https://docs.oracle.com/en/java/javase/22/docs/api/ you will find nothing. 
> Why are we fixing "broken since tags" that don't even exist in the first 
> place?
> 
> Also have you looked at the output documentation? Without the `@inheritDoc` 
> tags the content will only have a since tag, which is definitely wrong.

For overriding methods we don't look into the supertype because that's what 
`javadoc` (the tool) is doing, `javadoc` doesn't look into the supertype and 
has no special handling or support for `@since` tags in inherited methods.
If `javadoc` changes how it deals with method overriding in the future we will 
match it's behavior and look into the supertype for overriding methods.
What is important is that we have to match the rules used in `javadoc`.
You can't have both, either you add explicit javadoc comments to these methods 
or use rules that go against the current behavior or `javadoc`

-

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

Re: RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Nizar Benalla]

On Thu, 25 Apr 2024 14:29:27 GMT, Nizar Benalla  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"
> 
>  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.
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>
> 
>  src="https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>
> 
>  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

RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Nizar Benalla]

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"

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.

https://github.com/openjdk/jdk/assets/96922791/89b92288-9b5e-48ed-8fa1-9342ea43e043;>

https://github.com/openjdk/jdk/assets/96922791/9aef08ff-5030-4189-a996-582a7eef849b;>

https://github.com/openjdk/jdk/assets/96922791/fdd75a26-0396-4c5e-8f59-a3717b7d7ec8;>


TIA

-

Commit messages:
 - 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
 - add tags to elements from `java.base`

Changes: https://git.openjdk.org/jdk/pull/18954/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk=18954=00
  Issue: https://bugs.openjdk.org/browse/JDK-8330954
  Stats: 71 lines in 14 files changed: 66 ins; 2 del; 3 mod
  Patch: https://git.openjdk.org/jdk/pull/18954.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18954/head:pull/18954

PR: https://git.openjdk.org/jdk/pull/18954

Re: RFR: 8330954: Fix remaining `@since` tags in `java.base`

[Nizar Benalla]

On Thu, 25 Apr 2024 16:43:50 GMT, Chen Liang  wrote:

> I think your changes mostly group in these categories:
> 
> 1. New API methods provided in superclasses/superinterfaces, this class 
> provides a more concrete implementation:
>Examples being `CompletableFuture`, `FileInputStream`, `DelayQueue`, 
> `FutureTask`
>I don't think you should add since tags for these; without explicit 
> javadoc, the methods inherit the superclass/superinterface docs, and appear 
> in `Methods declared in class/interface Xxx` (supertype) section, which 
> already have the correct since tags.
>There's one scenario where such addition may be meaningful, however: 
> that's if the supertype's since version is newer than this class/interfaces's 
> since version, so we might need to specify here.
>(On a side note, it would be great if we can mark the since version of an 
> interface, notorious example being `ZipFile` retrofitted to implement 
> `Closeable` in 1.7 and breaks compile target 1.6)
> 2. Remove unnecessary since tags for existing API methods with newer 
> implementation
>Examples being `Reference`, `RsaPrivateKey`. These make sense.
> 3. API methods with different return types
>Examples being `ClassSignature`, `ClassDesc`. These make sense too, as 
> older version may return different types. But problem here is should we count 
> methods with only signature (but not descriptor) differences, like 
> `ClassSignature::superinterfaceSignatures()`?

@liach 
- I am only looking at code added in JDK 9-current and do not plan on checking 
old code for now (in case there are questions on why certain methods weren't 
affected)
- I want generify-ing methods to be fine, so I am leaving 
`ClassSignature::superinterfaceSignatures()`. It will be changed eventually 
once the class goes out of Preview

> src/java.base/share/classes/java/lang/classfile/ClassSignature.java line 47:
> 
>> 45:  *
>> 46:  * @since 23
>> 47:  * */
> 
> Suggestion:
> 
>  */

good catch - will reply to your other questions later

> src/java.base/share/classes/java/lang/constant/MethodHandleDesc.java line 209:
> 
>> 207: 
>> 208: /**
>> 209:  * @since 21
> 
> Suggestion:
> 
>  * {@inheritDoc}
>  *
>  * @since 21

Will need to look more into what elements require `{@inheritDoc}`

-

PR Comment: https://git.openjdk.org/jdk/pull/18954#issuecomment-2077922679
PR Review Comment: https://git.openjdk.org/jdk/pull/18954#discussion_r1579841341
PR Review Comment: https://git.openjdk.org/jdk/pull/18954#discussion_r1579880986

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v5]

[Nizar Benalla]

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  - Not checking elements enclosed within a record, I doubt a record class will 
change after being created
  - Added a null check as `toString` can return an exception

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18934/files
  - new: https://git.openjdk.org/jdk/pull/18934/files/3f226ef9..48c87814

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18934=04
 - incr: https://webrevs.openjdk.org/?repo=jdk=18934=03-04

  Stats: 14 lines in 1 file changed: 12 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v4]

[Nizar Benalla]

On Thu, 2 May 2024 14:06:25 GMT, Hannes Wallnöfer  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional 
>> commit since the last revision:
>> 
>>   - Added some legacy modules that existed long before preview features 
>> (they were incubating)
>>   - Not checking elements enclosed withing a record
>>   - Only check if the file is readable using `Files.isReadable`
>>   - Dropped the use of `Files.exists` and `Files.isDirectory`
>>   - Use `--add-modules` option now to resolve certain modules
>
> test/jdk/tools/sincechecker/SinceChecker.java line 106:
> 
>> 104: public static void main(String[] args) throws Exception {
>> 105: if (args.length == 0) {
>> 106: throw new SkippedException("Test module not specified");
> 
> I don't think `SkippedException` is the right exception to throw here, since 
> invoking the method with a missing argument is probably a configuration error 
> that shouldn't be ignored. Maybe `IllegalArgumentException` or just 
> `RuntimeException`?

Fixed it, now throwing `IllegalArgumentException`.

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1590329254

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v4]

[Nizar Benalla]

On Thu, 2 May 2024 13:49:43 GMT, Hannes Wallnöfer  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional 
>> commit since the last revision:
>> 
>>   - Added some legacy modules that existed long before preview features 
>> (they were incubating)
>>   - Not checking elements enclosed withing a record
>>   - Only check if the file is readable using `Files.isReadable`
>>   - Dropped the use of `Files.exists` and `Files.isDirectory`
>>   - Use `--add-modules` option now to resolve certain modules
>
> test/jdk/tools/sincechecker/SinceChecker.java line 51:
> 
>> 49: 
>> 50: /*
>> 51: - This checker checks the values of the `@since` tag found in the 
>> documentation comment for an element against the release in which the 
>> element first appeared.
> 
> In addition to the long lines mentioned by Jon which make the comments hard 
> to read, I find it strange that every sentence is formatted as a list item 
> with a leading dash. I think it's ok when describing different parts/steps of 
> the algorithm, but at least the first sentence in the comment should not be a 
> list item IMO.

Fixed, thanks.

> test/jdk/tools/sincechecker/SinceChecker.java line 216:
> 
>> 214: srcZip = 
>> testJdk.getParent().resolve("images").resolve("jdk").resolve("lib").resolve("src.zip");
>> 215: }
>> 216: if (!Files.exists(srcZip) && !Files.isDirectory(srcZip)) {
> 
> This condition looks wrong. If `exists` returns false, it also implies that 
> `isDirectory` returns false. I think there's no need to check for a 
> (not-)directory here.

Fixed in 
[3f226ef](https://github.com/openjdk/jdk/pull/18934/commits/3f226ef9134b71a1b63b6562b8381be909c30343),
 I now only check if the file is readable.

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1590327624
PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1590327722

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v4]

[Nizar Benalla]

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  - Added some legacy modules that existed long before preview features (they 
were incubating)
  - Not checking elements enclosed withing a record
  - Only check if the file is readable using `Files.isReadable`
  - Dropped the use of `Files.exists` and `Files.isDirectory`
  - Use `--add-modules` option now to resolve certain modules

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18934/files
  - new: https://git.openjdk.org/jdk/pull/18934/files/5df2151e..3f226ef9

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18934=03
 - incr: https://webrevs.openjdk.org/?repo=jdk=18934=02-03

  Stats: 71 lines in 1 file changed: 32 ins; 8 del; 31 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v3]

[Nizar Benalla]

On Fri, 3 May 2024 00:25:16 GMT, Nizar Benalla  wrote:

>> This checker checks the values of the `@since` tag found in the 
>> documentation comment for an element against the release in which the 
>> element first appeared.
>> 
>> Real since value of an API element is computed as the oldest release in 
>> which the given API element was introduced. That is:
>> - for modules, classes and interfaces, the release in which the element with 
>> the given qualified name was introduced
>> - for constructors, the release in which the constructor with the given VM 
>> descriptor was introduced
>> - for methods and fields, the release in which the given method or field 
>> with the given VM descriptor became a member of its enclosing class or 
>> interface, whether direct or inherited
>> 
>> Effective since value of an API element is computed as follows:
>> - if the given element has a `@since` tag in its javadoc, it is used
>> - in all other cases, return the effective since value of the enclosing 
>> element
>> 
>> The since checker verifies that for every API element, the real since value 
>> and the effective since value are the same, and reports an error if they are 
>> not.
>> 
>> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
>> consistently going forward then the checker doesn't need to be updated with 
>> every release. The checker has explicit knowledge of preview elements that 
>> came before `JDK 14` because they weren't marked in a machine understandable 
>> way and preview elements that came before `JDK 17` that didn't have 
>> `@PreviewFeature`.
>> 
>> Important note : We only check code written since `JDK 9` as the releases 
>> used to determine the expected value of `@since` tags are taken from the 
>> historical data built into `javac` which only goes back that far
>> 
>> The intial comment at the beginning of `SinceChecker.java` holds more 
>> information into the program.
>> 
>> I already have filed issues and fixed some wrong tags like in #18640, 
>> #18032, #18030, #18055, #18373, #18954, #18972.
>
> Nizar Benalla has updated the pull request incrementally with one additional 
> commit since the last revision:
> 
>   mention packages in initial comment

test/jdk/tools/sincechecker/SinceChecker.java line 145:

> 143: private void processModuleElement(ModuleElement moduleElement, 
> String releaseVersion, JavacTask ct) {
> 144: for (ModuleElement.ExportsDirective ed : 
> ElementFilter.exportsIn(moduleElement.getDirectives())) {
> 145: processElement(moduleElement, moduleElement, ct.getTypes(), 
> releaseVersion);

For consideration for tomorrow: move this one line up - to map the module id 
even if the module has no export directives

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1588597273

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v3]

[Nizar Benalla]

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  mention packages in initial comment

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18934/files
  - new: https://git.openjdk.org/jdk/pull/18934/files/1bdb25d9..5df2151e

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18934=02
 - incr: https://webrevs.openjdk.org/?repo=jdk=18934=01-02

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module [v2]

[Nizar Benalla]

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  -Wrap lines at 80-100
  -Changes `e.getMessages` to `e`
  -`File.separator` to be platform indepedant
  -Added a newline character at the end of files
  -Rename `persistElement` to `processElement`
  -Now throwing IllegalArgumentException instead of SkippedException

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18934/files
  - new: https://git.openjdk.org/jdk/pull/18934/files/599477bf..1bdb25d9

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18934=01
 - incr: https://webrevs.openjdk.org/?repo=jdk=18934=00-01

  Stats: 51 lines in 3 files changed: 14 ins; 0 del; 37 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module

[Nizar Benalla]

On Wed, 1 May 2024 23:28:20 GMT, Nizar Benalla  wrote:

>> This checker checks the values of the `@since` tag found in the 
>> documentation comment for an element against the release in which the 
>> element first appeared.
>> 
>> Real since value of an API element is computed as the oldest release in 
>> which the given API element was introduced. That is:
>> - for modules, classes and interfaces, the release in which the element with 
>> the given qualified name was introduced
>> - for constructors, the release in which the constructor with the given VM 
>> descriptor was introduced
>> - for methods and fields, the release in which the given method or field 
>> with the given VM descriptor became a member of its enclosing class or 
>> interface, whether direct or inherited
>> 
>> Effective since value of an API element is computed as follows:
>> - if the given element has a `@since` tag in its javadoc, it is used
>> - in all other cases, return the effective since value of the enclosing 
>> element
>> 
>> The since checker verifies that for every API element, the real since value 
>> and the effective since value are the same, and reports an error if they are 
>> not.
>> 
>> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
>> consistently going forward then the checker doesn't need to be updated with 
>> every release. The checker has explicit knowledge of preview elements that 
>> came before `JDK 14` because they weren't marked in a machine understandable 
>> way and preview elements that came before `JDK 17` that didn't have 
>> `@PreviewFeature`.
>> 
>> Important note : We only check code written since `JDK 9` as the releases 
>> used to determine the expected value of `@since` tags are taken from the 
>> historical data built into `javac` which only goes back that far
>> 
>> The intial comment at the beginning of `SinceChecker.java` holds more 
>> information into the program.
>> 
>> I already have filed issues and fixed some wrong tags like in #18640, 
>> #18032, #18030, #18055, #18373, #18954, #18972.
>
> test/jdk/tools/sincechecker/SinceChecker.java line 300:
> 
>> 298: .getQualifiedName()
>> 299: .toString()
>> 300: .replaceAll("\\.", "/")
> 
> Note for readers: I will change this tomorrow to be more platform agnostic 
> using `File.separatorChar` instead

Replaced with `.replace(".", File.separator)`

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1588545737

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module

[Nizar Benalla]

On Wed, 24 Apr 2024 14:10:29 GMT, Nizar Benalla  wrote:

> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element against the release in which the element first 
> appeared.
> 
> Real since value of an API element is computed as the oldest release in which 
> the given API element was introduced. That is:
> - for modules, classes and interfaces, the release in which the element with 
> the given qualified name was introduced
> - for constructors, the release in which the constructor with the given VM 
> descriptor was introduced
> - for methods and fields, the release in which the given method or field with 
> the given VM descriptor became a member of its enclosing class or interface, 
> whether direct or inherited
> 
> Effective since value of an API element is computed as follows:
> - if the given element has a `@since` tag in its javadoc, it is used
> - in all other cases, return the effective since value of the enclosing 
> element
> 
> The since checker verifies that for every API element, the real since value 
> and the effective since value are the same, and reports an error if they are 
> not.
> 
> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
> consistently going forward then the checker doesn't need to be updated with 
> every release. The checker has explicit knowledge of preview elements that 
> came before `JDK 14` because they weren't marked in a machine understandable 
> way and preview elements that came before `JDK 17` that didn't have 
> `@PreviewFeature`.
> 
> Important note : We only check code written since `JDK 9` as the releases 
> used to determine the expected value of `@since` tags are taken from the 
> historical data built into `javac` which only goes back that far
> 
> The intial comment at the beginning of `SinceChecker.java` holds more 
> information into the program.
> 
> I already have filed issues and fixed some wrong tags like in #18640, #18032, 
> #18030, #18055, #18373, #18954, #18972.

test/jdk/tools/sincechecker/SinceChecker.java line 300:

> 298: .getQualifiedName()
> 299: .toString()
> 300: .replaceAll("\\.", "/")

Note for readers: I will change this tomorrow to be more platform agnostic 
using `File.separatorChar` instead

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1586919223

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module

[Nizar Benalla]

On Wed, 1 May 2024 20:53:08 GMT, Jonathan Gibbons  wrote:

>> This checker checks the values of the `@since` tag found in the 
>> documentation comment for an element against the release in which the 
>> element first appeared.
>> 
>> Real since value of an API element is computed as the oldest release in 
>> which the given API element was introduced. That is:
>> - for modules, classes and interfaces, the release in which the element with 
>> the given qualified name was introduced
>> - for constructors, the release in which the constructor with the given VM 
>> descriptor was introduced
>> - for methods and fields, the release in which the given method or field 
>> with the given VM descriptor became a member of its enclosing class or 
>> interface, whether direct or inherited
>> 
>> Effective since value of an API element is computed as follows:
>> - if the given element has a `@since` tag in its javadoc, it is used
>> - in all other cases, return the effective since value of the enclosing 
>> element
>> 
>> The since checker verifies that for every API element, the real since value 
>> and the effective since value are the same, and reports an error if they are 
>> not.
>> 
>> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
>> consistently going forward then the checker doesn't need to be updated with 
>> every release. The checker has explicit knowledge of preview elements that 
>> came before `JDK 14` because they weren't marked in a machine understandable 
>> way and preview elements that came before `JDK 17` that didn't have 
>> `@PreviewFeature`.
>> 
>> Important note : We only check code written since `JDK 9` as the releases 
>> used to determine the expected value of `@since` tags are taken from the 
>> historical data built into `javac` which only goes back that far
>> 
>> The intial comment at the beginning of `SinceChecker.java` holds more 
>> information into the program.
>> 
>> I already have filed issues and fixed some wrong tags like in #18640, 
>> #18032, #18030, #18055, #18373, #18954, #18972.
>
> test/jdk/tools/sincechecker/SinceChecker.java line 53:
> 
>> 51: - This checker checks the values of the `@since` tag found in the 
>> documentation comment for an element against the release in which the 
>> element first appeared.
>> 52: - The source code containing the documentation comments is read from 
>> `src.zip` in the release of JDK used to run the test.
>> 53: - The releases used to determine the expected value of `@since` tags are 
>> taken from the historical data built into `javac`.
> 
> (Minor, suggest wrapping lines somewhere between 80-100 characters long)

My idea was that, even when comparing files in a merge conflit, there wouldn't 
be problems here. 

But I will fix, some lines in the code are a bit long as well

> test/jdk/tools/sincechecker/SinceChecker.java line 72:
> 
>> 70: 
>> 71: Real since value of an API element is computed as the oldest release in 
>> which the given API element was introduced. That is:
>> 72: - for modules, classes and interfaces, the release in which the element 
>> with the given qualified name was introduced
> 
> What about packages?  packages should be in this list as well.

Small oversight, will fix

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1586840002
PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1586838616

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module

[Nizar Benalla]

On Fri, 26 Apr 2024 23:24:19 GMT, Jonathan Gibbons  wrote:

>> This checker checks the values of the `@since` tag found in the 
>> documentation comment for an element against the release in which the 
>> element first appeared.
>> 
>> Real since value of an API element is computed as the oldest release in 
>> which the given API element was introduced. That is:
>> - for modules, classes and interfaces, the release in which the element with 
>> the given qualified name was introduced
>> - for constructors, the release in which the constructor with the given VM 
>> descriptor was introduced
>> - for methods and fields, the release in which the given method or field 
>> with the given VM descriptor became a member of its enclosing class or 
>> interface, whether direct or inherited
>> 
>> Effective since value of an API element is computed as follows:
>> - if the given element has a `@since` tag in its javadoc, it is used
>> - in all other cases, return the effective since value of the enclosing 
>> element
>> 
>> The since checker verifies that for every API element, the real since value 
>> and the effective since value are the same, and reports an error if they are 
>> not.
>> 
>> Preview method are handled as per JEP 12, if `@PreviewFeature` is used 
>> consistently going forward then the checker doesn't need to be updated with 
>> every release. The checker has explicit knowledge of preview elements that 
>> came before `JDK 14` because they weren't marked in a machine understandable 
>> way and preview elements that came before `JDK 17` that didn't have 
>> `@PreviewFeature`.
>> 
>> Important note : We only check code written since `JDK 9` as the releases 
>> used to determine the expected value of `@since` tags are taken from the 
>> historical data built into `javac` which only goes back that far
>> 
>> The intial comment at the beginning of `SinceChecker.java` holds more 
>> information into the program.
>> 
>> I already have filed issues and fixed some wrong tags like in #18640, 
>> #18032, #18030, #18055, #18373, #18954, #18972.
>
> test/jdk/tools/sincechecker/SinceChecker.java line 423:
> 
>> 421: }
>> 422: 
>> 423: //these were preview in before the introduction of the 
>> @PreviewFeature
> 
> Just curious: where do you find this information?

Used a script to get all the elements with `@Deprecated(forRemoval=true, 
since=...)`, `@jdk.internal.preview`, `{@preview Associated with ` in their 
javadoc.
And then had to cross reference with a document that had all the ids

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18934#discussion_r1582899131

Re: RFR: 8331051: Add an `@since` checker test for `java.base` module

[Nizar Benalla]

On Wed, 24 Apr 2024 21:59:02 GMT, Jonathan Gibbons  wrote:

>> This checker checks the values of the `@since` tag found in the 
>> documentation comment for an element against the release in which the 
>> element first appeared.
>> 
>> Real since value of an API element is computed as the oldest release in 
>> which the given API element was introduced. That is:
>> - for modules, classes and interfaces, the release in which the element with 
>> the given qualified name was introduced
>> - for constructors, the release in which the constructor with the given VM 
>> descriptor was introduced
>> - for methods and fields, the release in which the given method or field 
>> with the given VM descriptor became a member of its enclosing class or 
>> interface, whether direct or inherited
>> 
>> Effective since value of an API element is computed as follows:
>> - if the given element has a `@since` tag in its javadoc, it is used
>> - in all other cases, return the effective since value of the enclosing 
>> element
>> 
>> The since checker verifies that for every API element, the real since value 
>> and the effective since value are the same, and reports an error if they are 
>> not.
>> 
>> Important note : We only check code written since `JDK 9` as the releases 
>> used to determine the expected value of `@since` tags are taken from the 
>> historical data built into `javac` which only goes back that far
>> 
>> The intial comment at the beginning of `SinceChecker.java` holds more 
>> information into the program.
>> 
>> I already have filed issues and fixed some wrong tags like in #18640, 
>> #18032, #18030, #18055, #18373, #18954, #18972.
>
> test/jdk/tools/sincechecker/SinceChecker.java line 49:
> 
>> 47: import java.util.regex.Matcher;
>> 48: import java.util.regex.Pattern;
>> 49: import java.util.stream.Collectors;
> 
> The imports are somewhat unordered.   I recommend the follooing order
> 
> * `java.*` imports first, 
> * then `javax.*` imports
> * then `com.sun.*` imports
> * and finally the `jtreg` import.
> 
> And, alphabetically sorted in each group.

Thanks, fixed in 32edb4d811978f87bd2f850c214191e8fc7b8c88

> test/jdk/tools/sincechecker/SinceChecker.java line 52:
> 
>> 50: 
>> 51: /*
>> 52: The `@since` checker works as a two-step process:
> 
> Insert an initial sentence or paragraph, such as the following:
> 
> 
> This checker checks the values of the `@since` tag found in the documentation 
> comment for an element
> against the release in which the element first appeared.
> 
> The source code containing the documentation comments is read from `src.zip` 
> in the release of
> JDK used to run the test.  The releases used to determine the expected value 
> of `@since` tags
> are taken from the historical data built into `javac`.

Added in  32edb4d811978f87bd2f850c214191e8fc7b8c88

> test/jdk/tools/sincechecker/SinceChecker.java line 79:
> 
>> 77: - When an element is still marked as preview, the `@since` should be the 
>> first JDK release where the element was added.
>> 78: - If the element is no longer marked as preview, the `@since` should be 
>> the first JDK release where it was no longer preview.
>> 79: 
> 
> Add a comment about need for special treatment of early preview features.

Thanks, added it

> test/jdk/tools/sincechecker/SinceChecker.java line 116:
> 
>> 114: }
>> 115: 
>> 116: private void processModuleRecord(ModuleElement moduleElement, 
>> String releaseVersion, JavacTask ct) {
> 
> for this method, and similarly named methods, the use of `Record` seems 
> confusing, if only because there do not seem to be any record classes being 
> processed or analyzed.   Consider dropping `Record` or changing it to 
> `Element`. Same for `analyzePackageRecord`, `analyzeClassRecord`.
> 
> Also, consider being consistent with `process` or analyze`.

Fixed in 32edb4d811978f87bd2f850c214191e8fc7b8c88

> test/jdk/tools/sincechecker/SinceChecker.java line 140:
> 
>> 138: persistElement(te.getEnclosingElement(), te, types, version);
>> 139: elements.getAllMembers(te).stream()
>> 140: .filter(element -> 
>> element.getModifiers().contains(Modifier.PUBLIC) || 
>> element.getModifiers().contains(Modifier.PROTECTED))
> 
> Consider writing and using a predicate method:
> 
> 
> boolean isDocumented(Element e) {
> var mods = e.getModifiers();
> return mods.contains(Modifier,.PUBLIC) || 
> mods.contains(Modifier.PROTECTED);
> }
> 
> 
> You could then use that method in the obvious way for the class 
> declaration(line 134) and in a lambda as follows:
> 
> .filter(this::isDocumented)

Added in 32edb4d811978f87bd2f850c214191e8fc7b8c88

> test/jdk/tools/sincechecker/SinceChecker.java line 143:
> 
>> 141: .filter(element -> element.getKind().isField()
>> 142: || element.getKind() == ElementKind.METHOD
>> 143: || element.getKind() == ElementKind.CONSTRUCTOR)
> 
> Consider writing and using another 

RFR: 8331051: Add an `@since` checker test for `java.base` module

[Nizar Benalla]

This checker checks the values of the `@since` tag found in the documentation 
comment for an element against the release in which the element first appeared.

Real since value of an API element is computed as the oldest release in which 
the given API element was introduced. That is:
- for modules, classes and interfaces, the release in which the element with 
the given qualified name was introduced
- for constructors, the release in which the constructor with the given VM 
descriptor was introduced
- for methods and fields, the release in which the given method or field with 
the given VM descriptor became a member of its enclosing class or interface, 
whether direct or inherited

Effective since value of an API element is computed as follows:
- if the given element has a `@since` tag in its javadoc, it is used
- in all other cases, return the effective since value of the enclosing element

The since checker verifies that for every API element, the real since value and 
the effective since value are the same, and reports an error if they are not.

Important note : We only check code written since `JDK 9` as the releases used 
to determine the expected value of `@since` tags are taken from the historical 
data built into `javac` which only goes back that far

The intial comment at the beginning of `SinceChecker.java` holds more 
information into the program.

I already have filed issues and fixed some wrong tags like in #18640, #18032, 
#18030, #18055, #18373, #18954, #18972.

-

Commit messages:
 - trivial change - extra parentheses
 - General improvements:
 - Add more details to the initial comment
 - remove unnecessary class - jtreg comment is enough to run the test
 - renamed files to give them more unique filenames - add more to the comment 
at the beginning of the file
 - first `@since` checker test of the JDK. For `java.base`

Changes: https://git.openjdk.org/jdk/pull/18934/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk=18934=00
  Issue: https://bugs.openjdk.org/browse/JDK-8331051
  Stats: 869 lines in 3 files changed: 867 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/18934.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18934/head:pull/18934

PR: https://git.openjdk.org/jdk/pull/18934

Re: RFR: 8326951: Missing `@since` tags [v7]

[Nizar Benalla]

> 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).
> 
> 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:

  deal with methods with different return types - added some spaces for 
readability

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18055/files
  - new: https://git.openjdk.org/jdk/pull/18055/files/390a21f9..670acaec

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18055=06
 - incr: https://webrevs.openjdk.org/?repo=jdk=18055=05-06

  Stats: 13 lines in 5 files changed: 12 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/18055.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18055/head:pull/18055

PR: https://git.openjdk.org/jdk/pull/18055

Re: RFR: 8326836: Incorrect `@since` tags for ClassSignature methods [v4]

[Nizar Benalla]

> # 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.

Nizar Benalla has updated the pull request with a new target base due to a 
merge or a rebase. The pull request now contains five commits:

 - Merge branch 'master' into fix-classfile-related-since-tag
   
   # Conflicts:
   #src/java.base/share/classes/java/lang/classfile/ClassFile.java
 - Update full name
 - update the copyright year to 2024
 - added @ since 23 to ClassFile.JAVA_23_VERSION, it now matches the @ since of 
the enclosing element
 - added @ since tag for of methods as their signature changed in jdk 23

-

Changes: https://git.openjdk.org/jdk/pull/18030/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk=18030=03
  Stats: 2 lines in 1 file changed: 2 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/18030.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18030/head:pull/18030

PR: https://git.openjdk.org/jdk/pull/18030

Re: RFR: 8326951: Missing `@since` tags [v6]

[Nizar Benalla]

> 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).
> 
> 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:

  removed change

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18055/files
  - new: https://git.openjdk.org/jdk/pull/18055/files/97f4c946..390a21f9

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18055=05
 - incr: https://webrevs.openjdk.org/?repo=jdk=18055=04-05

  Stats: 1 line in 1 file changed: 0 ins; 1 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/18055.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18055/head:pull/18055

PR: https://git.openjdk.org/jdk/pull/18055

Re: RFR: 8326951: Missing `@since` tags [v5]

[Nizar Benalla]

> 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).
> 
> 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:

  Update full name

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18055/files
  - new: https://git.openjdk.org/jdk/pull/18055/files/7d6e969e..97f4c946

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18055=04
 - incr: https://webrevs.openjdk.org/?repo=jdk=18055=03-04

  Stats: 0 lines in 0 files changed: 0 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/18055.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18055/head:pull/18055

PR: https://git.openjdk.org/jdk/pull/18055

Re: RFR: JDK-8326836 Incorrect `@since` tags for ClassSignature methods [v3]

[Nizar Benalla]

> # 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.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  Update full name

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18030/files
  - new: https://git.openjdk.org/jdk/pull/18030/files/8c0c7122..f73ce11a

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18030=02
 - incr: https://webrevs.openjdk.org/?repo=jdk=18030=01-02

  Stats: 0 lines in 0 files changed: 0 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/18030.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18030/head:pull/18030

PR: https://git.openjdk.org/jdk/pull/18030

Re: RFR: JDK-8326836 Incorrect `@since` Tags for ClassSignature methods [v2]

[Nizar Benalla]

On Tue, 9 Apr 2024 21:03:57 GMT, Pavel Rappo  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional 
>> commit since the last revision:
>> 
>>   update the copyright year to 2024
>
> Trivially, what's the reason you capitalised the word "tags" in the PR title 
> and the respective JBS issue?

@pavelrappo no real reason, that's just how I wrote it in my notes and it 
persisted until now.
I can change it here if you change it in the JBS

-

PR Comment: https://git.openjdk.org/jdk/pull/18030#issuecomment-2046204353

Re: RFR: JDK-8326836 Incorrect `@since` Tags for ClassSignature methods

[Nizar Benalla]

On Tue, 9 Apr 2024 20:50:18 GMT, Chen Liang  wrote:

>> `/covered`
>
> @nizarbenalla Why don't you add since tags for `superclassSignature` and 
> `superinterfaceSignatures` methods, both of which have their signatures 
> changed like the two `of` methods?

@liach good find! maybe I should look more carefully into members of Classes 
annotated with `@PreviewFeature`, I'll keep those for now. Until I can get my 
tool to programmatically pickup on them.

-

PR Comment: https://git.openjdk.org/jdk/pull/18030#issuecomment-2046133913

Integrated: JDK-8326853 Missing `@since` tags for Charset related methods added in Java 10

[Nizar Benalla]

On Tue, 27 Feb 2024 16:28:26 GMT, Nizar Benalla  wrote:

> # Issue
> - JDK-8326853 Incorrect `@since` Tags for Charset Related Methods Added in 
> JDK 10
> 
> I changed the `@since` tags to better accurately show when the methods and 
> constructors were introduced.

This pull request has now been integrated.

Changeset: 4d932d61
Author:Nizar Benalla 
Committer: Justin Lu 
URL:   
https://git.openjdk.org/jdk/commit/4d932d615c78f45516a4f136398e7610546065a6
Stats: 12 lines in 2 files changed: 10 ins; 0 del; 2 mod

8326853: Missing `@since` tags for Charset related methods added in Java 10

Reviewed-by: jlu, naoto

-

PR: https://git.openjdk.org/jdk/pull/18032

Re: RFR: JDK-8326853 Missing @ since tags for Charset related methods added in Java 10 [v8]

[Nizar Benalla]

On Thu, 21 Mar 2024 16:50:31 GMT, Justin Lu  wrote:

>> Thank you justin
>
> Hi @nizarbenalla , you can comment `/integrate` whenever you're ready, and we 
> can sponsor the change to have it integrated.

@justin-curtis-lu I realized there is a small issue with the commit message

8326853: Missing @since tags for Charset related methods added in Java 10

Reviewed-by: jlu, naoto

there is a github user with the username `@since` and he will be tagged in the 
commit message, so there should be a space here. I added a space in the PR title

-

PR Comment: https://git.openjdk.org/jdk/pull/18032#issuecomment-2015380584

Re: RFR: JDK-8326853 Missing @since tags for Charset related methods added in Java 10 [v9]

[Nizar Benalla]

On Wed, 20 Mar 2024 18:04:50 GMT, Nizar Benalla  wrote:

>> # Issue
>> - JDK-8326853 Incorrect `@since` Tags for Charset Related Methods Added in 
>> JDK 10
>> 
>> I changed the `@since` tags to better accurately show when the methods and 
>> constructors were introduced.
>
> Nizar Benalla has updated the pull request incrementally with two additional 
> commits since the last revision:
> 
>  - Update full name
>  - Update full name

I spent some time running some tests to learn the process.

-

PR Comment: https://git.openjdk.org/jdk/pull/18032#issuecomment-2014786660

Re: RFR: JDK-8326853 Missing @since tags for Charset related methods added in Java 10 [v9]

[Nizar Benalla]

> # Issue
> - JDK-8326853 Incorrect `@since` Tags for Charset Related Methods Added in 
> JDK 10
> 
> I changed the `@since` tags to better accurately show when the methods and 
> constructors were introduced.

Nizar Benalla has updated the pull request incrementally with two additional 
commits since the last revision:

 - Update full name
 - Update full name

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18032/files
  - new: https://git.openjdk.org/jdk/pull/18032/files/56968dcd..99f54fe2

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18032=08
 - incr: https://webrevs.openjdk.org/?repo=jdk=18032=07-08

  Stats: 0 lines in 0 files changed: 0 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/18032.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18032/head:pull/18032

PR: https://git.openjdk.org/jdk/pull/18032

Re: RFR: JDK-8326951 Missing @since Tags [v4]

[Nizar Benalla]

> 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).

Nizar Benalla has updated the pull request incrementally with three additional 
commits since the last revision:

 - update the copyright year to 2024
 - Revert "update the copyright year to 2024"
   
   This reverts commit 9ddd230dcf88bedade76a8e2804db6e120a200f8.
 - update the copyright year to 2024

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18055/files
  - new: https://git.openjdk.org/jdk/pull/18055/files/3cec63e9..7d6e969e

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18055=03
 - incr: https://webrevs.openjdk.org/?repo=jdk=18055=02-03

  Stats: 4 lines in 4 files changed: 0 ins; 0 del; 4 mod
  Patch: https://git.openjdk.org/jdk/pull/18055.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18055/head:pull/18055

PR: https://git.openjdk.org/jdk/pull/18055

Re: RFR: JDK-8326836 Incorrect @since Tags for ClassSignature methods [v2]

[Nizar Benalla]

> # 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.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  update the copyright year to 2024

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18030/files
  - new: https://git.openjdk.org/jdk/pull/18030/files/0d857db4..8c0c7122

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18030=01
 - incr: https://webrevs.openjdk.org/?repo=jdk=18030=00-01

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/18030.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18030/head:pull/18030

PR: https://git.openjdk.org/jdk/pull/18030

Re: RFR: JDK-8326853 Missing @since tags for Charset related methods added in Java 10 [v8]

[Nizar Benalla]

On Tue, 19 Mar 2024 17:02:36 GMT, Nizar Benalla  wrote:

>> # Issue
>> - JDK-8326853 Incorrect @\since Tags for Charset Related Methods Added in 
>> JDK 10
>> 
>> I changed the @\since tags to better accurately show when the methods and 
>> constructors were introduced.
>
> Nizar Benalla has updated the pull request incrementally with two additional 
> commits since the last revision:
> 
>  - update the copyright year to 2024
>  - Revert "update the latter years for the Oracle copyrights"
>
>This reverts commit 8bcc364fef8287c4d9aff7c60ed6fc0ea9155f64.

Thank you justin

-

PR Comment: https://git.openjdk.org/jdk/pull/18032#issuecomment-2007813492

Re: RFR: JDK-8326853 Missing @since tags for Charset related methods added in Java 10 [v7]

[Nizar Benalla]

On Tue, 19 Mar 2024 16:13:49 GMT, Justin Lu  wrote:

>> Nizar Benalla has updated the pull request incrementally with one additional 
>> commit since the last revision:
>> 
>>   update the latter years for the Oracle copyrights
>
> src/java.base/share/classes/java/nio/channels/Channels.java line 2:
> 
>> 1: /*
>> 2:  * Copyright (c) 2000, 2023, 2024, Oracle and/or its affiliates. All 
>> rights reserved.
> 
> Thanks for updating, but needs a little adjustment.
> 
> Rather than adding a third year, the format should be: "original year, 
> current year, Oracle ..."
> So in this case ->  `2000, 2024,`

Thanks for the explanation, I have fixed it.
I have a couple other similar PRs, is the policy to update the copyright year 
every time a file is changed? whether it's an addition or removal of code?

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18032#discussion_r1530770401

Re: RFR: JDK-8326853 Missing @since tags for Charset related methods added in Java 10 [v8]

[Nizar Benalla]

> # Issue
> - JDK-8326853 Incorrect @\since Tags for Charset Related Methods Added in JDK 
> 10
> 
> I changed the @\since tags to better accurately show when the methods and 
> constructors were introduced.

Nizar Benalla has updated the pull request incrementally with two additional 
commits since the last revision:

 - update the copyright year to 2024
 - Revert "update the latter years for the Oracle copyrights"
   
   This reverts commit 8bcc364fef8287c4d9aff7c60ed6fc0ea9155f64.

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18032/files
  - new: https://git.openjdk.org/jdk/pull/18032/files/8bcc364f..56968dcd

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18032=07
 - incr: https://webrevs.openjdk.org/?repo=jdk=18032=06-07

  Stats: 2 lines in 2 files changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/18032.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18032/head:pull/18032

PR: https://git.openjdk.org/jdk/pull/18032

Re: RFR: JDK-8326951 Missing @since Tags [v3]

[Nizar Benalla]

> 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).

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  added since tag

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18055/files
  - new: https://git.openjdk.org/jdk/pull/18055/files/ba97724d..3cec63e9

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18055=02
 - incr: https://webrevs.openjdk.org/?repo=jdk=18055=01-02

  Stats: 1 line in 1 file changed: 1 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/18055.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18055/head:pull/18055

PR: https://git.openjdk.org/jdk/pull/18055

Re: RFR: JDK-8326951 Missing @since Tags [v2]

[Nizar Benalla]

> 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).

Nizar Benalla has updated the pull request incrementally with three additional 
commits since the last revision:

 - Revert "fix rest of private/public since tags"
   
   This reverts commit 2c04a9d8e773616b7b6239335d4e5eb955944ad1.
 - Revert "removed unnecessary @ since tags"
   
   This reverts commit 5da3f0d83d19393eeb3a9da68aac40dd999de660.
 - removed unnecessary @ since tags

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18055/files
  - new: https://git.openjdk.org/jdk/pull/18055/files/2c04a9d8..ba97724d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18055=01
 - incr: https://webrevs.openjdk.org/?repo=jdk=18055=00-01

  Stats: 10 lines in 10 files changed: 8 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/18055.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18055/head:pull/18055

PR: https://git.openjdk.org/jdk/pull/18055

Re: RFR: JDK-8326951 Missing @since Tags [v2]

[Nizar Benalla]

On Sat, 16 Mar 2024 00:20:51 GMT, Jaikiran Pai  wrote:

>> Nizar Benalla has updated the pull request incrementally with three 
>> additional commits since the last revision:
>> 
>>  - Revert "fix rest of private/public since tags"
>>
>>This reverts commit 2c04a9d8e773616b7b6239335d4e5eb955944ad1.
>>  - Revert "removed unnecessary @ since tags"
>>
>>This reverts commit 5da3f0d83d19393eeb3a9da68aac40dd999de660.
>>  - removed unnecessary @ since tags
>
> src/java.base/share/classes/javax/crypto/interfaces/DHPublicKey.java line 68:
> 
>> 66:  *
>> 67:  * @return {@inheritDoc java.security.AsymmetricKey}
>> 68:  * @since 22
> 
> Hello Nizar, are the removal of `@since` in this PR intentional? I haven't 
> checked all of them, but this specific removal appears incorrect, since this 
> method was indeed introduced in Java 22 as part of 
> https://bugs.openjdk.org/browse/JDK-8318096.

Hello Jaikiran,
in jdk21 DHPPublicKey did have a 
[getParams()](https://github.com/openjdk/jdk21/blob/890adb6410dab4606a4f26a942aed02fb2f55387/src/java.base/share/classes/com/sun/crypto/provider/DHPublicKey.java#L244)
 method, so it is not new in jdk 22. It also existed [before 
that](https://github.com/openjdk/jdk11/blob/37115c8ea4aff13a8148ee2b8832b20888a5d880/src/java.base/share/classes/com/sun/crypto/provider/DHPublicKey.java#L252)

If you haven't looked at the other cases, I was about to group the changes 
related to the Key interfaces in a separate PR if that's fine. let me know what 
you think

-

PR Review Comment: https://git.openjdk.org/jdk/pull/18055#discussion_r1527393223

Re: RFR: JDK-8326853 Missing @since tags for Charset related methods added in Java 10 [v6]

[Nizar Benalla]

On Mon, 18 Mar 2024 12:44:46 GMT, Nizar Benalla  wrote:

>> # Issue
>> - JDK-8326853 Incorrect @\since Tags for Charset Related Methods Added in 
>> JDK 10
>> 
>> I changed the @\since tags to better accurately show when the methods and 
>> constructors were introduced.
>
> Nizar Benalla has updated the pull request incrementally with one additional 
> commit since the last revision:
> 
>   added terminal new line

I have updated them

-

PR Comment: https://git.openjdk.org/jdk/pull/18032#issuecomment-2006812767

Re: RFR: JDK-8326853 Missing @since tags for Charset related methods added in Java 10 [v7]

[Nizar Benalla]

> # Issue
> - JDK-8326853 Incorrect @\since Tags for Charset Related Methods Added in JDK 
> 10
> 
> I changed the @\since tags to better accurately show when the methods and 
> constructors were introduced.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  update the latter years for the Oracle copyrights

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18032/files
  - new: https://git.openjdk.org/jdk/pull/18032/files/abc5a6ab..8bcc364f

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18032=06
 - incr: https://webrevs.openjdk.org/?repo=jdk=18032=05-06

  Stats: 2 lines in 2 files changed: 0 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/18032.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18032/head:pull/18032

PR: https://git.openjdk.org/jdk/pull/18032

Re: RFR: JDK-8326853 Missing @since tags for Charset related methods added in Java 10 [v6]

[Nizar Benalla]

> # Issue
> - JDK-8326853 Incorrect @\since Tags for Charset Related Methods Added in JDK 
> 10
> 
> I changed the @\since tags to better accurately show when the methods and 
> constructors were introduced.

Nizar Benalla has updated the pull request incrementally with one additional 
commit since the last revision:

  added terminal new line

-

Changes:
  - all: https://git.openjdk.org/jdk/pull/18032/files
  - new: https://git.openjdk.org/jdk/pull/18032/files/4822dede..abc5a6ab

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk=18032=05
 - incr: https://webrevs.openjdk.org/?repo=jdk=18032=04-05

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/18032.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18032/head:pull/18032

PR: https://git.openjdk.org/jdk/pull/18032