From jjg at openjdk.org  Thu Feb  1 00:22:10 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 1 Feb 2024 00:22:10 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <9udnoUCtCVEEO3rIQypPb3f14bMp6wVRRO4x0yNKZpw=.b1245fbf-e2eb-44c1-9b44-76ccbefe200f@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <zrqu3x52AXuB6DBs1kg66rC0arBB3MUFFokkL8CIF_k=.7935ef71-4d3c-4246-bf5c-afe5fd5fb625@github.com>
 <UbOd3C2ZrB35hFrkossEp7LIUWFk9dpBZh6v8IS0HeA=.84a2e253-8eb2-40fc-8256-c38a8a4e4399@github.com>
 <t12_cx8L88XOIB668UOHrnt7TPsyJiVC48ic7BribrI=.4b9996e0-a930-48cb-a8f4-6f2f7e0d717a@github.com>
 <9udnoUCtCVEEO3rIQypPb3f14bMp6wVRRO4x0yNKZpw=.b1245fbf-e2eb-44c1-9b44-76ccbefe200f@github.com>
Message-ID: <xdbBz5jNKMyTzPYYjGZ993AJ53U6DQm-LZHahZLLKfc=.0de14de4-08fe-435b-a173-6d7c5518d21b@github.com>

On Wed, 31 Jan 2024 23:09:57 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Yes, you need to escape `[` and `]` within the label of any Markdown reference link, by preceding each with backslash.   (Remember, the label is the string used to find the URL for the link; not the displayed text of the link).
>> That's a CommonMark feature independent of this work.
>> 
>> While we could change that `replace` call into two separate ones, in reference signatures they always appear together as a pair, and can be replaced together.   We need to remove the escape characters in the generated URL so that the signature is a standard signature with unescaped `[]`
>> 
>> For fun/demo, try the following:
>> 
>> 
>> /// First sentence.
>> /// * Link 0 to [java.lang.Object]
>> /// * Link 1a to [Arrays-equals][java.util.Arrays#equals(Object[],Object[])]
>> /// * Link 1b to [Arrays-equals][java.util.Arrays#equals(Object[],Object[])]
>> /// * Link 2a to [java.util.Arrays#equals(Object[],Object[])]
>> /// * Link 2b to [java.util.Arrays#equals(Object[],Object[])]
>> public class C { }
>> 
>> 
>> Link 1a and 2a end up as unprocessed "literal" text (because the `[]` were not escaped.)  That is, they are not even recognized by the CommonMark parser as reference links.  Link 1b and 2b get processed as links, as expected.
>> 
>> FWIW, this issue with needing to escape `[]` pairs is specifically mentioned in the JEP as an inescapable (sic) limitation.
>
> I'll add a test case.

Done

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473644884

From jjg at openjdk.org  Thu Feb  1 00:38:11 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 1 Feb 2024 00:38:11 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
In-Reply-To: <mYUhOCbMeG5EtIygSHpOAYyVun1Q8YcA3GucL1z1qcE=.33866d2d-c942-49c8-bc48-91df3021981d@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0mlIFIZ2ec8oE2zlmKxoMwp59dBgOdUQs-vzTLnU7hI=.15fa2827-8c87-415b-ab74-0e42b45a5cf7@github.com>
 <vUJ0cyyLa08AppwEQ4Dzu_JQlkJWo9oJUhUHUbSnK_M=.e2172756-ad2e-411c-8961-d55b756551a9@github.com>
 <mYUhOCbMeG5EtIygSHpOAYyVun1Q8YcA3GucL1z1qcE=.33866d2d-c942-49c8-bc48-91df3021981d@github.com>
Message-ID: <vB0WjtcVwLcWakp_A0EpAX8XUtWVnPAyqUWN4q3mM7k=.4be9cb20-e6b7-4e13-8e1d-1da8277ca531@github.com>

On Tue, 30 Jan 2024 00:39:43 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 259:
>> 
>>> 257:         LineKind lineKind = textKind == DocTree.Kind.MARKDOWN ? peekLineKind() : null;
>>> 258: 
>>> 259:         if (DEBUG) System.err.println("starting content " + showPos(bp) + " " + newline);
>> 
>> Debug output is useful. I wonder if we should consider https://openjdk.org/jeps/264.
>
> My oops for leaving the code in, or at least not cleaning it up more.

yeah, the debug code was pretty obsolete; I removed all except the generally useful method to show the text surrounding a position in the input buffer.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473654007

From jjg at openjdk.org  Thu Feb  1 01:06:15 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 1 Feb 2024 01:06:15 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <vVADmiqaRr_Vr4KBZLGZ84p7XFHjOnSu3YXHxT3R8ds=.9e9ac84c-d6e8-4f61-9a1f-90f33dbd4c07@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <vVADmiqaRr_Vr4KBZLGZ84p7XFHjOnSu3YXHxT3R8ds=.9e9ac84c-d6e8-4f61-9a1f-90f33dbd4c07@github.com>
Message-ID: <_gXMWS65YgIw407hA80Xje-d4ws86vbtNqJuv2AUuH0=.9a143695-1fb0-4862-b07e-9ae720fe4029@github.com>

On Fri, 26 Jan 2024 16:33:08 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains eight commits:
>> 
>>  - Merge with upstream/master
>>  - Merge with upstream/master
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Address review comments
>>  - Fix whitespace
>>  - Improve handling of embedded inline taglets
>>  - Customize support for Markdown headings
>>  - JDK-8298405: Support Markdown in Documentation Comments
>
> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 668:
> 
>> 666:          * U+FFFC characters that were found in the original document.
>> 667:          */
>> 668:         Iterator<?> replaceIter;
> 
> Suggestion:
> 
>         final Iterator<?> replaceIter;

actually, `private final` ... done

> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 732:
> 
>> 730:                 offsets.add(m.end());
>> 731:             }
>> 732:             sourceLineOffsets = offsets.stream().mapToInt(Integer::intValue).toArray();
> 
> Here's an alternative, which you might find better (or not):
> Suggestion:
> 
>             sourceLineOffsets = Stream.concat(Stream.of(0), lineBreak.matcher(source).results()
>                             .map(MatchResult::end)).mapToInt(Integer::intValue).toArray();

done

it's borderline (to me) that it's worthwhile but given that my original code used streams to create the final array, it sort-of makes sense to go "all in".

> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 831:
> 
>> 829:         /**
>> 830:          * {@return the position in the original comment for a position in {@code source},
>> 831:          * using {@link #replaceAdjustPos}}.
> 
> Suggestion:
> 
>          * using {@link #replaceAdjustPos}}

done

> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 939:
> 
>> 937: 
>> 938:         /**
>> 939:          * Flush any text in the {@code text} buffer, by creating a new
> 
> Suggestion:
> 
>          * Flushes any text in the {@code text} buffer, by creating a new

done

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473668136
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473670108
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473668952
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1473668548

From jjg at openjdk.org  Thu Feb  1 01:12:52 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 1 Feb 2024 01:12:52 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v15]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <PzTVKwDfSLmEqm4kFvgUO_yBBCj5aWSzsm4acfFE8Bc=.fa82e41e-6c65-4fde-b99d-48f9ac5561fd@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with four additional commits since the last revision:

 - MarkdownTransformer: tweak doc comments
 - MarkdownTransformer: change `Lower.replaceIter` to be `private final`
 - MarkdownTransformer: use suggested text for using streams
 - remove obsolete debug code

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/586daddf..54d40b20

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=14
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=13-14

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

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

From darcy at openjdk.org  Thu Feb  1 05:18:09 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Thu, 1 Feb 2024 05:18:09 GMT
Subject: RFR: JDK-8325078: Better escaping of single and double quotes in javac
 annotation toString() results
Message-ID: <Zb7QDFmHkdEVLXkgqXxxlsDskveHPkw0fQBIPe6X9hY=.044b0f7d-7fb4-4e64-9c5c-ab0dd737d046@github.com>

The javac version of https://github.com/openjdk/jdk/pull/17664

"A double quote character doesn't need to be escaped when it is a char literal and single quote character doesn't need to be escaped when it is in a string. This change updates the toString() output of annotations to account for the different escaping requirements of strings and characters."

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

Commit messages:
 - Update regressiont test for changed string output.
 - JDK-8325078: Better escaping of single and double quotes in javac annotation toString() results

Changes: https://git.openjdk.org/jdk/pull/17665/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17665&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325078
  Stats: 21 lines in 4 files changed: 6 ins; 0 del; 15 mod
  Patch: https://git.openjdk.org/jdk/pull/17665.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17665/head:pull/17665

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

From ihse at openjdk.org  Thu Feb  1 12:02:12 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Thu, 1 Feb 2024 12:02:12 GMT
Subject: RFR: 8325109: Sort method modifiers in canonical order
Message-ID: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>

This is a follow-up on [JDK-8324053](https://bugs.openjdk.org/browse/JDK-8324053). I have run the bin/blessed-modifier-order.sh on the entire code base, and manually checked the result. I have reverted all but these trivial and uncontroversial changes.

Almost all of these are about moving `static` to its proper position; a few do not involve `static` but instead puts `final` or `abstract` in the correct place.

I have deliberately stayed away from `default` in this PR, since they should probably get a more thorough treatment, see https://github.com/openjdk/jdk/pull/17468#pullrequestreview-1829238473.

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

Commit messages:
 - 8325109: Sort method modifiers in canonical order

Changes: https://git.openjdk.org/jdk/pull/17670/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17670&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325109
  Stats: 61 lines in 39 files changed: 0 ins; 0 del; 61 mod
  Patch: https://git.openjdk.org/jdk/pull/17670.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17670/head:pull/17670

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

From dfuchs at openjdk.org  Thu Feb  1 13:43:00 2024
From: dfuchs at openjdk.org (Daniel Fuchs)
Date: Thu, 1 Feb 2024 13:43:00 GMT
Subject: RFR: 8325109: Sort method modifiers in canonical order
In-Reply-To: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
References: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
Message-ID: <8VqjbOBjkNCr7PmXABZ1xmQqvF0jidmGyIMNUdKQDww=.8ffdc2ac-023f-4b79-ac5a-9ef541af68a7@github.com>

On Thu, 1 Feb 2024 11:57:04 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is a follow-up on [JDK-8324053](https://bugs.openjdk.org/browse/JDK-8324053). I have run the bin/blessed-modifier-order.sh on the entire code base, and manually checked the result. I have reverted all but these trivial and uncontroversial changes.
> 
> Almost all of these are about moving `static` to its proper position; a few do not involve `static` but instead puts `final` or `abstract` in the correct place.
> 
> I have deliberately stayed away from `default` in this PR, since they should probably get a more thorough treatment, see https://github.com/openjdk/jdk/pull/17468#pullrequestreview-1829238473.

Changes to IPAdressUtil look fine. I eyeballed the rest and didn't spot any issue.

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

PR Review: https://git.openjdk.org/jdk/pull/17670#pullrequestreview-1856519410

From duke at openjdk.org  Thu Feb  1 13:53:34 2024
From: duke at openjdk.org (ExE Boss)
Date: Thu, 1 Feb 2024 13:53:34 GMT
Subject: RFR: 8303374: Implement JEP 455: Primitive Types in Patterns,
 instanceof, and switch (Preview) [v57]
In-Reply-To: <M06P1ym-MnvjB2Z-v9hfGFjXV2RbBeIqg0EMzWr9LNU=.b363d892-f5da-42dc-b53d-7a9a0ed1689e@github.com>
References: <4GCkSMggtYI8KnM-kELHez3Nd42WIrfd6jOF1bbK5PA=.12aec6f3-669b-4675-ad34-ffe28cb23459@github.com>
 <M06P1ym-MnvjB2Z-v9hfGFjXV2RbBeIqg0EMzWr9LNU=.b363d892-f5da-42dc-b53d-7a9a0ed1689e@github.com>
Message-ID: <CLbfoAR5kAC4Pb1kwSn_aHkdrPSdvk9EjO96nov1sTY=.b15cd4ce-03e4-46d5-b85f-d17f0bb9f174@github.com>

On Wed, 31 Jan 2024 10:03:23 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

>> This is the proposed patch for Primitive types in patterns, instanceof, and switch (Preview).
>> 
>> Draft spec here: https://cr.openjdk.org/~abimpoudis/instanceof/latest/
>
> Aggelos Biboudis has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 78 commits:
> 
>  - Merge branch 'master' into primitive-patterns
>  - Update summary in ExactnessConversionsSupportTest
>  - Address review by Jan
>  - Remove redundant null check  and introduce a const boolean for unconditionally exact pairs
>  - Small fix in Javadoc
>  - Tidy up Javadoc of Lower.visitTypeTest
>  - Tidy up Javadoc of IllegalArgumentException in typeSwitch
>  - Improve readability in SwitchBootstraps
>  - Update year
>  - Cleanup redundant clone
>  - ... and 68 more: https://git.openjdk.org/jdk/compare/ec56c72b...f68748b1

src/java.base/share/classes/java/lang/runtime/SwitchBootstraps.java line 721:

> 719:             typePairToName.put(new TypePairs(double.class, long.class),   "isDoubleToLongExact");
> 720:             typePairToName.put(new TypePairs(double.class, float.class),  "isDoubleToFloatExact");
> 721:             return typePairToName;

This?should?return an?immutable?map, so that `TypePairs`?lookups can?be?treated as?constant:
Suggestion:

            return Map.copyOf(typePairToName);

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

PR Review Comment: https://git.openjdk.org/jdk/pull/15638#discussion_r1474502668

From aivanov at openjdk.org  Thu Feb  1 14:44:02 2024
From: aivanov at openjdk.org (Alexey Ivanov)
Date: Thu, 1 Feb 2024 14:44:02 GMT
Subject: RFR: 8325109: Sort method modifiers in canonical order
In-Reply-To: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
References: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
Message-ID: <uj6X0EkJ7Id9yviBJdcfrEINU46lON8sZkDN2xF5OB4=.bd123c3f-d79e-46e8-8a5f-241b4a50390e@github.com>

On Thu, 1 Feb 2024 11:57:04 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is a follow-up on [JDK-8324053](https://bugs.openjdk.org/browse/JDK-8324053). I have run the bin/blessed-modifier-order.sh on the entire code base, and manually checked the result. I have reverted all but these trivial and uncontroversial changes.
> 
> Almost all of these are about moving `static` to its proper position; a few do not involve `static` but instead puts `final` or `abstract` in the correct place.
> 
> I have deliberately stayed away from `default` in this PR, since they should probably get a more thorough treatment, see https://github.com/openjdk/jdk/pull/17468#pullrequestreview-1829238473.

Looks good to me.

I looked through all the changes.

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

Marked as reviewed by aivanov (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17670#pullrequestreview-1856683827

From rriggs at openjdk.org  Thu Feb  1 17:02:01 2024
From: rriggs at openjdk.org (Roger Riggs)
Date: Thu, 1 Feb 2024 17:02:01 GMT
Subject: RFR: 8325109: Sort method modifiers in canonical order
In-Reply-To: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
References: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
Message-ID: <E28xCC3i0n7CBNbkZDdvbd8kDHlZdAfF0o_OrhT88ng=.79424bfe-ea1d-4015-a15b-de98635b7d05@github.com>

On Thu, 1 Feb 2024 11:57:04 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is a follow-up on [JDK-8324053](https://bugs.openjdk.org/browse/JDK-8324053). I have run the bin/blessed-modifier-order.sh on the entire code base, and manually checked the result. I have reverted all but these trivial and uncontroversial changes.
> 
> Almost all of these are about moving `static` to its proper position; a few do not involve `static` but instead puts `final` or `abstract` in the correct place.
> 
> I have deliberately stayed away from `default` in this PR, since they should probably get a more thorough treatment, see https://github.com/openjdk/jdk/pull/17468#pullrequestreview-1829238473.

lgtm; all look good

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

Marked as reviewed by rriggs (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17670#pullrequestreview-1857031136

From darcy at openjdk.org  Thu Feb  1 17:24:01 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Thu, 1 Feb 2024 17:24:01 GMT
Subject: RFR: 8325109: Sort method modifiers in canonical order
In-Reply-To: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
References: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
Message-ID: <uY6CoY9NwuiOEmWivsV3k5OEdoBB4ETOCiK2fo0mDLU=.7ec4beb3-66b9-4076-8aa6-2caa221023bf@github.com>

On Thu, 1 Feb 2024 11:57:04 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is a follow-up on [JDK-8324053](https://bugs.openjdk.org/browse/JDK-8324053). I have run the bin/blessed-modifier-order.sh on the entire code base, and manually checked the result. I have reverted all but these trivial and uncontroversial changes.
> 
> Almost all of these are about moving `static` to its proper position; a few do not involve `static` but instead puts `final` or `abstract` in the correct place.
> 
> I have deliberately stayed away from `default` in this PR, since they should probably get a more thorough treatment, see https://github.com/openjdk/jdk/pull/17468#pullrequestreview-1829238473.

Looks fine; I just suggest double-checking on the current maintenance procedures for the java.util.concurrent code.

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

Marked as reviewed by darcy (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17670#pullrequestreview-1857088376

From jlahoda at openjdk.org  Thu Feb  1 17:56:02 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Thu, 1 Feb 2024 17:56:02 GMT
Subject: RFR: JDK-8325078: Better escaping of single and double quotes in
 javac annotation toString() results
In-Reply-To: <Zb7QDFmHkdEVLXkgqXxxlsDskveHPkw0fQBIPe6X9hY=.044b0f7d-7fb4-4e64-9c5c-ab0dd737d046@github.com>
References: <Zb7QDFmHkdEVLXkgqXxxlsDskveHPkw0fQBIPe6X9hY=.044b0f7d-7fb4-4e64-9c5c-ab0dd737d046@github.com>
Message-ID: <GfjJ3NYw0ccqHqqF20RzI1rXnbyvswAcYV-NU77Q5kY=.26976a21-5e35-4d32-aaae-4348fc66555d@github.com>

On Thu, 1 Feb 2024 02:40:29 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> The javac version of https://github.com/openjdk/jdk/pull/17664
> 
> "A double quote character doesn't need to be escaped when it is a char literal and single quote character doesn't need to be escaped when it is in a string. This change updates the toString() output of annotations to account for the different escaping requirements of strings and characters."

Looks OK to me.

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

Marked as reviewed by jlahoda (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17665#pullrequestreview-1857163477

From java-ml at ialistannen.de  Thu Feb  1 18:56:27 2024
From: java-ml at ialistannen.de (I Al Istannen)
Date: Thu, 1 Feb 2024 19:56:27 +0100
Subject: Allowed names for receiver parameters
Message-ID: <9b9832ee-bb49-48e0-b9bd-c72e3a22234b@ialistannen.de>

Hey,

we recently looked at the handling of receiver parameters in Java and 
did not quite understand some of the spec. As far as we can tell, Javac 
and the spec do not quite agree on the allowed names, which can be seen 
in the example[0].
The first comment before the constructor and method quotes JLS ?8.4, the 
rest explain why we think the names should be rejected by Javac. Does 
Javac accept more than specified here or did we miss something?

IntelliJ accepts the code and models it in the PSI tree as a 
"PsiThisExpression", but ignores it completely in the documentation popup.
JDT seems to directly normalise the parameter name to "this", 
unqualifying it in the process.

Have a nice day :)
I Al Istannen

[0] Example:
```java
public class Outer {
 ??? public class Middle {
 ??????? class Inner {
 ??????????? //? In an inner class's constructor [..] and the name of the
 ??????????? //? receiver parameter must be "Identifier.this" where 
"Identifier"
 ??????????? //? is the simple name of the class or interface which is the
 ??????????? //? immediately enclosing type declaration of the inner class;
 ??????????? //? otherwise, a compile-time error occurs
 ??????????? public Inner(Middle Middle.this) {}
 ??????????? // here "Identifier" is "Outer.Middle", which is *not* the 
simple
 ??????????? // name, but still accepted
 ??????????? public Inner(Outer.Middle Outer.Middle.this, int a) {}


 ??????????? // In an instance method, the type of the receiver 
parameter must
 ??????????? // be the class or interface in which the method is 
declared, and
 ??????????? // the name of the receiver parameter must be 'this'; 
otherwise, a
 ??????????? // compile-time error occurs.
 ??????????? public void inner1(Inner this) {}

 ??????????? // Here the name is "Outer.Middle.Inner.this" and not 
"this", but
 ??????????? // still accepted
 ??????????? public void inner2(Inner Outer.Middle.Inner.this) {}
 ??????????? // Here the name is "Middle.Inner.this" and not "this", but 
still
 ??????????? // accepted
 ??????????? public void inner3(Inner Middle.Inner.this) {}
 ??????????? // Here the name is "Inner.this" and not "this", but still 
accepted
 ??????????? public void inner4(Inner Inner.this) {}
 ??????? }
 ??? }
}
```


From darcy at openjdk.org  Thu Feb  1 20:23:05 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Thu, 1 Feb 2024 20:23:05 GMT
Subject: Integrated: JDK-8325078: Better escaping of single and double quotes
 in javac annotation toString() results
In-Reply-To: <Zb7QDFmHkdEVLXkgqXxxlsDskveHPkw0fQBIPe6X9hY=.044b0f7d-7fb4-4e64-9c5c-ab0dd737d046@github.com>
References: <Zb7QDFmHkdEVLXkgqXxxlsDskveHPkw0fQBIPe6X9hY=.044b0f7d-7fb4-4e64-9c5c-ab0dd737d046@github.com>
Message-ID: <7WiXBBFrikTgEyMKC0XoK8kfJv-FzdpiDpYXLmDWBNo=.3750f4f0-3b1a-44b0-aa05-ee099be9dd90@github.com>

On Thu, 1 Feb 2024 02:40:29 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> The javac version of https://github.com/openjdk/jdk/pull/17664
> 
> "A double quote character doesn't need to be escaped when it is a char literal and single quote character doesn't need to be escaped when it is in a string. This change updates the toString() output of annotations to account for the different escaping requirements of strings and characters."

This pull request has now been integrated.

Changeset: 144a08ee
Author:    Joe Darcy <darcy at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/144a08ee5092980859379c7664c8036eec1e264d
Stats:     21 lines in 4 files changed: 6 ins; 0 del; 15 mod

8325078: Better escaping of single and double quotes in javac annotation toString() results

Reviewed-by: jlahoda

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

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

From jjg at openjdk.org  Thu Feb  1 21:44:26 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 1 Feb 2024 21:44:26 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v16]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <qS3B2GKOrKecN9jB0n07XU5EiDfPkhZh0nWqM8sMK5w=.cb6211a6-d67d-4ece-aa5e-c54ecbb3819f@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  add info about provenance of `jdk.internal.md` module

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/54d40b20..b02d4675

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=15
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=14-15

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

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

From jjg at openjdk.org  Thu Feb  1 21:44:26 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 1 Feb 2024 21:44:26 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v15]
In-Reply-To: <PzTVKwDfSLmEqm4kFvgUO_yBBCj5aWSzsm4acfFE8Bc=.fa82e41e-6c65-4fde-b99d-48f9ac5561fd@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <PzTVKwDfSLmEqm4kFvgUO_yBBCj5aWSzsm4acfFE8Bc=.fa82e41e-6c65-4fde-b99d-48f9ac5561fd@github.com>
Message-ID: <SUHUUp0kmXRTlAB-q1G-vRJotgWqCAr4Zixl3CxdzLE=.79a709f8-77ed-46f3-9fb6-ed544ed721d8@github.com>

On Thu, 1 Feb 2024 01:12:52 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with four additional commits since the last revision:
> 
>  - MarkdownTransformer: tweak doc comments
>  - MarkdownTransformer: change `Lower.replaceIter` to be `private final`
>  - MarkdownTransformer: use suggested text for using streams
>  - remove obsolete debug code

> On CommonMark.
> 
> * `jdk.internal.md` contains 133 files, the vast majority of which are from commonmark-java 0.21.0. According to https://github.com/commonmark/commonmark-java/releases 0.21.0 is the latest/current release; good.
>   Questions:
>   
>   * Did we take the tagged commit or mainline at some point after the tagged commit? If it's the latter, we need to take the tagged version.
>   * What's the difference between those commonmark-java files in this PR and official commonmark-java? In other words, how do we adapt them? It would be nice to have a description of the procedure or a script to update those files.
> * `jdk.internal.md` exports packages to `jdk.jshell`. A question for @lahodaj, who maintains `jdk.jshell`: when do we need to create a new PR similar to that withdrawn [8299902: Support for MarkDown javadoc in JShell?#11936](https://github.com/openjdk/jdk/pull/11936)?

Added comment to `jdk.internal.md` `module-info.java`

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

PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-1922295907

From jjg at openjdk.org  Thu Feb  1 22:27:14 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 1 Feb 2024 22:27:14 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v16]
In-Reply-To: <h1baGO4_88DIboIvFWEK-QfaeWbjLrkuwFV5Xz1iOIw=.a878dcce-b168-4114-a842-a704ddb0caf3@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <HZQiJKB0i4jqcVhsKgdzF3_q0vXLC2IIEi6JeZpdq5w=.5cc0180c-8db2-4768-ad38-95aa3ec85403@github.com>
 <h1baGO4_88DIboIvFWEK-QfaeWbjLrkuwFV5Xz1iOIw=.a878dcce-b168-4114-a842-a704ddb0caf3@github.com>
Message-ID: <GOPf7tAXTikT_Ieo7WtAlOW1oCvhsgqSzkswZRp_SMw=.2246f478-4b6b-46df-a7b0-423cdbadea47@github.com>

On Tue, 30 Jan 2024 23:07:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java line 572:
>> 
>>> 570:                         }
>>> 571: 
>>> 572:                         case TEXT -> {
>> 
>> I haven't looked at `SentenceBreaker` in detail, but one thing that bothers me is that it sees a comment before that comment has been transformed. This means that `///` comments might not "feel" like Markdown to authors.
>
> First up: I do not understand your second sentence: _This means that /// comments might not "feel" like Markdown to authors._    Please rephrase or clarify that.
> 
> That aside, there's a big case of chickens and eggs here.  The API assumes that the first sentence is distinct from the rest of the description, so we cannot transform it at that early stage.  But generally, the first sentence is supposed to be reasonably simple text, and for cases where it is not, you can use the `summary` tag to circumvent any use of the sentence breaker.
> 
> Bottom line, I do not see any cause for concern at this time.

To add to that, regarding this:
> but one thing that bothers me is that it sees a comment before that comment has been transformed

I don't think we should support any transformations (i.e. custom extensions to Markdown) that would affect the detection of the end of the first sentence.  As of this review, the only custom extension is for enhanced links which simply infer link definitions for appropriate reference links.   If there is anything that is worth checking, it is the handling of any links, including reference links, in the first sentence.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1475229987

From prappo at openjdk.org  Thu Feb  1 23:07:08 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 1 Feb 2024 23:07:08 GMT
Subject: RFR: 8325109: Sort method modifiers in canonical order
In-Reply-To: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
References: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
Message-ID: <zBTvQPjpQKoxxj5CsUlaOfJkO0EyJy-lUfF8Zg6FQRQ=.132947bd-1b7a-4809-af69-e3d9ba962099@github.com>

On Thu, 1 Feb 2024 11:57:04 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is a follow-up on [JDK-8324053](https://bugs.openjdk.org/browse/JDK-8324053). I have run the bin/blessed-modifier-order.sh on the entire code base, and manually checked the result. I have reverted all but these trivial and uncontroversial changes.
> 
> Almost all of these are about moving `static` to its proper position; a few do not involve `static` but instead puts `final` or `abstract` in the correct place.
> 
> I have deliberately stayed away from `default` in this PR, since they should probably get a more thorough treatment, see https://github.com/openjdk/jdk/pull/17468#pullrequestreview-1829238473.

Changes to jdk.javadoc look fine.

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

Marked as reviewed by prappo (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17670#pullrequestreview-1857871131

From jjg at openjdk.org  Fri Feb  2 00:51:32 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 2 Feb 2024 00:51:32 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v17]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <sHTEhyYjMOUx6Qb8SCSClyM9cVauuF4JCP8WnMzRS34=.06d836c2-edfc-4623-8aa9-f02df689f168@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  updates for "first sentence" issues and tests

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/b02d4675..f086aaab

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=16
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=15-16

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

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

From ihse at openjdk.org  Fri Feb  2 06:40:01 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Fri, 2 Feb 2024 06:40:01 GMT
Subject: RFR: 8325109: Sort method modifiers in canonical order
In-Reply-To: <uY6CoY9NwuiOEmWivsV3k5OEdoBB4ETOCiK2fo0mDLU=.7ec4beb3-66b9-4076-8aa6-2caa221023bf@github.com>
References: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
 <uY6CoY9NwuiOEmWivsV3k5OEdoBB4ETOCiK2fo0mDLU=.7ec4beb3-66b9-4076-8aa6-2caa221023bf@github.com>
Message-ID: <c1A2_JMyhmgyx8N0-IvYuVxJ-uK43gJZ-qQRWUYtBbk=.aee9ccc3-254c-41e8-b839-e61c21ca7fae@github.com>

On Thu, 1 Feb 2024 17:21:23 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>  I just suggest double-checking on the current maintenance procedures for the java.util.concurrent code.

@jddarcy Any idea how to do that? I tried searching for JSR-166 and java.util.concurrent, but all I could find was talk about a now-deleted mailing list concurrency-interest, and a link to a [CVS repo for JDK8](http://gee.cs.oswego.edu/cgi-bin/viewcvs.cgi/jsr166/jsr166/src/jdk8/java/util/).

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

PR Comment: https://git.openjdk.org/jdk/pull/17670#issuecomment-1923018074

From dholmes at openjdk.org  Sun Feb  4 22:50:17 2024
From: dholmes at openjdk.org (David Holmes)
Date: Sun, 4 Feb 2024 22:50:17 GMT
Subject: [jdk22] RFR: 8322066: Update troff manpages in JDK 22 before RC
Message-ID: <Bn2yaD_18c678eQYCUsUyuwOAHSiVkwu2AK6aMB7FNA=.d21f35d6-bbab-400c-a420-54d8098bddde@github.com>

This update drops the "ea" from the version string.

We also propagate the following fixes from the markdown sources to the troff manpage file:

JDK-8322478: Update java manpage for multi-file source-code launcher
JDK-8302233: HSS/LMS: keytool and jarsigner changes
JDK-8318971: Better Error Handling for Jar Tool When Processing Non-existent Files


Thanks.

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

Commit messages:
 - 8322066: Update troff pages in JDK 22 before RC

Changes: https://git.openjdk.org/jdk22/pull/104/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk22&pr=104&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8322066
  Stats: 160 lines in 28 files changed: 63 ins; 15 del; 82 mod
  Patch: https://git.openjdk.org/jdk22/pull/104.diff
  Fetch: git fetch https://git.openjdk.org/jdk22.git pull/104/head:pull/104

PR: https://git.openjdk.org/jdk22/pull/104

From jlahoda at openjdk.org  Mon Feb  5 08:44:01 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Mon, 5 Feb 2024 08:44:01 GMT
Subject: RFR: 8323502: javac crash with wrongly typed method block in Flow
In-Reply-To: <C6MfeaWcvPaWuJdzxoUoxLAEGiq6tUizTO--GuzJpN0=.5d007893-e548-438b-b006-3bc5137b4b55@github.com>
References: <C6MfeaWcvPaWuJdzxoUoxLAEGiq6tUizTO--GuzJpN0=.5d007893-e548-438b-b006-3bc5137b4b55@github.com>
Message-ID: <-vgv0UzKpV32zMKVuxj7gmHKT_ZniKft8Q-s6eFjGwY=.c390b4f4-daff-46be-b5ff-a1c291840873@github.com>

On Wed, 17 Jan 2024 15:45:09 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

> The observation is that the `tree.target` of the RHS's `yield` was not set properly to point at the outer switch. As a result, the assertion was hit in `clearPendingExits` with a wrong set of pending exits.
> 
> The cause was that the `tree` was not attributed since `visitSwitchExpression` was short-circuited to `return;` and `visitYield` was never setting the `target`. As a result, `resolveJump` was not actually resolving the jump correctly.
> 
> thx @lahodaj for the help!

To me, looks good.

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

Marked as reviewed by jlahoda (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17466#pullrequestreview-1862147664

From abimpoudis at openjdk.org  Mon Feb  5 09:03:07 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Mon, 5 Feb 2024 09:03:07 GMT
Subject: Integrated: 8323502: javac crash with wrongly typed method block in
 Flow
In-Reply-To: <C6MfeaWcvPaWuJdzxoUoxLAEGiq6tUizTO--GuzJpN0=.5d007893-e548-438b-b006-3bc5137b4b55@github.com>
References: <C6MfeaWcvPaWuJdzxoUoxLAEGiq6tUizTO--GuzJpN0=.5d007893-e548-438b-b006-3bc5137b4b55@github.com>
Message-ID: <zAFa48HWgf-FX6MAKiP1B58HyiKH3envoKe5CpLbdjg=.8c78d5eb-9e6b-41f0-8c2a-ffb56d36d382@github.com>

On Wed, 17 Jan 2024 15:45:09 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

> The observation is that the `tree.target` of the RHS's `yield` was not set properly to point at the outer switch. As a result, the assertion was hit in `clearPendingExits` with a wrong set of pending exits.
> 
> The cause was that the `tree` was not attributed since `visitSwitchExpression` was short-circuited to `return;` and `visitYield` was never setting the `target`. As a result, `resolveJump` was not actually resolving the jump correctly.
> 
> thx @lahodaj for the help!

This pull request has now been integrated.

Changeset: df35462a
Author:    Aggelos Biboudis <abimpoudis at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/df35462a4eaa6bbe1c2ea1edaedf74728f549090
Stats:     42 lines in 3 files changed: 39 ins; 0 del; 3 mod

8323502: javac crash with wrongly typed method block in Flow

Co-authored-by: Jan Lahoda <jlahoda at openjdk.org>
Reviewed-by: jlahoda

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

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

From darcy at openjdk.org  Mon Feb  5 23:56:08 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Mon, 5 Feb 2024 23:56:08 GMT
Subject: [jdk22] RFR: 8322066: Update troff manpages in JDK 22 before RC
In-Reply-To: <Bn2yaD_18c678eQYCUsUyuwOAHSiVkwu2AK6aMB7FNA=.d21f35d6-bbab-400c-a420-54d8098bddde@github.com>
References: <Bn2yaD_18c678eQYCUsUyuwOAHSiVkwu2AK6aMB7FNA=.d21f35d6-bbab-400c-a420-54d8098bddde@github.com>
Message-ID: <JpJ7fBK_scQD13UZdtIO_B5ibXDQos_iDrQ8dro_YgM=.6ae9d6c5-1def-4108-a275-7f5bf4c7fc2b@github.com>

On Sun, 4 Feb 2024 22:43:28 GMT, David Holmes <dholmes at openjdk.org> wrote:

> This update drops the "ea" from the version string.
> 
> We also propagate the following fixes from the markdown sources to the troff manpage file:
> 
> JDK-8322478: Update java manpage for multi-file source-code launcher
> JDK-8302233: HSS/LMS: keytool and jarsigner changes
> JDK-8318971: Better Error Handling for Jar Tool When Processing Non-existent Files
> 
> 
> Thanks.

Marked as reviewed by darcy (Reviewer).

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

PR Review: https://git.openjdk.org/jdk22/pull/104#pullrequestreview-1863882694

From cushon at google.com  Tue Feb  6 00:08:55 2024
From: cushon at google.com (Liam Miller-Cushon)
Date: Mon, 5 Feb 2024 16:08:55 -0800
Subject: diagnostics for non-applicable type annotations
In-Reply-To: <CAEvq2noJ05eQNnHVoGVv80WXMcB7jL3FQp3qm1SubYO+THj6kg@mail.gmail.com>
References: <CAL4QsgvWtaqG-9SarR8eut07tsmq0RRXAbK-JDd0FxApB+wPLA@mail.gmail.com>
 <CAEvq2noJ05eQNnHVoGVv80WXMcB7jL3FQp3qm1SubYO+THj6kg@mail.gmail.com>
Message-ID: <CAL4Qsguy5LayCJ8Ytr_=UHz-vcvdsWwOa6FG8DNp9w3spm12Rw@mail.gmail.com>

Thanks Chris!

Does anyone else have feedback on the proposal?

On Tue, Jan 9, 2024 at 8:26?AM Chris Povirk <cpovirk at google.com> wrote:

> Thanks, Liam.
>
> We've found the current error messages to be a source of confusion: While
> the average user doesn't use type-use annotations, those users who do use
> them seem to hit this pretty frequently. We have our own FAQ entry about it
> in our internal documentation, and I also refer people to the Checker
> Framework's documentation
> <https://checkerframework.org/manual/#common-problems-non-typechecking>,
> which gives advice similar to that implemented by Liam's PR. I would expect
> for that page and this Stack Overflow answer
> <https://stackoverflow.com/a/21385939/28465> to get more traffic as
> type-use annotations grow in popularity, as we're aiming for them to do as
> part of our work on JSpecify nullness. The error-message changes could save
> users a trip to those docs.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/compiler-dev/attachments/20240205/a05476e7/attachment.htm>

From jjg at openjdk.org  Tue Feb  6 01:36:58 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 6 Feb 2024 01:36:58 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v18]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <RIP-4xQbHyEjoPx-PHy-YFMYjq5xq1pjV5SCdVWbQNo=.c6fa9a51-39c3-4ef9-bfe9-1382b9bc016f@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  First pass at remove DocCommentTransformer from the public API.
  
  It is still declared internally, and installed by default, using the service-provider mechanism.
  If the standard impl is not available, an identity transformer is used.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/f086aaab..203532b2

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=17
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=16-17

  Stats: 191 lines in 11 files changed: 89 ins; 90 del; 12 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From darcy at openjdk.org  Tue Feb  6 02:33:46 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Tue, 6 Feb 2024 02:33:46 GMT
Subject: RFR: JDK-8325268: Add policy statement to langtools makefiles
 concerning warnings
Message-ID: <SDIA7FXQnkrauJHNBE5Ziz5YoRkEdYi5TTUZSKDAiYo=.85170a59-a6aa-4940-b5ad-3cdcdac8d6ab@github.com>

Add policy statement about lint warnings to various langtools modules.

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

Commit messages:
 - JDK-8325268: Add policy statement to langtools makefiles concerning warnings

Changes: https://git.openjdk.org/jdk/pull/17718/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17718&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325268
  Stats: 14 lines in 3 files changed: 12 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/17718.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17718/head:pull/17718

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

From iris at openjdk.org  Tue Feb  6 03:11:03 2024
From: iris at openjdk.org (Iris Clark)
Date: Tue, 6 Feb 2024 03:11:03 GMT
Subject: [jdk22] RFR: 8322066: Update troff manpages in JDK 22 before RC
In-Reply-To: <Bn2yaD_18c678eQYCUsUyuwOAHSiVkwu2AK6aMB7FNA=.d21f35d6-bbab-400c-a420-54d8098bddde@github.com>
References: <Bn2yaD_18c678eQYCUsUyuwOAHSiVkwu2AK6aMB7FNA=.d21f35d6-bbab-400c-a420-54d8098bddde@github.com>
Message-ID: <4cRyPED3qle_BVYZkKe7WqzTTTypo6nFookYaFGeCDw=.a49cec00-d0b4-4f09-85f0-e5c2ce730792@github.com>

On Sun, 4 Feb 2024 22:43:28 GMT, David Holmes <dholmes at openjdk.org> wrote:

> This update drops the "ea" from the version string.
> 
> We also propagate the following fixes from the markdown sources to the troff manpage file:
> 
> JDK-8322478: Update java manpage for multi-file source-code launcher
> JDK-8302233: HSS/LMS: keytool and jarsigner changes
> JDK-8318971: Better Error Handling for Jar Tool When Processing Non-existent Files
> 
> 
> Thanks.

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/jdk22/pull/104#pullrequestreview-1864200734

From dholmes at openjdk.org  Tue Feb  6 04:58:53 2024
From: dholmes at openjdk.org (David Holmes)
Date: Tue, 6 Feb 2024 04:58:53 GMT
Subject: [jdk22] RFR: 8322066: Update troff manpages in JDK 22 before RC
In-Reply-To: <JpJ7fBK_scQD13UZdtIO_B5ibXDQos_iDrQ8dro_YgM=.6ae9d6c5-1def-4108-a275-7f5bf4c7fc2b@github.com>
References: <Bn2yaD_18c678eQYCUsUyuwOAHSiVkwu2AK6aMB7FNA=.d21f35d6-bbab-400c-a420-54d8098bddde@github.com>
 <JpJ7fBK_scQD13UZdtIO_B5ibXDQos_iDrQ8dro_YgM=.6ae9d6c5-1def-4108-a275-7f5bf4c7fc2b@github.com>
Message-ID: <FSy9f973gXj84Ajd9__EnOKfPyXHbbWaFo1NRR8MeKM=.6f57bddd-83fb-4f1f-8c50-e5fb7089586d@github.com>

On Mon, 5 Feb 2024 21:58:23 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> This update drops the "ea" from the version string.
>> 
>> We also propagate the following fixes from the markdown sources to the troff manpage file:
>> 
>> JDK-8322478: Update java manpage for multi-file source-code launcher
>> JDK-8302233: HSS/LMS: keytool and jarsigner changes
>> JDK-8318971: Better Error Handling for Jar Tool When Processing Non-existent Files
>> 
>> 
>> Thanks.
>
> Marked as reviewed by darcy (Reviewer).

Thanks for the reviews @jddarcy  and @irisclark !

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

PR Comment: https://git.openjdk.org/jdk22/pull/104#issuecomment-1928783920

From dholmes at openjdk.org  Tue Feb  6 04:58:54 2024
From: dholmes at openjdk.org (David Holmes)
Date: Tue, 6 Feb 2024 04:58:54 GMT
Subject: [jdk22] Integrated: 8322066: Update troff manpages in JDK 22 before RC
In-Reply-To: <Bn2yaD_18c678eQYCUsUyuwOAHSiVkwu2AK6aMB7FNA=.d21f35d6-bbab-400c-a420-54d8098bddde@github.com>
References: <Bn2yaD_18c678eQYCUsUyuwOAHSiVkwu2AK6aMB7FNA=.d21f35d6-bbab-400c-a420-54d8098bddde@github.com>
Message-ID: <43aREZ6MAFvrQojZi3ALfLy7yqlrS76R3HUs5lil8xE=.2471360a-6946-4dbc-91e8-386b5d31df58@github.com>

On Sun, 4 Feb 2024 22:43:28 GMT, David Holmes <dholmes at openjdk.org> wrote:

> This update drops the "ea" from the version string.
> 
> We also propagate the following fixes from the markdown sources to the troff manpage file:
> 
> JDK-8322478: Update java manpage for multi-file source-code launcher
> JDK-8302233: HSS/LMS: keytool and jarsigner changes
> JDK-8318971: Better Error Handling for Jar Tool When Processing Non-existent Files
> 
> 
> Thanks.

This pull request has now been integrated.

Changeset: ac7a3c00
Author:    David Holmes <dholmes at openjdk.org>
URL:       https://git.openjdk.org/jdk22/commit/ac7a3c00bbfde173ced08d8745b308bc0ac9649b
Stats:     160 lines in 28 files changed: 63 ins; 15 del; 82 mod

8322066: Update troff manpages in JDK 22 before RC

Reviewed-by: darcy, iris

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

PR: https://git.openjdk.org/jdk22/pull/104

From jlahoda at openjdk.org  Tue Feb  6 07:11:02 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Tue, 6 Feb 2024 07:11:02 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v18]
In-Reply-To: <RIP-4xQbHyEjoPx-PHy-YFMYjq5xq1pjV5SCdVWbQNo=.c6fa9a51-39c3-4ef9-bfe9-1382b9bc016f@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <RIP-4xQbHyEjoPx-PHy-YFMYjq5xq1pjV5SCdVWbQNo=.c6fa9a51-39c3-4ef9-bfe9-1382b9bc016f@github.com>
Message-ID: <l62YkgsxqBHwYu5AzzN6v-rMMuUARmbIOVdQnlEfQ4c=.5b166998-4f34-4526-96de-3a6ea9030c76@github.com>

On Tue, 6 Feb 2024 01:36:58 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   First pass at remove DocCommentTransformer from the public API.
>   
>   It is still declared internally, and installed by default, using the service-provider mechanism.
>   If the standard impl is not available, an identity transformer is used.

src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 1:

> 1: /*

This transformer seems to break positions of the `RawTextTree`.
For javadoc like:

                        /// Markdown test
                        ///
                        /// @author testAuthor

without this transformer, taking the start and end positions of the `RawTextTree` and taking the text between these positions will lead to: `[Markdown test, testAuthor]`. With this transfomer, it leads to `[Markdown test, Markdown t]`, which is clearly suspicious.

Testcase:

/*
 * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

/*
 * @test
 * @bug 9999999
 * @summary XXX
 * @run main/othervm --limit-modules jdk.compiler MarkdownTransformerPositionTest
 * @run main MarkdownTransformerPositionTest
 */

import com.sun.source.doctree.DocCommentTree;
import com.sun.source.doctree.RawTextTree;
import com.sun.source.tree.*;
import com.sun.source.util.*;

import java.net.URI;
import java.util.*;
import javax.lang.model.element.Element;
import javax.tools.*;


public class MarkdownTransformerPositionTest {

    public static void main(String... args) throws Exception {
        String source = """
                        /// Markdown test
                        ///
                        /// @author testAuthor
                        public class Test {
                        }
                        """;
        JavaCompiler comp = ToolProvider.getSystemJavaCompiler();
        JavacTask task = (JavacTask)comp.getTask(null, null, null, null, null, Arrays.asList(new JavaSource(source)));
        CompilationUnitTree cu = task.parse().iterator().next();
        task.analyze();
        DocTrees trees = DocTrees.instance(task);
        List<String> rawSpans = new ArrayList<>();
        TreePath clazzTP = new TreePath(new TreePath(cu), cu.getTypeDecls().get(0));
        Element clazz = trees.getElement(clazzTP);
        DocCommentTree docComment = trees.getDocCommentTree(clazz);

        new DocTreeScanner<Void, Void>() {
            @Override
            public Void visitRawText(RawTextTree node, Void p) {
                int start = (int) trees.getSourcePositions().getStartPosition(cu, docComment, node);
                int end = (int) trees.getSourcePositions().getEndPosition(cu, docComment, node);
                rawSpans.add(source.substring(start, end));
                return super.visitRawText(node, p);
            }
        }.scan(docComment, null);

        List<String> expectedRawSpans = List.of("Markdown test", "testAuthor");

        if (!expectedRawSpans.equals(rawSpans)) {
            throw new AssertionError("Incorrect raw text spans, should be: " +
                                     expectedRawSpans + ", but is: " + rawSpans);
        }

        System.err.println("Test result: success, boot modules: " + ModuleLayer.boot().modules());
    }

    static class JavaSource extends SimpleJavaFileObject {

        private final String source;

        public JavaSource(String source) {
            super(URI.create("myfo:/Test.java"), JavaFileObject.Kind.SOURCE);
            this.source = source;
        }

        @Override
        public CharSequence getCharContent(boolean ignoreEncodingErrors) {
            return source;
        }
    }
}

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1479306878

From abimpoudis at openjdk.org  Tue Feb  6 10:54:16 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Tue, 6 Feb 2024 10:54:16 GMT
Subject: RFR: 8325257: jshell reports NoSuchFieldError with instanceof
 primitive type
Message-ID: <g7K6PelTU6m2rNVHVe_ep0jUmSpkH3j32bcFjZyXrUE=.11f5cc29-b924-4ebc-93dd-e937e556e55e@github.com>

Fixed compiler bug during lowering of the type test, where the let expression was using the `expr` of the old `tree` and not of the translated one. The latter manifested as a JShell error. Added compiler test as well. e.g., 


class $JShell$2 {
    
    $JShell$2() {
        super();
    }
    public static boolean $1;
    
    public static Object do_it$() throws Throwable {
        return Boolean.valueOf($1 = (let /*synthetic*/ final Object tmp184$ = $JShell$1.o 
                                     in tmp184$ != null && o instanceof Long));                          
                                                        // ^
    }
}

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

Commit messages:
 - 8325257: jshell reports NoSuchFieldError with instanceof primitive type

Changes: https://git.openjdk.org/jdk/pull/17729/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17729&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325257
  Stats: 22 lines in 3 files changed: 17 ins; 0 del; 5 mod
  Patch: https://git.openjdk.org/jdk/pull/17729.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17729/head:pull/17729

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

From ihse at openjdk.org  Tue Feb  6 11:39:57 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Tue, 6 Feb 2024 11:39:57 GMT
Subject: RFR: 8325109: Sort method modifiers in canonical order
In-Reply-To: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
References: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
Message-ID: <hMv74_Mz6j4w5HMKHfGqeYuSNKUfu3ywR8Zdxv3nUBQ=.8965f0fa-9ea6-467b-b8a3-4a1dc59c2d76@github.com>

On Thu, 1 Feb 2024 11:57:04 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is a follow-up on [JDK-8324053](https://bugs.openjdk.org/browse/JDK-8324053). I have run the bin/blessed-modifier-order.sh on the entire code base, and manually checked the result. I have reverted all but these trivial and uncontroversial changes.
> 
> Almost all of these are about moving `static` to its proper position; a few do not involve `static` but instead puts `final` or `abstract` in the correct place.
> 
> I have deliberately stayed away from `default` in this PR, since they should probably get a more thorough treatment, see https://github.com/openjdk/jdk/pull/17468#pullrequestreview-1829238473.

@DougLea Doug, do you have anything to say about the changes in `java.util.concurrent`?

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

PR Comment: https://git.openjdk.org/jdk/pull/17670#issuecomment-1929336942

From cstein at openjdk.org  Tue Feb  6 12:06:01 2024
From: cstein at openjdk.org (Christian Stein)
Date: Tue, 6 Feb 2024 12:06:01 GMT
Subject: RFR: 8323605: Java source launcher should not require `--source ...`
 to enable preview
Message-ID: <JJD99SlLDH8cPUveBx3kOwCt_7rTT685g2lqlQRgkqw=.3864c4b1-5eff-42d4-881b-37dca48272d6@github.com>

Please review this PR targeting the source launcher that instead of throwing an error reading _"--enable-preview must be used with --source"_ adds the required compiler arguments on-the-fly.

The add arguments are `--release` and `feature`, with `feature` being the release feature number of the current Java runtime as acquired by `Runtime.version().feature()`.

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

Commit messages:
 - 8323605: Java source launcher should not require `--source ...` to enable preview

Changes: https://git.openjdk.org/jdk/pull/17731/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17731&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8323605
  Stats: 13 lines in 3 files changed: 2 ins; 7 del; 4 mod
  Patch: https://git.openjdk.org/jdk/pull/17731.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17731/head:pull/17731

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

From cstein at openjdk.org  Tue Feb  6 12:24:07 2024
From: cstein at openjdk.org (Christian Stein)
Date: Tue, 6 Feb 2024 12:24:07 GMT
Subject: RFR: 8323605: Java source launcher should not require `--source
 ...` to enable preview [v2]
In-Reply-To: <JJD99SlLDH8cPUveBx3kOwCt_7rTT685g2lqlQRgkqw=.3864c4b1-5eff-42d4-881b-37dca48272d6@github.com>
References: <JJD99SlLDH8cPUveBx3kOwCt_7rTT685g2lqlQRgkqw=.3864c4b1-5eff-42d4-881b-37dca48272d6@github.com>
Message-ID: <69gKaPPanuID1p8h7uZRWDvmPCQwgP-P-1yn65mv-Ww=.cc16362c-6a9e-4cb9-9249-3e52c1dc3228@github.com>

> Please review this PR targeting the source launcher that instead of throwing an error reading _"--enable-preview must be used with --source"_ adds the required compiler arguments on-the-fly.
> 
> The add arguments are `--release` and `feature`, with `feature` being the release feature number of the current Java runtime as acquired by `Runtime.version().feature()`.

Christian Stein has updated the pull request incrementally with one additional commit since the last revision:

  Update copyright dates
  
  [skip ci]

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17731/files
  - new: https://git.openjdk.org/jdk/pull/17731/files/323e34b7..7883b861

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17731&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17731&range=00-01

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

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

From ihse at openjdk.org  Tue Feb  6 12:29:55 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Tue, 6 Feb 2024 12:29:55 GMT
Subject: RFR: JDK-8325268: Add policy statement to langtools makefiles
 concerning warnings
In-Reply-To: <SDIA7FXQnkrauJHNBE5Ziz5YoRkEdYi5TTUZSKDAiYo=.85170a59-a6aa-4940-b5ad-3cdcdac8d6ab@github.com>
References: <SDIA7FXQnkrauJHNBE5Ziz5YoRkEdYi5TTUZSKDAiYo=.85170a59-a6aa-4940-b5ad-3cdcdac8d6ab@github.com>
Message-ID: <e2spIarpf_7he-D94CEm8hf-jaEZz1YpkFLjxBCvg_c=.2eadd425-9c4d-4644-948d-512b9af67fa1@github.com>

On Tue, 6 Feb 2024 02:28:32 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Add policy statement about lint warnings to various langtools modules.

LGTM

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

Marked as reviewed by ihse (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17718#pullrequestreview-1865030163

From mcimadamore at openjdk.org  Tue Feb  6 13:56:54 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 6 Feb 2024 13:56:54 GMT
Subject: RFR: 8325257: jshell reports NoSuchFieldError with instanceof
 primitive type
In-Reply-To: <g7K6PelTU6m2rNVHVe_ep0jUmSpkH3j32bcFjZyXrUE=.11f5cc29-b924-4ebc-93dd-e937e556e55e@github.com>
References: <g7K6PelTU6m2rNVHVe_ep0jUmSpkH3j32bcFjZyXrUE=.11f5cc29-b924-4ebc-93dd-e937e556e55e@github.com>
Message-ID: <CkBcpEqMfizHZcVGzpomdivIimOVGeAg7qaN9xi9Qs0=.2e570ced-0c38-499f-9ac1-36e5bc7653d8@github.com>

On Tue, 6 Feb 2024 10:50:08 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

> Fixed compiler bug during lowering of the type test, where the let expression was using the `expr` of the old `tree` and not of the translated one. The latter manifested as a JShell error. Added compiler test as well. e.g., 
> 
> 
> class $JShell$2 {
>     
>     $JShell$2() {
>         super();
>     }
>     public static boolean $1;
>     
>     public static Object do_it$() throws Throwable {
>         return Boolean.valueOf($1 = (let /*synthetic*/ final Object tmp184$ = $JShell$1.o 
>                                      in tmp184$ != null && o instanceof Long));                          
>                                                         // ^
>     }
> }

Looks good

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

Marked as reviewed by mcimadamore (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17729#pullrequestreview-1865254355

From cstein at openjdk.org  Tue Feb  6 14:06:07 2024
From: cstein at openjdk.org (Christian Stein)
Date: Tue, 6 Feb 2024 14:06:07 GMT
Subject: RFR: 8323605: Java source launcher should not require `--source
 ...` to enable preview [v3]
In-Reply-To: <JJD99SlLDH8cPUveBx3kOwCt_7rTT685g2lqlQRgkqw=.3864c4b1-5eff-42d4-881b-37dca48272d6@github.com>
References: <JJD99SlLDH8cPUveBx3kOwCt_7rTT685g2lqlQRgkqw=.3864c4b1-5eff-42d4-881b-37dca48272d6@github.com>
Message-ID: <fnDSeJ7T9oUgX4X1n881yYMFeqQncfBZEB6-gN0aB3c=.a4662f7a-f14d-4777-8543-61ce47cd1d72@github.com>

> Please review this PR targeting the source launcher that instead of throwing an error reading _"--enable-preview must be used with --source"_ adds the required compiler arguments on-the-fly.
> 
> The add arguments are `--release` and `feature`, with `feature` being the release feature number of the current Java runtime as acquired by `Runtime.version().feature()`.

Christian Stein has updated the pull request incrementally with one additional commit since the last revision:

  Remove now outdated workaround
  
  [skip ci]

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17731/files
  - new: https://git.openjdk.org/jdk/pull/17731/files/7883b861..23fba2bf

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17731&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17731&range=01-02

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

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

From mcimadamore at openjdk.org  Tue Feb  6 15:59:54 2024
From: mcimadamore at openjdk.org (Maurizio Cimadamore)
Date: Tue, 6 Feb 2024 15:59:54 GMT
Subject: RFR: 8323605: Java source launcher should not require `--source
 ...` to enable preview [v3]
In-Reply-To: <fnDSeJ7T9oUgX4X1n881yYMFeqQncfBZEB6-gN0aB3c=.a4662f7a-f14d-4777-8543-61ce47cd1d72@github.com>
References: <JJD99SlLDH8cPUveBx3kOwCt_7rTT685g2lqlQRgkqw=.3864c4b1-5eff-42d4-881b-37dca48272d6@github.com>
 <fnDSeJ7T9oUgX4X1n881yYMFeqQncfBZEB6-gN0aB3c=.a4662f7a-f14d-4777-8543-61ce47cd1d72@github.com>
Message-ID: <WyJPOFHm6UzC7ZqRPm2v0t3pomlZhKLct5QFfDDnAk8=.7727e18a-5023-464c-94ed-4f1d99eea837@github.com>

On Tue, 6 Feb 2024 14:06:07 GMT, Christian Stein <cstein at openjdk.org> wrote:

>> Please review this PR targeting the source launcher that instead of throwing an error reading _"--enable-preview must be used with --source"_ adds the required compiler arguments on-the-fly.
>> 
>> The add arguments are `--release` and `feature`, with `feature` being the release feature number of the current Java runtime as acquired by `Runtime.version().feature()`.
>
> Christian Stein has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Remove now outdated workaround
>   
>   [skip ci]

Looks good!

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

Marked as reviewed by mcimadamore (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17731#pullrequestreview-1865632395

From ihse at openjdk.org  Tue Feb  6 16:28:03 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Tue, 6 Feb 2024 16:28:03 GMT
Subject: RFR: 8298044: Fix hidden but significant trailing whitespace in
 properties files for langtools code
In-Reply-To: <XTrtCArjzxYwYSv-IZZ_I1vdatcAPUNmDMURw33rHg0=.a3f2717c-a5c1-403b-899a-7f4af166a891@github.com>
References: <XTrtCArjzxYwYSv-IZZ_I1vdatcAPUNmDMURw33rHg0=.a3f2717c-a5c1-403b-899a-7f4af166a891@github.com>
Message-ID: <NrJTC3stlxFQWztet4N8xhmweI4CStcr10g3fcTpW_4=.d905ff86-5c65-4f88-a39d-6c0a4e6bba7c@github.com>

On Fri, 2 Dec 2022 16:36:22 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> According to [the specification](https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/util/Properties.html#load(java.io.Reader)) trailing whitespaces in the values of properties files are (somewhat surprisingly) actually significant.
> 
> We have multiple files in the JDK with trailing whitespaces in the values. For most of this files, this is likely incorrect and due to oversight, but in a few cases it might actually be intended (like "The value is: ").
> 
> After a discussion in the PR for [JDK-8295729](https://bugs.openjdk.org/browse/JDK-8295729), the consensus was to replace valid trailing spaces with the corresponding unicode sequence, `\u0020`. (And of course remove non-wanted trailing spaces.)
> 
> Doing so has a dual benefit:
> 
> 1) It makes it clear to everyone reading the code that there is a trailing space and it is intended
> 
> 2) It will allow us to remove all actual trailing space characters, and turn on the corresponding check in jcheck to keep the properties files, just like all other source code files, free of trailing spaces.
> 
> Ultimately, the call of whether a trailing space is supposed to be there, or is a bug, lies with the respective component teams owning these files. Thus I have split up the set of properties files with trailing spaces in several groups, to match the JDK teams, and open a JBS issue for each of them. This issue is for code I believe belongs with the langtools team.

For the record, when I tried to revive this, it turned out that all changes proposed here were already implemented in master.

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

PR Comment: https://git.openjdk.org/jdk/pull/11487#issuecomment-1930231543

From jlu at openjdk.org  Tue Feb  6 18:43:01 2024
From: jlu at openjdk.org (Justin Lu)
Date: Tue, 6 Feb 2024 18:43:01 GMT
Subject: RFR: 8298044: Fix hidden but significant trailing whitespace in
 properties files for langtools code
In-Reply-To: <NrJTC3stlxFQWztet4N8xhmweI4CStcr10g3fcTpW_4=.d905ff86-5c65-4f88-a39d-6c0a4e6bba7c@github.com>
References: <XTrtCArjzxYwYSv-IZZ_I1vdatcAPUNmDMURw33rHg0=.a3f2717c-a5c1-403b-899a-7f4af166a891@github.com>
 <NrJTC3stlxFQWztet4N8xhmweI4CStcr10g3fcTpW_4=.d905ff86-5c65-4f88-a39d-6c0a4e6bba7c@github.com>
Message-ID: <3VL5M629rog_nnT8coNUIEcHPbhc8KwC8s_1qbFNWAQ=.beb54eca-cbf3-45f8-8208-057acc677951@github.com>

On Tue, 6 Feb 2024 16:24:53 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> According to [the specification](https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/util/Properties.html#load(java.io.Reader)) trailing whitespaces in the values of properties files are (somewhat surprisingly) actually significant.
>> 
>> We have multiple files in the JDK with trailing whitespaces in the values. For most of this files, this is likely incorrect and due to oversight, but in a few cases it might actually be intended (like "The value is: ").
>> 
>> After a discussion in the PR for [JDK-8295729](https://bugs.openjdk.org/browse/JDK-8295729), the consensus was to replace valid trailing spaces with the corresponding unicode sequence, `\u0020`. (And of course remove non-wanted trailing spaces.)
>> 
>> Doing so has a dual benefit:
>> 
>> 1) It makes it clear to everyone reading the code that there is a trailing space and it is intended
>> 
>> 2) It will allow us to remove all actual trailing space characters, and turn on the corresponding check in jcheck to keep the properties files, just like all other source code files, free of trailing spaces.
>> 
>> Ultimately, the call of whether a trailing space is supposed to be there, or is a bug, lies with the respective component teams owning these files. Thus I have split up the set of properties files with trailing spaces in several groups, to match the JDK teams, and open a JBS issue for each of them. This issue is for code I believe belongs with the langtools team.
>
> For the record, when I tried to revive this, it turned out that all changes proposed here were already implemented in master.

Hi @magicus, the trailing white space in all .properties files between the localized and un-localized versions was standardized in [8300719](https://bugs.openjdk.org/browse/JDK-8300719) as part of the L10n translations. The changes there likely included the proposed changes here as well.

For context, there was no removal of questionable trailing white space, only the standardization that the localized versions matched the original version. And similar to this patch, `/u0020` was used in replacement of ` `. We usually see that the external translation tool causes inconsistency in trailing white space, so we re-run our white space tool during each L10n translation drop.

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

PR Comment: https://git.openjdk.org/jdk/pull/11487#issuecomment-1930543225

From jjg at openjdk.org  Tue Feb  6 19:31:06 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 6 Feb 2024 19:31:06 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v18]
In-Reply-To: <l62YkgsxqBHwYu5AzzN6v-rMMuUARmbIOVdQnlEfQ4c=.5b166998-4f34-4526-96de-3a6ea9030c76@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <RIP-4xQbHyEjoPx-PHy-YFMYjq5xq1pjV5SCdVWbQNo=.c6fa9a51-39c3-4ef9-bfe9-1382b9bc016f@github.com>
 <l62YkgsxqBHwYu5AzzN6v-rMMuUARmbIOVdQnlEfQ4c=.5b166998-4f34-4526-96de-3a6ea9030c76@github.com>
Message-ID: <UVXpzCUqXHCV4DX8cuZ35YSyGI5zWmqItEaxgtV4WVc=.563257a5-d67c-4d38-adf6-8b03b94de37c@github.com>

On Tue, 6 Feb 2024 07:08:13 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   First pass at remove DocCommentTransformer from the public API.
>>   
>>   It is still declared internally, and installed by default, using the service-provider mechanism.
>>   If the standard impl is not available, an identity transformer is used.
>
> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 1:
> 
>> 1: /*
> 
> This transformer seems to break positions of the `RawTextTree`.
> For javadoc like:
> 
>                         /// Markdown test
>                         ///
>                         /// @author testAuthor
> 
> without this transformer, taking the start and end positions of the `RawTextTree` and taking the text between these positions will lead to: `[Markdown test, testAuthor]`. With this transfomer, it leads to `[Markdown test, Markdown t]`, which is clearly suspicious.
> 
> Testcase:
> 
> /*
>  * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
>  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>  *
>  * This code is free software; you can redistribute it and/or modify it
>  * under the terms of the GNU General Public License version 2 only, as
>  * published by the Free Software Foundation.
>  *
>  * This code is distributed in the hope that it will be useful, but WITHOUT
>  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
>  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
>  * version 2 for more details (a copy is included in the LICENSE file that
>  * accompanied this code).
>  *
>  * You should have received a copy of the GNU General Public License version
>  * 2 along with this work; if not, write to the Free Software Foundation,
>  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
>  *
>  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
>  * or visit www.oracle.com if you need additional information or have any
>  * questions.
>  */
> 
> /*
>  * @test
>  * @bug 9999999
>  * @summary XXX
>  * @run main/othervm --limit-modules jdk.compiler MarkdownTransformerPositionTest
>  * @run main MarkdownTransformerPositionTest
>  */
> 
> import com.sun.source.doctree.DocCommentTree;
> import com.sun.source.doctree.RawTextTree;
> import com.sun.source.tree.*;
> import com.sun.source.util.*;
> 
> import java.net.URI;
> import java.util.*;
> import javax.lang.model.element.Element;
> import javax.tools.*;
> 
> 
> public class MarkdownTransformerPositionTest {
> 
>     public static void main(String... args) throws Exception {
>         String source = """
>                         /// Markdown test
>                         ///
>                         /// @author testAuthor
>                         public class Test {
>                         }
>                         """;
>         JavaCompiler comp = ToolProvider.getSystemJavaCompiler();
>         JavacTask ...

Uugh.  Noted.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1480437320

From jjg at openjdk.org  Tue Feb  6 20:00:01 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 6 Feb 2024 20:00:01 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v18]
In-Reply-To: <UVXpzCUqXHCV4DX8cuZ35YSyGI5zWmqItEaxgtV4WVc=.563257a5-d67c-4d38-adf6-8b03b94de37c@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <RIP-4xQbHyEjoPx-PHy-YFMYjq5xq1pjV5SCdVWbQNo=.c6fa9a51-39c3-4ef9-bfe9-1382b9bc016f@github.com>
 <l62YkgsxqBHwYu5AzzN6v-rMMuUARmbIOVdQnlEfQ4c=.5b166998-4f34-4526-96de-3a6ea9030c76@github.com>
 <UVXpzCUqXHCV4DX8cuZ35YSyGI5zWmqItEaxgtV4WVc=.563257a5-d67c-4d38-adf6-8b03b94de37c@github.com>
Message-ID: <6EEwmjOExugvg9w74ZEhDGZ37af9ott0EdQfTPpU5i4=.2279f998-cf78-47ad-8ef7-8a0da0831be6@github.com>

On Tue, 6 Feb 2024 19:27:55 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 1:
>> 
>>> 1: /*
>> 
>> This transformer seems to break positions of the `RawTextTree`.
>> For javadoc like:
>> 
>>                         /// Markdown test
>>                         ///
>>                         /// @author testAuthor
>> 
>> without this transformer, taking the start and end positions of the `RawTextTree` and taking the text between these positions will lead to: `[Markdown test, testAuthor]`. With this transfomer, it leads to `[Markdown test, Markdown t]`, which is clearly suspicious.
>> 
>> Testcase:
>> 
>> /*
>>  * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
>>  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
>>  *
>>  * This code is free software; you can redistribute it and/or modify it
>>  * under the terms of the GNU General Public License version 2 only, as
>>  * published by the Free Software Foundation.
>>  *
>>  * This code is distributed in the hope that it will be useful, but WITHOUT
>>  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
>>  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
>>  * version 2 for more details (a copy is included in the LICENSE file that
>>  * accompanied this code).
>>  *
>>  * You should have received a copy of the GNU General Public License version
>>  * 2 along with this work; if not, write to the Free Software Foundation,
>>  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
>>  *
>>  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
>>  * or visit www.oracle.com if you need additional information or have any
>>  * questions.
>>  */
>> 
>> /*
>>  * @test
>>  * @bug 9999999
>>  * @summary XXX
>>  * @run main/othervm --limit-modules jdk.compiler MarkdownTransformerPositionTest
>>  * @run main MarkdownTransformerPositionTest
>>  */
>> 
>> import com.sun.source.doctree.DocCommentTree;
>> import com.sun.source.doctree.RawTextTree;
>> import com.sun.source.tree.*;
>> import com.sun.source.util.*;
>> 
>> import java.net.URI;
>> import java.util.*;
>> import javax.lang.model.element.Element;
>> import javax.tools.*;
>> 
>> 
>> public class MarkdownTransformerPositionTest {
>> 
>>     public static void main(String... args) throws Exception {
>>         String source = """
>>                         /// Markdown test
>>                         ///
>>                         /// @author testAuthor
>>                         public class Test {
>>         ...
>
> Uugh.  Noted.

There are two cases that need consideration:
1. A tree that is not modified during the transformation, as in the test case here, so that all nodes should be "as before"
2. A tree that is modified during the transformation, raising the issue of the positions of the new node and any enclosing node

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1480467208

From jjg at openjdk.org  Tue Feb  6 22:05:44 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 6 Feb 2024 22:05:44 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v19]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <Y3aFNXN3o5yr8X0JE59s4DCZ49XEsKn40JntdncuBA8=.5bda22c4-0fd5-4906-864f-43b7fd201788@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  remove unused imports

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/203532b2..2a20c74b

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=18
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=17-18

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

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

From kcr at openjdk.org  Tue Feb  6 23:08:11 2024
From: kcr at openjdk.org (Kevin Rushforth)
Date: Tue, 6 Feb 2024 23:08:11 GMT
Subject: [jdk22] RFR: 8322159: ThisEscapeAnalyzer crashes for erroneous
 code
In-Reply-To: <W0kG7mO0T3nzSuq051cg0Ljx2uo2BMArDgVXgDje1kU=.8888df7d-9ae9-44ce-8121-434e9a758e5d@github.com>
References: <W0kG7mO0T3nzSuq051cg0Ljx2uo2BMArDgVXgDje1kU=.8888df7d-9ae9-44ce-8121-434e9a758e5d@github.com>
Message-ID: <aZ-654cIR5ResSDiUuVH8HHzIWPhRUm7VZPhD_DvMNo=.ff58bdc5-942a-4787-82a5-ce9ba710c2c1@github.com>

On Tue, 2 Jan 2024 12:32:04 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Hi all,
> 
> This pull request contains a backport of commit [7455b1b5](https://github.com/openjdk/jdk/commit/7455b1b527568aff5b1c16a29fd80b05260c0fad) from the [openjdk/jdk](https://git.openjdk.org/jdk) repository.
> 
> The commit being backported was authored by Jan Lahoda on 2 Jan 2024 and was reviewed by Vicente Romero.
> 
> Thanks!

@lahodaj This PR should be closed, since it is not a candidate for JDK 22 (I see that a review is in progress for the jdk22u backport, which is good).

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

PR Comment: https://git.openjdk.org/jdk22/pull/26#issuecomment-1930917782

From jjg at openjdk.org  Wed Feb  7 00:20:21 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 7 Feb 2024 00:20:21 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v20]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <QWiZQpzCfBJwXNfe4QZljJnuhzXZeInI0IGt38FI1UM=.8b2e090a-0a75-4eec-9c68-bddbed99014c@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  initial fix for source offset problem

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/2a20c74b..7c631688

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=19
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=18-19

  Stats: 32 lines in 3 files changed: 22 ins; 1 del; 9 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From jjg at openjdk.org  Wed Feb  7 00:20:21 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 7 Feb 2024 00:20:21 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v18]
In-Reply-To: <6EEwmjOExugvg9w74ZEhDGZ37af9ott0EdQfTPpU5i4=.2279f998-cf78-47ad-8ef7-8a0da0831be6@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <RIP-4xQbHyEjoPx-PHy-YFMYjq5xq1pjV5SCdVWbQNo=.c6fa9a51-39c3-4ef9-bfe9-1382b9bc016f@github.com>
 <l62YkgsxqBHwYu5AzzN6v-rMMuUARmbIOVdQnlEfQ4c=.5b166998-4f34-4526-96de-3a6ea9030c76@github.com>
 <UVXpzCUqXHCV4DX8cuZ35YSyGI5zWmqItEaxgtV4WVc=.563257a5-d67c-4d38-adf6-8b03b94de37c@github.com>
 <6EEwmjOExugvg9w74ZEhDGZ37af9ott0EdQfTPpU5i4=.2279f998-cf78-47ad-8ef7-8a0da0831be6@github.com>
Message-ID: <43UGpbzrBbISoThN_wch1kQQD0FYeWlAvaTM_pH6dTs=.4250aff5-cc0e-41e9-9a1b-f62fd8989b25@github.com>

On Tue, 6 Feb 2024 19:57:45 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Uugh.  Noted.
>
> There are two cases that need consideration:
> 1. A tree that is not modified during the transformation, as in the test case here, so that all nodes should be "as before"
> 2. A tree that is modified during the transformation, raising the issue of the positions of the new node and any enclosing node

I found what I think was the issue, and I've pushed an initial fix for it, which passes improved versions of existing tests.
I'll follow up with more tests and perhaps include your test case here as well; thanks for providing it.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1480710301

From jjg at openjdk.org  Wed Feb  7 00:34:04 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 7 Feb 2024 00:34:04 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v18]
In-Reply-To: <43UGpbzrBbISoThN_wch1kQQD0FYeWlAvaTM_pH6dTs=.4250aff5-cc0e-41e9-9a1b-f62fd8989b25@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <RIP-4xQbHyEjoPx-PHy-YFMYjq5xq1pjV5SCdVWbQNo=.c6fa9a51-39c3-4ef9-bfe9-1382b9bc016f@github.com>
 <l62YkgsxqBHwYu5AzzN6v-rMMuUARmbIOVdQnlEfQ4c=.5b166998-4f34-4526-96de-3a6ea9030c76@github.com>
 <UVXpzCUqXHCV4DX8cuZ35YSyGI5zWmqItEaxgtV4WVc=.563257a5-d67c-4d38-adf6-8b03b94de37c@github.com>
 <6EEwmjOExugvg9w74ZEhDGZ37af9ott0EdQfTPpU5i4=.2279f998-cf78-47ad-8ef7-8a0da0831be6@github.com>
 <43UGpbzrBbISoThN_wch1kQQD0FYeWlAvaTM_pH6dTs=.4250aff5-cc0e-41e9-9a1b-f62fd8989b25@github.com>
Message-ID: <ZCAy44_3fhDhjiKkwhwvAXwRLLN8jzVXxYpFjObedrY=.fe895cdf-352d-464b-8a56-5b73ab4465be@github.com>

On Wed, 7 Feb 2024 00:16:57 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> There are two cases that need consideration:
>> 1. A tree that is not modified during the transformation, as in the test case here, so that all nodes should be "as before"
>> 2. A tree that is modified during the transformation, raising the issue of the positions of the new node and any enclosing node
>
> I found what I think was the issue, and I've pushed an initial fix for it, which passes improved versions of existing tests.
> I'll follow up with more tests and perhaps include your test case here as well; thanks for providing it.

Update: I've added your test case, which now passes OK.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1480724330

From jjg at openjdk.org  Wed Feb  7 00:38:59 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 7 Feb 2024 00:38:59 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v21]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <QGBunllNXVQ5XgdRQtV0xjD5F47qn7r3S200rLsWAfs=.959af0c7-8cd7-4715-aad6-41f2a7053625@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  add test case contributed by @lahodaj

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/7c631688..5710c285

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=20
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=19-20

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

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

From abimpoudis at openjdk.org  Wed Feb  7 07:03:00 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Wed, 7 Feb 2024 07:03:00 GMT
Subject: Integrated: 8325257: jshell reports NoSuchFieldError with instanceof
 primitive type
In-Reply-To: <g7K6PelTU6m2rNVHVe_ep0jUmSpkH3j32bcFjZyXrUE=.11f5cc29-b924-4ebc-93dd-e937e556e55e@github.com>
References: <g7K6PelTU6m2rNVHVe_ep0jUmSpkH3j32bcFjZyXrUE=.11f5cc29-b924-4ebc-93dd-e937e556e55e@github.com>
Message-ID: <r__J87qeLczUrsYTbe3mb5903HPCiuwjQJ-rHpHhSoA=.d4b5b53c-da93-406a-b689-4c446fdfb731@github.com>

On Tue, 6 Feb 2024 10:50:08 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

> Fixed compiler bug during lowering of the type test, where the let expression was using the `expr` of the old `tree` and not of the translated one. The latter manifested as a JShell error. Added compiler test as well. e.g., 
> 
> 
> class $JShell$2 {
>     
>     $JShell$2() {
>         super();
>     }
>     public static boolean $1;
>     
>     public static Object do_it$() throws Throwable {
>         return Boolean.valueOf($1 = (let /*synthetic*/ final Object tmp184$ = $JShell$1.o 
>                                      in tmp184$ != null && o instanceof Long));                          
>                                                         // ^
>     }
> }

This pull request has now been integrated.

Changeset: e0d98dd3
Author:    Aggelos Biboudis <abimpoudis at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/e0d98dd3019b2fd6b95dd341296899dc0b470cb1
Stats:     22 lines in 3 files changed: 17 ins; 0 del; 5 mod

8325257: jshell reports NoSuchFieldError with instanceof primitive type

Reviewed-by: mcimadamore

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

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

From ihse at openjdk.org  Wed Feb  7 15:53:59 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Wed, 7 Feb 2024 15:53:59 GMT
Subject: RFR: 8325109: Sort method modifiers in canonical order
In-Reply-To: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
References: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
Message-ID: <AbyHgk1wHchuCkp0snusjEkqPmCzyc_IRaEbP8f9tNE=.eb528716-b511-4d83-a3a9-480f8487ff6d@github.com>

On Thu, 1 Feb 2024 11:57:04 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is a follow-up on [JDK-8324053](https://bugs.openjdk.org/browse/JDK-8324053). I have run the bin/blessed-modifier-order.sh on the entire code base, and manually checked the result. I have reverted all but these trivial and uncontroversial changes.
> 
> Almost all of these are about moving `static` to its proper position; a few do not involve `static` but instead puts `final` or `abstract` in the correct place.
> 
> I have deliberately stayed away from `default` in this PR, since they should probably get a more thorough treatment, see https://github.com/openjdk/jdk/pull/17468#pullrequestreview-1829238473.

Just to confirm publicly, there is no need for any special handling of `java.util.concurrent` any longer; the JDK repo is the single source of truth nowadays.

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

PR Comment: https://git.openjdk.org/jdk/pull/17670#issuecomment-1932335281

From ihse at openjdk.org  Wed Feb  7 15:53:59 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Wed, 7 Feb 2024 15:53:59 GMT
Subject: Integrated: 8325109: Sort method modifiers in canonical order
In-Reply-To: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
References: <BbICMGps3zSn7DLxe-b-MC7Uu4QDLRAlnz6BudkoyZA=.be51525d-91fb-4973-87fd-cbc2d6099754@github.com>
Message-ID: <xk3ADOyZQDY-sxr5Ph7VYQTzRabzGFg0kBCsVxThQro=.b8764313-7ea0-4939-93a5-8e9501b63756@github.com>

On Thu, 1 Feb 2024 11:57:04 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is a follow-up on [JDK-8324053](https://bugs.openjdk.org/browse/JDK-8324053). I have run the bin/blessed-modifier-order.sh on the entire code base, and manually checked the result. I have reverted all but these trivial and uncontroversial changes.
> 
> Almost all of these are about moving `static` to its proper position; a few do not involve `static` but instead puts `final` or `abstract` in the correct place.
> 
> I have deliberately stayed away from `default` in this PR, since they should probably get a more thorough treatment, see https://github.com/openjdk/jdk/pull/17468#pullrequestreview-1829238473.

This pull request has now been integrated.

Changeset: 18e24d06
Author:    Magnus Ihse Bursie <ihse at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/18e24d0619ffef7c6dbfc419105faba9f7ba1874
Stats:     61 lines in 39 files changed: 0 ins; 0 del; 61 mod

8325109: Sort method modifiers in canonical order

Reviewed-by: aivanov, rriggs, darcy, prappo

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

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

From jjg at openjdk.org  Wed Feb  7 18:05:58 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 7 Feb 2024 18:05:58 GMT
Subject: RFR: JDK-8325268: Add policy statement to langtools makefiles
 concerning warnings
In-Reply-To: <SDIA7FXQnkrauJHNBE5Ziz5YoRkEdYi5TTUZSKDAiYo=.85170a59-a6aa-4940-b5ad-3cdcdac8d6ab@github.com>
References: <SDIA7FXQnkrauJHNBE5Ziz5YoRkEdYi5TTUZSKDAiYo=.85170a59-a6aa-4940-b5ad-3cdcdac8d6ab@github.com>
Message-ID: <wiGEfp9dnvgvcfkOQc7qFPbkDmdGSocpHqMbO3q4vNc=.296dbbc6-d872-4ddc-a0ef-2189f9dbe05d@github.com>

On Tue, 6 Feb 2024 02:28:32 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Add policy statement about lint warnings to various langtools modules.

Marked as reviewed by jjg (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/17718#pullrequestreview-1868462643

From vromero at openjdk.org  Wed Feb  7 18:05:58 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Wed, 7 Feb 2024 18:05:58 GMT
Subject: RFR: JDK-8325268: Add policy statement to langtools makefiles
 concerning warnings
In-Reply-To: <SDIA7FXQnkrauJHNBE5Ziz5YoRkEdYi5TTUZSKDAiYo=.85170a59-a6aa-4940-b5ad-3cdcdac8d6ab@github.com>
References: <SDIA7FXQnkrauJHNBE5Ziz5YoRkEdYi5TTUZSKDAiYo=.85170a59-a6aa-4940-b5ad-3cdcdac8d6ab@github.com>
Message-ID: <7_cvctT07uXpZwxVt3BUnFdN7qbHuxYrhD-9wKBdGGg=.fcf5e6ab-bb66-4342-9fa0-a4b681c73bae@github.com>

On Tue, 6 Feb 2024 02:28:32 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Add policy statement about lint warnings to various langtools modules.

lgtm

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17718#pullrequestreview-1868464016

From darcy at openjdk.org  Wed Feb  7 18:05:59 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Wed, 7 Feb 2024 18:05:59 GMT
Subject: Integrated: JDK-8325268: Add policy statement to langtools makefiles
 concerning warnings
In-Reply-To: <SDIA7FXQnkrauJHNBE5Ziz5YoRkEdYi5TTUZSKDAiYo=.85170a59-a6aa-4940-b5ad-3cdcdac8d6ab@github.com>
References: <SDIA7FXQnkrauJHNBE5Ziz5YoRkEdYi5TTUZSKDAiYo=.85170a59-a6aa-4940-b5ad-3cdcdac8d6ab@github.com>
Message-ID: <X7jJ7y0V9PgToIy8MRYLrn7Aw_6oG3TzvKkA6Hgq5qQ=.16dee8a3-9375-4cee-9cc6-46cb7765afcb@github.com>

On Tue, 6 Feb 2024 02:28:32 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Add policy statement about lint warnings to various langtools modules.

This pull request has now been integrated.

Changeset: 3a1f4d0f
Author:    Joe Darcy <darcy at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/3a1f4d0f484f4c68e240ca3f2f36730805ee7dc0
Stats:     14 lines in 3 files changed: 12 ins; 0 del; 2 mod

8325268: Add policy statement to langtools makefiles concerning warnings

Reviewed-by: ihse, jjg, vromero

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

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

From jjg at openjdk.org  Wed Feb  7 18:14:24 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 7 Feb 2024 18:14:24 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <vrwe2U_b9K6EUSg760EHhm3x7sz2tp0D4thYIqknnGw=.e5c1c331-644a-4473-8a8b-d3c8f3128303@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 28 commits:

 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it
   merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.
 - add test case contributed by @lahodaj
 - initial fix for source offset problem
 - remove unused imports
 - First pass at remove DocCommentTransformer from the public API.
   
   It is still declared internally, and installed by default, using the service-provider mechanism.
   If the standard impl is not available, an identity transformer is used.
 - updates for "first sentence" issues and tests
 - add info about provenance of `jdk.internal.md` module
 - MarkdownTransformer: tweak doc comments
 - MarkdownTransformer: change `Lower.replaceIter` to be `private final`
 - MarkdownTransformer: use suggested text for using streams
 - ... and 18 more: https://git.openjdk.org/jdk/compare/18e24d06...63dd8bf4

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

Changes: https://git.openjdk.org/jdk/pull/16388/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=21
  Stats: 21713 lines in 193 files changed: 21042 ins; 274 del; 397 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From darcy at openjdk.org  Wed Feb  7 20:51:01 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Wed, 7 Feb 2024 20:51:01 GMT
Subject: RFR: JDK-8306819: Consider disabling the compiler's default active
 annotation processing [v7]
In-Reply-To: <0ivEYgoQy4gJIr7CoDx3QBUHvvZMyWLCDcF1IRkfmAc=.180db207-0f3c-4f1f-98af-d849432092b6@github.com>
References: <2iXdVG-MCaakXx5C5y01mcOFxJNEhoG4o2Fi_KlK8Co=.b500ce4e-7c4b-4d30-b489-f338f86f8af8@github.com>
 <nMq4Z3CRz7EPasRmnRcFhnXVLOIkvRjEh0mIj0N5nrs=.87d415f0-c379-49cc-a206-e5c34f8a3052@github.com>
 <Bh2E5JDkTcJhYAFH8lWllkjU9Q3BeKvtyEhf1dVpCU8=.54e720fe-033e-4f02-8c4a-b5a5a223c50c@github.com>
 <7AZJ2h8t-7ZCSTPvPNYpqj_GtG1vjsbVJO5HSpIXwHg=.cb84a0a8-8a13-4987-9bf4-84b12fabb614@github.com>
 <_wWk94od4ReNUx9KM1vOWlWcnw9Q_pO6Wdns-FDleL4=.cf37d33e-32c9-40f5-8f82-5a5443714904@github.com>
 <0ivEYgoQy4gJIr7CoDx3QBUHvvZMyWLCDcF1IRkfmAc=.180db207-0f3c-4f1f-98af-d849432092b6@github.com>
Message-ID: <OAlphPvxBVd-sN1iNpovq-Gwyu8VBBvS9d6gUsdsCH4=.d7d32f66-88e2-4030-827e-e52a3df41737@github.com>

On Thu, 26 Oct 2023 17:34:02 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> > > there need not be any flag day for changing to JDK 22 specifically since the option to request the old policy is accepted in JDK 21
> > 
> > 
> > Just to say, most of our libs build against **11, 17, 21 and EA/22**. So for this reason our projects we can't trivially make use of `-proc:full` introduced in 21 as that fails the builds using 11 and 17 and instead we needed to introduce build profiles for this.
> 
> Noted; thanks.

PS Support for -proc:full has been backported to Oracle's 17u, 11u, and 8u release trains ([JDK-8321416](https://bugs.openjdk.org/browse/JDK-8321416), [JDK-8321418](https://bugs.openjdk.org/browse/JDK-8321418), [JDK-8321419](https://bugs.openjdk.org/browse/JDK-8321419)) as well as the OpenJDK 17u and 11u release trains ([JDK-8324670](https://bugs.openjdk.org/browse/JDK-8324670), [JDK-8324804](https://bugs.openjdk.org/browse/JDK-8324804)). The feature is on track to appear in the April 2024 set of releases.

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

PR Comment: https://git.openjdk.org/jdk/pull/14432#issuecomment-1932839886

From jlahoda at openjdk.org  Wed Feb  7 21:11:05 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Wed, 7 Feb 2024 21:11:05 GMT
Subject: RFR: 8325440: Confusing error reported for octal literals with wrong
 digits
Message-ID: <DOj5xpfhfbWrdLnt_1ltgBQcTZN1pyDSmw4ydeZVe8w=.2b87a8d6-dcd6-4765-97b6-5d58e4732609@github.com>

Consider code like:

    int i = 08;


Currently, javac will produce an error like:

/tmp/Octal.java:2: error: ';' expected
    int i = 08;
             ^


Which is fairly confusing. The cause is that this gets lexed as two tokens: `0` and `8`, as `8` is not a valid digit for an octal literal. The current behavior is a consequence of:
https://bugs.openjdk.org/browse/JDK-8267361

Before that fix, the error was:

/tmp/Octal.java:2: error: integer number too large
    int i = 08;
            ^


which was not better.

Please see the original PR:
https://github.com/openjdk/jdk/pull/4111
for more information on the decision there.

It seems to me that it would be better to have an error pinpointing the problem (i.e. wrong digit in what is the octal literal). Which is what this patch is trying to do. It would be possible to do that in the lexer, but that is slightly complex. So, this patch:
- permits non-octal (and non-binary) digits in octal (and binary) literals, while still preserving the fact the literals are octal (binary)
- when the parser tries to convert the textual literal representation to a number, and fails to do that, get a `NumberFormatException`. The handling of this exception is improved to provide better errors.

Note that, for consistency, this patch works not only for octal literals (which is likely the most problematic case in practice), but also for binary literals, although it seems relatively unlikely code would contain literals like `0b123` (unlike `08`, which may be a simple mistake).

The new error is:

/tmp/Octal.java:2: error: illegal digit in an octal literal
    int i = 08;
             ^


(the error message can be re-phrased as needed/desired, of course.)

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

Commit messages:
 - Fixing test
 - Adding support for incorrect binary literals.
 - 8325440: Confusing error reported for octal literals with wrong digits

Changes: https://git.openjdk.org/jdk/pull/17760/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17760&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325440
  Stats: 70 lines in 9 files changed: 36 ins; 10 del; 24 mod
  Patch: https://git.openjdk.org/jdk/pull/17760.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17760/head:pull/17760

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

From darcy at openjdk.org  Thu Feb  8 02:07:56 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Thu, 8 Feb 2024 02:07:56 GMT
Subject: RFR: 8325440: Confusing error reported for octal literals with
 wrong digits
In-Reply-To: <DOj5xpfhfbWrdLnt_1ltgBQcTZN1pyDSmw4ydeZVe8w=.2b87a8d6-dcd6-4765-97b6-5d58e4732609@github.com>
References: <DOj5xpfhfbWrdLnt_1ltgBQcTZN1pyDSmw4ydeZVe8w=.2b87a8d6-dcd6-4765-97b6-5d58e4732609@github.com>
Message-ID: <fbvZzRkygO9I3vY9vDipRxBMhSyF0lLDiiezIbHpeHA=.173a1f9a-2f38-4d49-8e03-fcb36391f949@github.com>

On Wed, 7 Feb 2024 21:06:47 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Consider code like:
> 
>     int i = 08;
> 
> 
> Currently, javac will produce an error like:
> 
> /tmp/Octal.java:2: error: ';' expected
>     int i = 08;
>              ^
> 
> 
> Which is fairly confusing. The cause is that this gets lexed as two tokens: `0` and `8`, as `8` is not a valid digit for an octal literal. The current behavior is a consequence of:
> https://bugs.openjdk.org/browse/JDK-8267361
> 
> Before that fix, the error was:
> 
> /tmp/Octal.java:2: error: integer number too large
>     int i = 08;
>             ^
> 
> 
> which was not better.
> 
> Please see the original PR:
> https://github.com/openjdk/jdk/pull/4111
> for more information on the decision there.
> 
> It seems to me that it would be better to have an error pinpointing the problem (i.e. wrong digit in what is the octal literal). Which is what this patch is trying to do. It would be possible to do that in the lexer, but that is slightly complex. So, this patch:
> - permits non-octal (and non-binary) digits in octal (and binary) literals, while still preserving the fact the literals are octal (binary)
> - when the parser tries to convert the textual literal representation to a number, and fails to do that, get a `NumberFormatException`. The handling of this exception is improved to provide better errors.
> 
> Note that, for consistency, this patch works not only for octal literals (which is likely the most problematic case in practice), but also for binary literals, although it seems relatively unlikely code would contain literals like `0b123` (unlike `08`, which may be a simple mistake).
> 
> The new error is:
> 
> /tmp/Octal.java:2: error: illegal digit in an octal literal
>     int i = 08;
>              ^
> 
> 
> (the error message can be re-phrased as needed/desired, of course.)

src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties line 744:

> 742: 
> 743: compiler.err.illegal.digit.in.binary.literal=\
> 744:     illegal digit in an binary literal

Typo: should be "a binary literal" rather than "an binary literal".

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17760#discussion_r1482326153

From jlahoda at openjdk.org  Thu Feb  8 09:13:11 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Thu, 8 Feb 2024 09:13:11 GMT
Subject: RFR: 8325440: Confusing error reported for octal literals with
 wrong digits [v2]
In-Reply-To: <DOj5xpfhfbWrdLnt_1ltgBQcTZN1pyDSmw4ydeZVe8w=.2b87a8d6-dcd6-4765-97b6-5d58e4732609@github.com>
References: <DOj5xpfhfbWrdLnt_1ltgBQcTZN1pyDSmw4ydeZVe8w=.2b87a8d6-dcd6-4765-97b6-5d58e4732609@github.com>
Message-ID: <Lyknzobau8RJ_BKU30KmpupLwV9QXxn7OQgJ_3NaeeQ=.0385588f-e042-4ece-8024-9bc80cb31dad@github.com>

> Consider code like:
> 
>     int i = 08;
> 
> 
> Currently, javac will produce an error like:
> 
> /tmp/Octal.java:2: error: ';' expected
>     int i = 08;
>              ^
> 
> 
> Which is fairly confusing. The cause is that this gets lexed as two tokens: `0` and `8`, as `8` is not a valid digit for an octal literal. The current behavior is a consequence of:
> https://bugs.openjdk.org/browse/JDK-8267361
> 
> Before that fix, the error was:
> 
> /tmp/Octal.java:2: error: integer number too large
>     int i = 08;
>             ^
> 
> 
> which was not better.
> 
> Please see the original PR:
> https://github.com/openjdk/jdk/pull/4111
> for more information on the decision there.
> 
> It seems to me that it would be better to have an error pinpointing the problem (i.e. wrong digit in what is the octal literal). Which is what this patch is trying to do. It would be possible to do that in the lexer, but that is slightly complex. So, this patch:
> - permits non-octal (and non-binary) digits in octal (and binary) literals, while still preserving the fact the literals are octal (binary)
> - when the parser tries to convert the textual literal representation to a number, and fails to do that, get a `NumberFormatException`. The handling of this exception is improved to provide better errors.
> 
> Note that, for consistency, this patch works not only for octal literals (which is likely the most problematic case in practice), but also for binary literals, although it seems relatively unlikely code would contain literals like `0b123` (unlike `08`, which may be a simple mistake).
> 
> The new error is:
> 
> /tmp/Octal.java:2: error: illegal digit in an octal literal
>     int i = 08;
>              ^
> 
> 
> (the error message can be re-phrased as needed/desired, of course.)

Jan Lahoda has updated the pull request incrementally with one additional commit since the last revision:

  Fixing typo.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17760/files
  - new: https://git.openjdk.org/jdk/pull/17760/files/8d20415e..4fc4b63b

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17760&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17760&range=00-01

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

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

From jlahoda at openjdk.org  Thu Feb  8 09:13:12 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Thu, 8 Feb 2024 09:13:12 GMT
Subject: RFR: 8325440: Confusing error reported for octal literals with
 wrong digits [v2]
In-Reply-To: <fbvZzRkygO9I3vY9vDipRxBMhSyF0lLDiiezIbHpeHA=.173a1f9a-2f38-4d49-8e03-fcb36391f949@github.com>
References: <DOj5xpfhfbWrdLnt_1ltgBQcTZN1pyDSmw4ydeZVe8w=.2b87a8d6-dcd6-4765-97b6-5d58e4732609@github.com>
 <fbvZzRkygO9I3vY9vDipRxBMhSyF0lLDiiezIbHpeHA=.173a1f9a-2f38-4d49-8e03-fcb36391f949@github.com>
Message-ID: <hcnXRWhU8CJDLbqUY-DCwORWUVaYOi4Lm8ShgOi-p5g=.03a94980-350f-4e9b-a49a-62eda36d5b47@github.com>

On Thu, 8 Feb 2024 02:05:35 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> Jan Lahoda has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fixing typo.
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties line 744:
> 
>> 742: 
>> 743: compiler.err.illegal.digit.in.binary.literal=\
>> 744:     illegal digit in an binary literal
> 
> Typo: should be "a binary literal" rather than "an binary literal".

Oops. Fixed, thanks!

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17760#discussion_r1482635712

From abimpoudis at openjdk.org  Thu Feb  8 14:35:32 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Thu, 8 Feb 2024 14:35:32 GMT
Subject: RFR: 8314275: Incorrect stepping in switch
Message-ID: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>

In code like the one below, the observable effect was that if the user debugs the following method, `multiply` called with `1`, the debugger steps from line 4 to line 6 (instead of 7) giving the impression that line 6 is going to be executed. The reason is that the `LineNumberTable` did not include an entry at the end of the `switch` mapping the statement that follows, to bytecode.


1 private static double multiply(Integer i) { 
2   double cr = 15;                              
3    cr = switch (i) {                            
4        case 1 -> cr * 1;                       
5        case 2 -> cr * 2;                      
6        default -> cr * 4;                     
7    };                                           
8    return cr;                              
9 }

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

Commit messages:
 - 8314275: Incorrect stepping in switch

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

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

From abimpoudis at openjdk.org  Thu Feb  8 14:57:16 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Thu, 8 Feb 2024 14:57:16 GMT
Subject: RFR: 8314275: Incorrect stepping in switch [v2]
In-Reply-To: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
References: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
Message-ID: <fa7y4gjVsQ2CZZsAf47MBnIUQlzphoZpFPU2R6zdTZo=.917e6da5-d176-4640-b4ce-9e75dee1207c@github.com>

> In code like the one below, the observable effect was that if the user debugs the following method, `multiply` called with `1`, the debugger steps from line 4 to line 6 (instead of 7) giving the impression that line 6 is going to be executed. The reason is that the `LineNumberTable` did not include an entry at the end of the `switch` mapping the statement that follows, to bytecode.
> 
> 
> 1 private static double multiply(Integer i) { 
> 2   double cr = 15;                              
> 3    cr = switch (i) {                            
> 4        case 1 -> cr * 1;                       
> 5        case 2 -> cr * 2;                      
> 6        default -> cr * 4;                     
> 7    };                                           
> 8    return cr;                              
> 9 }

Aggelos Biboudis 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 two additional commits since the last revision:

 - Merge branch 'master' into fix-#8314275
 - 8314275: Incorrect stepping in switch

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17772/files
  - new: https://git.openjdk.org/jdk/pull/17772/files/2512d10f..682802c5

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17772&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17772&range=00-01

  Stats: 1895 lines in 190 files changed: 1430 ins; 76 del; 389 mod
  Patch: https://git.openjdk.org/jdk/pull/17772.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17772/head:pull/17772

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

From vromero at openjdk.org  Thu Feb  8 16:23:55 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Thu, 8 Feb 2024 16:23:55 GMT
Subject: RFR: 8314275: Incorrect stepping in switch [v2]
In-Reply-To: <fa7y4gjVsQ2CZZsAf47MBnIUQlzphoZpFPU2R6zdTZo=.917e6da5-d176-4640-b4ce-9e75dee1207c@github.com>
References: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
 <fa7y4gjVsQ2CZZsAf47MBnIUQlzphoZpFPU2R6zdTZo=.917e6da5-d176-4640-b4ce-9e75dee1207c@github.com>
Message-ID: <KZF3mEXf0j8WMV-b0Y42jH7UpQqAUoqbTbjQdszVpsA=.336f96d9-e55e-4dbe-b28b-a9c70475e278@github.com>

On Thu, 8 Feb 2024 14:57:16 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

>> In code like the one below, the observable effect was that if the user debugs the following method, `multiply` called with `1`, the debugger steps from line 4 to line 6 (instead of 7) giving the impression that line 6 is going to be executed. The reason is that the `LineNumberTable` did not include an entry at the end of the `switch` mapping the statement that follows, to bytecode.
>> 
>> 
>> 1 private static double multiply(Integer i) { 
>> 2   double cr = 15;                              
>> 3    cr = switch (i) {                            
>> 4        case 1 -> cr * 1;                       
>> 5        case 2 -> cr * 2;                      
>> 6        default -> cr * 4;                     
>> 7    };                                           
>> 8    return cr;                              
>> 9 }
>
> Aggelos Biboudis 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 two additional commits since the last revision:
> 
>  - Merge branch 'master' into fix-#8314275
>  - 8314275: Incorrect stepping in switch

looks good, just a minor comment

src/jdk.compiler/share/classes/com/sun/tools/javac/jvm/Gen.java line 1433:

> 1431: 
> 1432:             // Emit line position for the end of the switch
> 1433:             code.statBegin(TreeInfo.endPos(swtch));

shouldn't this change affect already existing tests like: RuleSwitchBreaks.java in the same folder: test/langtools/tools/javac/classfiles/attributes/LineNumberTable/?

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17772#pullrequestreview-1870690309
PR Review Comment: https://git.openjdk.org/jdk/pull/17772#discussion_r1483253681

From abimpoudis at openjdk.org  Thu Feb  8 16:31:07 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Thu, 8 Feb 2024 16:31:07 GMT
Subject: RFR: 8314275: Incorrect stepping in switch [v2]
In-Reply-To: <KZF3mEXf0j8WMV-b0Y42jH7UpQqAUoqbTbjQdszVpsA=.336f96d9-e55e-4dbe-b28b-a9c70475e278@github.com>
References: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
 <fa7y4gjVsQ2CZZsAf47MBnIUQlzphoZpFPU2R6zdTZo=.917e6da5-d176-4640-b4ce-9e75dee1207c@github.com>
 <KZF3mEXf0j8WMV-b0Y42jH7UpQqAUoqbTbjQdszVpsA=.336f96d9-e55e-4dbe-b28b-a9c70475e278@github.com>
Message-ID: <3Tqlfnm1pGWscC7p-RsqmjIfWw80qxUUiYxwnW7wVeI=.faf09e60-79f0-4353-be4f-044b3678f59b@github.com>

On Thu, 8 Feb 2024 16:21:23 GMT, Vicente Romero <vromero at openjdk.org> wrote:

>> Aggelos Biboudis 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 two additional commits since the last revision:
>> 
>>  - Merge branch 'master' into fix-#8314275
>>  - 8314275: Incorrect stepping in switch
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/jvm/Gen.java line 1433:
> 
>> 1431: 
>> 1432:             // Emit line position for the end of the switch
>> 1433:             code.statBegin(TreeInfo.endPos(swtch));
> 
> shouldn't this change affect already existing tests like: RuleSwitchBreaks.java in the same folder: test/langtools/tools/javac/classfiles/attributes/LineNumberTable/?

I see what you mean. Those switches do not store their value (no store bytecode is emitted). This is why they didn't fail I presume. Do you think there is a discrepancy between how we compile the code in the two tests regarding `LineNumberTable`?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17772#discussion_r1483263599

From prappo at openjdk.org  Thu Feb  8 16:33:13 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 8 Feb 2024 16:33:13 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
In-Reply-To: <vrwe2U_b9K6EUSg760EHhm3x7sz2tp0D4thYIqknnGw=.e5c1c331-644a-4473-8a8b-d3c8f3128303@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <vrwe2U_b9K6EUSg760EHhm3x7sz2tp0D4thYIqknnGw=.e5c1c331-644a-4473-8a8b-d3c8f3128303@github.com>
Message-ID: <twtI7_ifT_3pTl3f8YtW1l-AX_H7EzZfj4EsXY1rFUA=.727894b4-c49f-4ccc-8eda-0f8ef82cdbfd@github.com>

On Wed, 7 Feb 2024 18:14:24 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 28 commits:
> 
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it
>    merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.
>  - add test case contributed by @lahodaj
>  - initial fix for source offset problem
>  - remove unused imports
>  - First pass at remove DocCommentTransformer from the public API.
>    
>    It is still declared internally, and installed by default, using the service-provider mechanism.
>    If the standard impl is not available, an identity transformer is used.
>  - updates for "first sentence" issues and tests
>  - add info about provenance of `jdk.internal.md` module
>  - MarkdownTransformer: tweak doc comments
>  - MarkdownTransformer: change `Lower.replaceIter` to be `private final`
>  - MarkdownTransformer: use suggested text for using streams
>  - ... and 18 more: https://git.openjdk.org/jdk/compare/18e24d06...63dd8bf4

Jon, here are a few reminders and misc comments.

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

PR Review: https://git.openjdk.org/jdk/pull/16388#pullrequestreview-1846272367

From prappo at openjdk.org  Thu Feb  8 16:33:14 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 8 Feb 2024 16:33:14 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
Message-ID: <MDprROiV35Q1rjuL_TD_cFkhYEGkN2B-xuH3eRcz0e0=.878238df-e7fd-4054-918b-17f77a5a4ecd@github.com>

On Fri, 19 Jan 2024 18:37:48 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains eight commits:
> 
>  - Merge with upstream/master
>  - Merge with upstream/master
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>  - Address review comments
>  - Fix whitespace
>  - Improve handling of embedded inline taglets
>  - Customize support for Markdown headings
>  - JDK-8298405: Support Markdown in Documentation Comments

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlConfiguration.java line 329:

> 327:         if (doclint == null) {
> 328:             var trees = docEnv.getDocTrees();
> 329:             if (trees.getDocCommentTreeTransformer()== null) {

Suggestion:

            if (trees.getDocCommentTreeTransformer() == null) {

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java line 145:

> 143:     }
> 144: 
> 145:     Pattern tag = Pattern.compile("<(?<tag>[A-Za-z0-9]+)(\\s|>)");

I'm not sure I grok this pattern; what's up with `\\s`?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java line 629:

> 627:     public DocCommentTree parse(URI uri, String text) {
> 628:         return trees.getDocCommentTree(new SimpleJavaFileObject(
> 629:                 uri, JavaFileObject.Kind.HTML) {

Was it a bug before?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Env.java line 139:

> 137:         this.types = types;
> 138: 
> 139:         if (this.trees.getDocCommentTreeTransformer()== null) {

Suggestion:

        if (this.trees.getDocCommentTreeTransformer() == null) {

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1467988621
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1467977203
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1467980609
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1467982493

From prappo at openjdk.org  Thu Feb  8 16:33:14 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 8 Feb 2024 16:33:14 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
In-Reply-To: <bZq6pPTdtcJayLOFPeVpL2lth3zrxQFh7MVhw_RnD8Q=.13043746-8c61-474d-93b5-44743733441d@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <bZq6pPTdtcJayLOFPeVpL2lth3zrxQFh7MVhw_RnD8Q=.13043746-8c61-474d-93b5-44743733441d@github.com>
Message-ID: <vpCR8ztMJ6THwioLqFcmf_XaoBfgGU8hESSITzaZDgg=.e3ccf661-eff8-41e9-b203-a58d369ec710@github.com>

On Wed, 8 Nov 2023 17:17:46 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 28 commits:
>> 
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it
>>    merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.
>>  - add test case contributed by @lahodaj
>>  - initial fix for source offset problem
>>  - remove unused imports
>>  - First pass at remove DocCommentTransformer from the public API.
>>    
>>    It is still declared internally, and installed by default, using the service-provider mechanism.
>>    If the standard impl is not available, an identity transformer is used.
>>  - updates for "first sentence" issues and tests
>>  - add info about provenance of `jdk.internal.md` module
>>  - MarkdownTransformer: tweak doc comments
>>  - MarkdownTransformer: change `Lower.replaceIter` to be `private final`
>>  - MarkdownTransformer: use suggested text for using streams
>>  - ... and 18 more: https://git.openjdk.org/jdk/compare/18e24d06...63dd8bf4
>
> test/langtools/jdk/javadoc/tool/sampleapi/lib/sampleapi/generator/ModuleGenerator.java line 49:
> 
>> 47: import sampleapi.util.PoorDocCommentTable;
>> 48: 
>> 49: import static com.sun.tools.javac.parser.Tokens.Comment.CommentStyle.JAVADOC;
> 
> To clarify, the change to this file is that you removed two unused imports, right?

Ping. Maybe if it is not essential, we could remove that change, to keep PR more focused.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483182361

From prappo at openjdk.org  Thu Feb  8 16:33:15 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 8 Feb 2024 16:33:15 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
In-Reply-To: <3N5guZn5SiRlcjZrWQt0JbqUMJr79EcQ999JpVtx8-k=.cf3f71c3-4fcb-4958-b673-76b6b9797cd5@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <bZq6pPTdtcJayLOFPeVpL2lth3zrxQFh7MVhw_RnD8Q=.13043746-8c61-474d-93b5-44743733441d@github.com>
 <3N5guZn5SiRlcjZrWQt0JbqUMJr79EcQ999JpVtx8-k=.cf3f71c3-4fcb-4958-b673-76b6b9797cd5@github.com>
Message-ID: <aRyFeUB0t9pLvRy-awz2Kr2gh1RDsiB0YGsuWTSItCQ=.b313e672-413f-46af-b95f-8d87707a8d70@github.com>

On Thu, 11 Jan 2024 15:07:33 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> test/langtools/tools/javac/classfiles/attributes/deprecated/DeprecatedTest.java line 26:
>> 
>>> 24: /*
>>> 25:  * @test
>>> 26:  * @bug 8042261 8298405
>> 
>> This comment is not for this line, but for two compiler tests for `@deprecated` javadoc tag. It seemed quite contextual place to put it.
>> 
>> Did I miss it, or you are planning to add a javadoc test that verifies that `@deprecated` appearing in a `///` comment has no [special meaning] it has in classic `/** */` comments?
>> 
>> [special meaning]: https://github.com/openjdk/jdk/blob/128363bf3b57dfa05b3807271b47851733c1afb9/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java#L1639-L1653
>
> Ping. I do believe that it's important to have such a test.

Ping.

>> test/langtools/tools/javac/doctree/DocCommentTester.java line 1012:
>> 
>>> 1010: //            }
>>> 1011: //            return null;
>>> 1012: //        }
>> 
>> Debugging leftover?
>
> If you want to leave it for debugging you can make it private and uncomment.

Ping.

>> test/langtools/tools/javac/doctree/MarkdownTest.java line 555:
>> 
>>> 553: //  block tags: empty
>>> 554: //]
>>> 555: //*/
>> 
>> Just to clarify: it is supposed to be commented out, right? If uncommented, this test fails with a slightly different error.
>
> Please update the DocComment printout in that commented out test: the actual content is different. It would be nice if the test were passing at least at the moment of its initial commit.
> 
> Here's what I see locally:
> 
> 
> Expect:
> DocComment[DOC_COMMENT, pos:0
>   firstSentence: 1
>     Summary[SUMMARY, pos:4
>       summary: 1
>         Erroneous[ERRONEOUS, pos:14, prefPos:37
>           code: compiler.err.dc.unterminated.inline.tag
>           body: abc_`|_def}|_rest_`more`
>         ]
>     ]
>   body: empty
>   block tags: empty
> ]
> 
> Found:
> DocComment[DOC_COMMENT, pos:0
>   firstSentence: 1
>     Summary[SUMMARY, pos:1
>       summary: 1
>         Erroneous[ERRONEOUS, pos:11, prefPos:32
>           code: compiler.err.dc.unterminated.inline.tag
>           body: abc_`|def}|rest_`more`
>         ]
>     ]
>   body: empty
>   block tags: empty
> ]

Ping.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483179667
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483179302
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483178073

From vromero at openjdk.org  Thu Feb  8 16:58:07 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Thu, 8 Feb 2024 16:58:07 GMT
Subject: RFR: 8314275: Incorrect stepping in switch [v2]
In-Reply-To: <3Tqlfnm1pGWscC7p-RsqmjIfWw80qxUUiYxwnW7wVeI=.faf09e60-79f0-4353-be4f-044b3678f59b@github.com>
References: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
 <fa7y4gjVsQ2CZZsAf47MBnIUQlzphoZpFPU2R6zdTZo=.917e6da5-d176-4640-b4ce-9e75dee1207c@github.com>
 <KZF3mEXf0j8WMV-b0Y42jH7UpQqAUoqbTbjQdszVpsA=.336f96d9-e55e-4dbe-b28b-a9c70475e278@github.com>
 <3Tqlfnm1pGWscC7p-RsqmjIfWw80qxUUiYxwnW7wVeI=.faf09e60-79f0-4353-be4f-044b3678f59b@github.com>
Message-ID: <nQcR5u1LzqekJdidNaWj0B3Cn4iIztGF8EmykfjLleI=.ccb69c35-bece-45fd-9204-c3022a70cdf8@github.com>

On Thu, 8 Feb 2024 16:27:25 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/jvm/Gen.java line 1433:
>> 
>>> 1431: 
>>> 1432:             // Emit line position for the end of the switch
>>> 1433:             code.statBegin(TreeInfo.endPos(swtch));
>> 
>> shouldn't this change affect already existing tests like: RuleSwitchBreaks.java in the same folder: test/langtools/tools/javac/classfiles/attributes/LineNumberTable/?
>
> I see what you mean. Those switches do not store their value (no store bytecode is emitted). This is why they didn't fail I presume. Do you think there is a discrepancy between how we compile the code in the two tests regarding `LineNumberTable`?

no I was just wondering why the issue didn't appear in the previous test, but what you are saying could be the explanation

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17772#discussion_r1483301578

From abimpoudis at openjdk.org  Thu Feb  8 17:03:20 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Thu, 8 Feb 2024 17:03:20 GMT
Subject: RFR: 8314275: Incorrect stepping in switch [v3]
In-Reply-To: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
References: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
Message-ID: <ntb0J5hmHOKI7B409GXM412Ttmt84XjYu7ntQ_MRQuI=.2a7f3f72-7a84-4f30-8754-ae2ec86de436@github.com>

> In code like the one below, the observable effect was that if the user debugs the following method, `multiply` called with `1`, the debugger steps from line 4 to line 6 (instead of 7) giving the impression that line 6 is going to be executed. The reason is that the `LineNumberTable` did not include an entry at the end of the `switch` mapping the statement that follows, to bytecode.
> 
> 
> 1 private static double multiply(Integer i) { 
> 2   double cr = 15;                              
> 3    cr = switch (i) {                            
> 4        case 1 -> cr * 1;                       
> 5        case 2 -> cr * 2;                      
> 6        default -> cr * 4;                     
> 7    };                                           
> 8    return cr;                              
> 9 }

Aggelos Biboudis has updated the pull request incrementally with one additional commit since the last revision:

  Ensure fix is effective for switch expressions only

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17772/files
  - new: https://git.openjdk.org/jdk/pull/17772/files/682802c5..a836d976

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17772&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17772&range=01-02

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

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

From abimpoudis at openjdk.org  Thu Feb  8 17:03:21 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Thu, 8 Feb 2024 17:03:21 GMT
Subject: RFR: 8314275: Incorrect stepping in switch [v2]
In-Reply-To: <nQcR5u1LzqekJdidNaWj0B3Cn4iIztGF8EmykfjLleI=.ccb69c35-bece-45fd-9204-c3022a70cdf8@github.com>
References: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
 <fa7y4gjVsQ2CZZsAf47MBnIUQlzphoZpFPU2R6zdTZo=.917e6da5-d176-4640-b4ce-9e75dee1207c@github.com>
 <KZF3mEXf0j8WMV-b0Y42jH7UpQqAUoqbTbjQdszVpsA=.336f96d9-e55e-4dbe-b28b-a9c70475e278@github.com>
 <3Tqlfnm1pGWscC7p-RsqmjIfWw80qxUUiYxwnW7wVeI=.faf09e60-79f0-4353-be4f-044b3678f59b@github.com>
 <nQcR5u1LzqekJdidNaWj0B3Cn4iIztGF8EmykfjLleI=.ccb69c35-bece-45fd-9204-c3022a70cdf8@github.com>
Message-ID: <4igTd3bEWa9fq1xROHxxG2XNmwI-KbXHNPWLuquMIQg=.6712fb90-fae3-461f-b1cd-bf0cc5004c15@github.com>

On Thu, 8 Feb 2024 16:55:45 GMT, Vicente Romero <vromero at openjdk.org> wrote:

>> I see what you mean. Those switches do not store their value (no store bytecode is emitted). This is why they didn't fail I presume. Do you think there is a discrepancy between how we compile the code in the two tests regarding `LineNumberTable`?
>
> no I was just wondering why the issue didn't appear in the previous test, but what you are saying could be the explanation

What do you think about this? https://github.com/openjdk/jdk/pull/17772/commits/a836d976e56c624882ae793ee89b1146c9fd4352

(also notice the newly added test case. For the `switch` statement the line 8 is not included and for the `switch` expression it is.)

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17772#discussion_r1483308140

From vromero at openjdk.org  Thu Feb  8 17:15:02 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Thu, 8 Feb 2024 17:15:02 GMT
Subject: RFR: 8325440: Confusing error reported for octal literals with
 wrong digits [v2]
In-Reply-To: <Lyknzobau8RJ_BKU30KmpupLwV9QXxn7OQgJ_3NaeeQ=.0385588f-e042-4ece-8024-9bc80cb31dad@github.com>
References: <DOj5xpfhfbWrdLnt_1ltgBQcTZN1pyDSmw4ydeZVe8w=.2b87a8d6-dcd6-4765-97b6-5d58e4732609@github.com>
 <Lyknzobau8RJ_BKU30KmpupLwV9QXxn7OQgJ_3NaeeQ=.0385588f-e042-4ece-8024-9bc80cb31dad@github.com>
Message-ID: <zXtiZ-cWHo8rV0aUP6bjOh1xoIFLhUrnWwtgsPqw1uc=.e293fa50-1744-4998-842b-800f29ea94f3@github.com>

On Thu, 8 Feb 2024 09:13:11 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

>> Consider code like:
>> 
>>     int i = 08;
>> 
>> 
>> Currently, javac will produce an error like:
>> 
>> /tmp/Octal.java:2: error: ';' expected
>>     int i = 08;
>>              ^
>> 
>> 
>> Which is fairly confusing. The cause is that this gets lexed as two tokens: `0` and `8`, as `8` is not a valid digit for an octal literal. The current behavior is a consequence of:
>> https://bugs.openjdk.org/browse/JDK-8267361
>> 
>> Before that fix, the error was:
>> 
>> /tmp/Octal.java:2: error: integer number too large
>>     int i = 08;
>>             ^
>> 
>> 
>> which was not better.
>> 
>> Please see the original PR:
>> https://github.com/openjdk/jdk/pull/4111
>> for more information on the decision there.
>> 
>> It seems to me that it would be better to have an error pinpointing the problem (i.e. wrong digit in what is the octal literal). Which is what this patch is trying to do. It would be possible to do that in the lexer, but that is slightly complex. So, this patch:
>> - permits non-octal (and non-binary) digits in octal (and binary) literals, while still preserving the fact the literals are octal (binary)
>> - when the parser tries to convert the textual literal representation to a number, and fails to do that, get a `NumberFormatException`. The handling of this exception is improved to provide better errors.
>> 
>> Note that, for consistency, this patch works not only for octal literals (which is likely the most problematic case in practice), but also for binary literals, although it seems relatively unlikely code would contain literals like `0b123` (unlike `08`, which may be a simple mistake).
>> 
>> The new error is:
>> 
>> /tmp/Octal.java:2: error: illegal digit in an octal literal
>>     int i = 08;
>>              ^
>> 
>> 
>> (the error message can be re-phrased as needed/desired, of course.)
>
> Jan Lahoda has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fixing typo.

lgtm

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17760#pullrequestreview-1870802606

From vromero at openjdk.org  Thu Feb  8 17:19:03 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Thu, 8 Feb 2024 17:19:03 GMT
Subject: RFR: 8314275: Incorrect stepping in switch [v3]
In-Reply-To: <ntb0J5hmHOKI7B409GXM412Ttmt84XjYu7ntQ_MRQuI=.2a7f3f72-7a84-4f30-8754-ae2ec86de436@github.com>
References: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
 <ntb0J5hmHOKI7B409GXM412Ttmt84XjYu7ntQ_MRQuI=.2a7f3f72-7a84-4f30-8754-ae2ec86de436@github.com>
Message-ID: <Wobh_uBVRFnM6xnZbw1CHBeymzhM-3aIEPeMVoSgtLU=.8bbab91d-4770-4a10-a930-9f572a382e59@github.com>

On Thu, 8 Feb 2024 17:03:20 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

>> In code like the one below, the observable effect was that if the user debugs the following method, `multiply` called with `1`, the debugger steps from line 4 to line 6 (instead of 7) giving the impression that line 6 is going to be executed. The reason is that the `LineNumberTable` did not include an entry at the end of the `switch` mapping the statement that follows, to bytecode.
>> 
>> 
>> 1 private static double multiply(Integer i) { 
>> 2   double cr = 15;                              
>> 3    cr = switch (i) {                            
>> 4        case 1 -> cr * 1;                       
>> 5        case 2 -> cr * 2;                      
>> 6        default -> cr * 4;                     
>> 7    };                                           
>> 8    return cr;                              
>> 9 }
>
> Aggelos Biboudis has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Ensure fix is effective for switch expressions only

lgtm

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17772#pullrequestreview-1870815306

From vromero at openjdk.org  Thu Feb  8 17:19:04 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Thu, 8 Feb 2024 17:19:04 GMT
Subject: RFR: 8314275: Incorrect stepping in switch [v2]
In-Reply-To: <4igTd3bEWa9fq1xROHxxG2XNmwI-KbXHNPWLuquMIQg=.6712fb90-fae3-461f-b1cd-bf0cc5004c15@github.com>
References: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
 <fa7y4gjVsQ2CZZsAf47MBnIUQlzphoZpFPU2R6zdTZo=.917e6da5-d176-4640-b4ce-9e75dee1207c@github.com>
 <KZF3mEXf0j8WMV-b0Y42jH7UpQqAUoqbTbjQdszVpsA=.336f96d9-e55e-4dbe-b28b-a9c70475e278@github.com>
 <3Tqlfnm1pGWscC7p-RsqmjIfWw80qxUUiYxwnW7wVeI=.faf09e60-79f0-4353-be4f-044b3678f59b@github.com>
 <nQcR5u1LzqekJdidNaWj0B3Cn4iIztGF8EmykfjLleI=.ccb69c35-bece-45fd-9204-c3022a70cdf8@github.com>
 <4igTd3bEWa9fq1xROHxxG2XNmwI-KbXHNPWLuquMIQg=.6712fb90-fae3-461f-b1cd-bf0cc5004c15@github.com>
Message-ID: <XDs3hLPFKEXpKLbb-CsrPjdMptCxW2_0XdvaR32iaQo=.9062fba6-98ae-4923-b974-caa03d146afb@github.com>

On Thu, 8 Feb 2024 17:00:47 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

>> no I was just wondering why the issue didn't appear in the previous test, but what you are saying could be the explanation
>
> What do you think about this? https://github.com/openjdk/jdk/pull/17772/commits/a836d976e56c624882ae793ee89b1146c9fd4352
> 
> (also notice the newly added test case. For the `switch` statement the line 8 is not included and for the `switch` expression it is.)

yep looks good, thanks

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17772#discussion_r1483328533

From jjg at openjdk.org  Thu Feb  8 18:56:05 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 8 Feb 2024 18:56:05 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <MDprROiV35Q1rjuL_TD_cFkhYEGkN2B-xuH3eRcz0e0=.878238df-e7fd-4054-918b-17f77a5a4ecd@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <MDprROiV35Q1rjuL_TD_cFkhYEGkN2B-xuH3eRcz0e0=.878238df-e7fd-4054-918b-17f77a5a4ecd@github.com>
Message-ID: <5-LBnp9pQaksnQQQIe1MPmqdKGD2-0-UZgNnhtY5294=.db5cb4ce-dd03-4d5e-8533-48fdf15d9371@github.com>

On Fri, 26 Jan 2024 18:10:18 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains eight commits:
>> 
>>  - Merge with upstream/master
>>  - Merge with upstream/master
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Address review comments
>>  - Fix whitespace
>>  - Improve handling of embedded inline taglets
>>  - Customize support for Markdown headings
>>  - JDK-8298405: Support Markdown in Documentation Comments
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java line 145:
> 
>> 143:     }
>> 144: 
>> 145:     Pattern tag = Pattern.compile("<(?<tag>[A-Za-z0-9]+)(\\s|>)");
> 
> I'm not sure I grok this pattern; what's up with `\\s`?

The match for a tag is one of
* `<` _tag-name_ `>`
* `<` _tag-name_ _whitespace_

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483444658

From jjg at openjdk.org  Thu Feb  8 19:06:21 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 8 Feb 2024 19:06:21 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <MDprROiV35Q1rjuL_TD_cFkhYEGkN2B-xuH3eRcz0e0=.878238df-e7fd-4054-918b-17f77a5a4ecd@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <MDprROiV35Q1rjuL_TD_cFkhYEGkN2B-xuH3eRcz0e0=.878238df-e7fd-4054-918b-17f77a5a4ecd@github.com>
Message-ID: <UaIDVKbhQfqfrZJw_Eg7F0FM3pgdf6J21lwxVqJB1FM=.906f65d4-495b-4339-842c-fe57d4dca162@github.com>

On Fri, 26 Jan 2024 18:14:05 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains eight commits:
>> 
>>  - Merge with upstream/master
>>  - Merge with upstream/master
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Address review comments
>>  - Fix whitespace
>>  - Improve handling of embedded inline taglets
>>  - Customize support for Markdown headings
>>  - JDK-8298405: Support Markdown in Documentation Comments
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/CommentUtils.java line 629:
> 
>> 627:     public DocCommentTree parse(URI uri, String text) {
>> 628:         return trees.getDocCommentTree(new SimpleJavaFileObject(
>> 629:                 uri, JavaFileObject.Kind.HTML) {
> 
> Was it a bug before?

I would describe it as having been a "latent bug, waiting to happen".

Previously, all file objects were regarded as containing HTML content, and so there was no need to use the parameter, although maybe it would have been good to check it.

Now, file objects can be HTML or Markdown, and so we do need to use the parameter.

In the case here, the method is used on strings specified in command-line options, which are specified to be in HTML format.   Yes, we might want to change that, but that would be a different RFE separate from the work in this PR.  In that future evolution, I would suggest adding a `JavaFileObject.Kind` parameter to parse and/or inferring the kind from the tail of the path in the `uri` parameter.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483458107

From jjg at openjdk.org  Thu Feb  8 19:16:25 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 8 Feb 2024 19:16:25 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v23]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <eIvTG8kifeKKbTm0mHWsWuLOz1a8xvJs7S0Rt78X_nE=.af538f7c-c85f-41c4-af6c-cd47d1820395@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  clean up imports in ModuleGenerator test file

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/63dd8bf4..92b5e7a5

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=22
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=21-22

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

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

From jjg at openjdk.org  Thu Feb  8 19:19:19 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 8 Feb 2024 19:19:19 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v24]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <LU8x_y5yqCo2qjx2nUoYpqXZcg0GLdBkLPGvuaxS5Tw=.84aa9c31-a962-4886-af71-a643fe4bec28@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  remove commented-out code from DocCommentTester

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/92b5e7a5..5fc415b6

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=23
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=22-23

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

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

From jjg at openjdk.org  Thu Feb  8 19:49:37 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 8 Feb 2024 19:49:37 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v25]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <ONBViDjGySnRgD67SvM1P1n2kmNKO01jkgMQZhuNPrA=.dd52e932-3fec-4367-a536-cbdf089d113c@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  improve comments on negative test case

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/5fc415b6..c891fe9a

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=24
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=23-24

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

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

From jjg at openjdk.org  Thu Feb  8 21:01:00 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 8 Feb 2024 21:01:00 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v25]
In-Reply-To: <aRyFeUB0t9pLvRy-awz2Kr2gh1RDsiB0YGsuWTSItCQ=.b313e672-413f-46af-b95f-8d87707a8d70@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <bZq6pPTdtcJayLOFPeVpL2lth3zrxQFh7MVhw_RnD8Q=.13043746-8c61-474d-93b5-44743733441d@github.com>
 <3N5guZn5SiRlcjZrWQt0JbqUMJr79EcQ999JpVtx8-k=.cf3f71c3-4fcb-4958-b673-76b6b9797cd5@github.com>
 <aRyFeUB0t9pLvRy-awz2Kr2gh1RDsiB0YGsuWTSItCQ=.b313e672-413f-46af-b95f-8d87707a8d70@github.com>
Message-ID: <hdNONc20yvv1FsDu66KDbyJ72OJrmz8hmJygq46wiAI=.8d8a4743-7f27-45da-9bbd-5cf9b44b888b@github.com>

On Thu, 8 Feb 2024 15:37:06 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Ping. I do believe that it's important to have such a test.
>
> Ping.

I believe this is substantially covered in line 226-227.  See the third call to `test` in the following group of lines:


for (String src : sources) {
                test(src);
                test(src.replaceAll("@Deprecated", "/** @deprecated */"));
                test(src.replaceAll("deprecated", "notDeprecated2") // change class name
                        .replaceAll("@Deprecated", "/// @deprecated\n"));
            }


* The first call, `test(src)`, runs all the test cases, using the `@Deprecated` annotation by default.  In these test cases, the name of the element encodes whether it is expected that the element is deprecated or not.

* The second call, `test(src.replaceAll("deprecated", "notDeprecated2")`, runs the test cases again, after changing the annotation to a traditional (`/** ...*/`) comment containing the `@deprecated` tag. This is a long-standing call, and tests the legacy behavior of `@deprecated` appearing in a traditional doc comment.  Effectively, it tests whether a `/** @deprecated */` comment has equivalent behavior to a `@Deprecated` comment.

* The third call is new to this PR and the functionality to support Markdown comments.  It makes two changes to the source for the test cases, before running them:
   1. as in the previous test, the annotations are replaced by a comment containing `@deprecated` -- except that this time, the comment is a new-style `/// ... ` comment instead of a traditional `/** ... */` comment, and ...
   2. because we do not expect `/// @deprecated` to indicate deprecation, we need to change the expected result for each test case, which we do by changing the element name for the test case.  The change is the first call to replace to avoid false positives after changing the doc comment. The change uses a new name, `notDeprecated2`, in which `notDeprecated` encodes the expected deprecation status, and the `2` is to differentiate the declarations from other declarations in the case case that already use the name `notDeprecated`.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483582480

From jjg at openjdk.org  Thu Feb  8 21:42:31 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 8 Feb 2024 21:42:31 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v26]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <5uofSBLPGv5G97bklFCq78DEJ4dYKlg2YwZQ1VEsuB8=.5ea3bbd4-8b31-43d5-b3a5-9ca9a4027a7d@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  amend comment in test

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/c891fe9a..cb070451

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=25
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=24-25

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

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

From jjg at openjdk.org  Thu Feb  8 21:49:07 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 8 Feb 2024 21:49:07 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v26]
In-Reply-To: <hdNONc20yvv1FsDu66KDbyJ72OJrmz8hmJygq46wiAI=.8d8a4743-7f27-45da-9bbd-5cf9b44b888b@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <bZq6pPTdtcJayLOFPeVpL2lth3zrxQFh7MVhw_RnD8Q=.13043746-8c61-474d-93b5-44743733441d@github.com>
 <3N5guZn5SiRlcjZrWQt0JbqUMJr79EcQ999JpVtx8-k=.cf3f71c3-4fcb-4958-b673-76b6b9797cd5@github.com>
 <aRyFeUB0t9pLvRy-awz2Kr2gh1RDsiB0YGsuWTSItCQ=.b313e672-413f-46af-b95f-8d87707a8d70@github.com>
 <hdNONc20yvv1FsDu66KDbyJ72OJrmz8hmJygq46wiAI=.8d8a4743-7f27-45da-9bbd-5cf9b44b888b@github.com>
Message-ID: <EzAfM-a1G_Im5dcX5GK1jCetaqZ7yPmdMvPBLlLsi2U=.9eb2b2be-4bf2-4ea3-8edd-315b88250f07@github.com>

On Thu, 8 Feb 2024 20:58:24 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Ping.
>
> I believe this is substantially covered in line 226-227.  See the third call to `test` in the following group of lines:
> 
> 
> for (String src : sources) {
>                 test(src);
>                 test(src.replaceAll("@Deprecated", "/** @deprecated */"));
>                 test(src.replaceAll("deprecated", "notDeprecated2") // change class name
>                         .replaceAll("@Deprecated", "/// @deprecated\n"));
>             }
> 
> 
> * The first call, `test(src)`, runs all the test cases, using the `@Deprecated` annotation by default.  In these test cases, the name of the element encodes whether it is expected that the element is deprecated or not.
> 
> * The second call, `test(src.replaceAll("deprecated", "notDeprecated2")`, runs the test cases again, after changing the annotation to a traditional (`/** ...*/`) comment containing the `@deprecated` tag. This is a long-standing call, and tests the legacy behavior of `@deprecated` appearing in a traditional doc comment.  Effectively, it tests whether a `/** @deprecated */` comment has equivalent behavior to a `@Deprecated` comment.
> 
> * The third call is new to this PR and the functionality to support Markdown comments.  It makes two changes to the source for the test cases, before running them:
>    1. as in the previous test, the annotations are replaced by a comment containing `@deprecated` -- except that this time, the comment is a new-style `/// ... ` comment instead of a traditional `/** ... */` comment, and ...
>    2. because we do not expect `/// @deprecated` to indicate deprecation, we need to change the expected result for each test case, which we do by changing the element name for the test case.  The change is the first call to replace to avoid false positives after changing the doc comment. The change uses a new name, `notDeprecated2`, in which `notDeprecated` encodes the expected deprecation status, and the `2` is to differentiate the declarations from other declarations in the case case that already use the name `notDeprecated`.

While the underlying mechanism in javac for indicating deprecation is the same for all, I accept this is primarily a test for generated class files. I can add a javadoc test for basic behavior of `@deprecated` in Markdown comments.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483628179

From jjg at openjdk.org  Thu Feb  8 23:02:18 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 8 Feb 2024 23:02:18 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v27]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <9NF_Fppb1h1roiaG9ZGVOsbYAF2pmrZtJEnJVFFmYh4=.83fe633b-cee0-4306-be22-1fe4467c6407@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  added test case in TestMarkdown.java for handling of `@deprecated` tag

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/cb070451..3b1350b2

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=26
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=25-26

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

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

From jjg at openjdk.org  Thu Feb  8 23:57:09 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 8 Feb 2024 23:57:09 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v27]
In-Reply-To: <9NF_Fppb1h1roiaG9ZGVOsbYAF2pmrZtJEnJVFFmYh4=.83fe633b-cee0-4306-be22-1fe4467c6407@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <9NF_Fppb1h1roiaG9ZGVOsbYAF2pmrZtJEnJVFFmYh4=.83fe633b-cee0-4306-be22-1fe4467c6407@github.com>
Message-ID: <g4pw9-j5XHSsHCwv4R_HSglA8vl9fuBBtTy9lIFP3bc=.6479816c-ec6e-4ab5-8d33-5046173f8f71@github.com>

On Thu, 8 Feb 2024 23:02:18 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   added test case in TestMarkdown.java for handling of `@deprecated` tag

Re: https://github.com/openjdk/jdk/pull/16388#discussion_r1483182361
See https://github.com/openjdk/jdk/pull/17782

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

PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-1935112305

From abimpoudis at openjdk.org  Fri Feb  9 08:55:08 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Fri, 9 Feb 2024 08:55:08 GMT
Subject: Integrated: 8314275: Incorrect stepping in switch
In-Reply-To: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
References: <NOj-MZ0dQv38ASmA4jR0XjVg8nLJbRg6ZBMNPU0tXQo=.0415a1dd-9401-4ea5-853b-5ee3b1728b09@github.com>
Message-ID: <sdEMfDPL3CiOKchT3PEtkE0AqnuWNHf1xdvPNK58cEQ=.2ca87257-ca19-45d0-98f4-1367de25284c@github.com>

On Thu, 8 Feb 2024 14:29:50 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

> In code like the one below, the observable effect was that if the user debugs the following method, `multiply` called with `1`, the debugger steps from line 4 to line 6 (instead of 7) giving the impression that line 6 is going to be executed. The reason is that the `LineNumberTable` did not include an entry at the end of the `switch` mapping the statement that follows, to bytecode.
> 
> 
> 1 private static double multiply(Integer i) { 
> 2   double cr = 15;                              
> 3    cr = switch (i) {                            
> 4        case 1 -> cr * 1;                       
> 5        case 2 -> cr * 2;                      
> 6        default -> cr * 4;                     
> 7    };                                           
> 8    return cr;                              
> 9 }

This pull request has now been integrated.

Changeset: e3dc6a7a
Author:    Aggelos Biboudis <abimpoudis at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/e3dc6a7a28c4f049eb234c5487fca6c54298aa31
Stats:     84 lines in 2 files changed: 84 ins; 0 del; 0 mod

8314275: Incorrect stepping in switch

Reviewed-by: vromero

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

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

From jlahoda at openjdk.org  Fri Feb  9 11:54:00 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Fri, 9 Feb 2024 11:54:00 GMT
Subject: Integrated: 8325440: Confusing error reported for octal literals with
 wrong digits
In-Reply-To: <DOj5xpfhfbWrdLnt_1ltgBQcTZN1pyDSmw4ydeZVe8w=.2b87a8d6-dcd6-4765-97b6-5d58e4732609@github.com>
References: <DOj5xpfhfbWrdLnt_1ltgBQcTZN1pyDSmw4ydeZVe8w=.2b87a8d6-dcd6-4765-97b6-5d58e4732609@github.com>
Message-ID: <udNwTGzJf4mKSG8CzVapqCUvPnvmk9ItMIS7itHs5U0=.ea8228e6-b4ac-4733-ac1b-24e7abe2c4d4@github.com>

On Wed, 7 Feb 2024 21:06:47 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Consider code like:
> 
>     int i = 08;
> 
> 
> Currently, javac will produce an error like:
> 
> /tmp/Octal.java:2: error: ';' expected
>     int i = 08;
>              ^
> 
> 
> Which is fairly confusing. The cause is that this gets lexed as two tokens: `0` and `8`, as `8` is not a valid digit for an octal literal. The current behavior is a consequence of:
> https://bugs.openjdk.org/browse/JDK-8267361
> 
> Before that fix, the error was:
> 
> /tmp/Octal.java:2: error: integer number too large
>     int i = 08;
>             ^
> 
> 
> which was not better.
> 
> Please see the original PR:
> https://github.com/openjdk/jdk/pull/4111
> for more information on the decision there.
> 
> It seems to me that it would be better to have an error pinpointing the problem (i.e. wrong digit in what is the octal literal). Which is what this patch is trying to do. It would be possible to do that in the lexer, but that is slightly complex. So, this patch:
> - permits non-octal (and non-binary) digits in octal (and binary) literals, while still preserving the fact the literals are octal (binary)
> - when the parser tries to convert the textual literal representation to a number, and fails to do that, get a `NumberFormatException`. The handling of this exception is improved to provide better errors.
> 
> Note that, for consistency, this patch works not only for octal literals (which is likely the most problematic case in practice), but also for binary literals, although it seems relatively unlikely code would contain literals like `0b123` (unlike `08`, which may be a simple mistake).
> 
> The new error is:
> 
> /tmp/Octal.java:2: error: illegal digit in an octal literal
>     int i = 08;
>              ^
> 
> 
> (the error message can be re-phrased as needed/desired, of course.)

This pull request has now been integrated.

Changeset: 8b70b8d8
Author:    Jan Lahoda <jlahoda at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/8b70b8d85af0e26020c010324c7f1389cc5cb801
Stats:     70 lines in 9 files changed: 36 ins; 10 del; 24 mod

8325440: Confusing error reported for octal literals with wrong digits

Reviewed-by: vromero

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

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

From ihse at openjdk.org  Fri Feb  9 13:41:39 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Fri, 9 Feb 2024 13:41:39 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
Message-ID: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>

This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 

With Skara jcheck, it is possible to increase the coverage of the whitespace checks.

However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.

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

Commit messages:
 - 8325558: Add jcheck whitespace checking for properties files

Changes: https://git.openjdk.org/jdk/pull/17789/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17789&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325558
  Stats: 761 lines in 95 files changed: 0 ins; 5 del; 756 mod
  Patch: https://git.openjdk.org/jdk/pull/17789.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17789/head:pull/17789

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

From ihse at openjdk.org  Fri Feb  9 13:41:39 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Fri, 9 Feb 2024 13:41:39 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
In-Reply-To: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
Message-ID: <vjpYKJQJffU8Erjfn6uucPoPpWriBq1VQhvkztNZ5yg=.834ae963-240f-4bbf-8110-2278d7e17cec@github.com>

On Fri, 9 Feb 2024 13:35:55 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
> 
> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
> 
> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.

I'll add some specific comments/reasoning to individual files, where I think a remark might be needed.

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

PR Comment: https://git.openjdk.org/jdk/pull/17789#issuecomment-1935947566

From ihse at openjdk.org  Fri Feb  9 13:55:09 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Fri, 9 Feb 2024 13:55:09 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
In-Reply-To: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
Message-ID: <aiUe8udp6Qtknwo8Ha3jenZ_TP_SMD5baGxnNlNz7WI=.86e01229-6456-4e46-ad0c-1e74c84c7c63@github.com>

On Fri, 9 Feb 2024 13:35:55 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
> 
> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
> 
> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.

src/java.base/unix/classes/sun/net/www/content-types.properties line 1:

> 1: #sun.net.www MIME content-types table

I have converted all leading tabs to 8 spaces.

src/java.base/windows/classes/sun/net/www/content-types.properties line 1:

> 1: #sun.net.www MIME content-types table

I have converted all leading tabs to 8 spaces.

src/java.desktop/share/classes/com/sun/imageio/plugins/common/iio-plugin.properties line 11:

> 9: ImageUtil0=The supplied Raster does not represent a binary data set.
> 10: ImageUtil1=The provided sample model is null.
> 11: ImageUtil2=The provided image cannot be encoded using: 

While it seems like this could have been significant, the code that uses it looks like this:

 throw new IIOException(I18N.getString("ImageUtil2")+" "+
                                   writer.getClass().getName());

so it will end up with a double space right now.

src/java.scripting/share/classes/com/sun/tools/script/shell/messages.properties line 1:

> 1: #

I have converted all leading tabs to 8 spaces.

src/java.sql.rowset/share/classes/com/sun/rowset/RowSetResourceBundle.properties line 73:

> 71: cachedrowsetimpl.numrows = Number of rows is less than zero or less than fetch size
> 72: cachedrowsetimpl.startpos = Start position cannot be negative
> 73: cachedrowsetimpl.nextpage = Populate data before calling 

This sounded like it could potentially be followed by a name, but this is not the case.

src/java.sql.rowset/share/classes/com/sun/rowset/RowSetResourceBundle.properties line 128:

> 126: crswriter.params1 = Value of params1 : {0} 
> 127: crswriter.params2 = Value of params2 : {0} 
> 128: crswriter.conflictsno =  conflicts while synchronizing 

This sounded like it could potentially be followed by a string, but this is not the case.

src/java.sql.rowset/share/classes/com/sun/rowset/RowSetResourceBundle_de.properties line 1:

> 1: #

The changes in this and the following files are just to align the file with the English master copy.

src/java.xml/share/classes/com/sun/org/apache/xerces/internal/impl/msg/DOMMessages.properties line 24:

> 22: 
> 23:         BadMessageKey = The error message corresponding to the message key can not be found.
> 24:         FormatFailed = An internal error occurred while formatting the following message:\n  

At first glance, it might look like something should follow the `:`, but note that there is a `\n` so if anything this will only make the next line improperly indented.

src/java.xml/share/classes/com/sun/org/apache/xerces/internal/impl/msg/DOMMessages_de.properties line 1:

> 1: #

The changes in this and the following files are just to align the file with the English master copy.

src/java.xml/share/classes/com/sun/org/apache/xerces/internal/impl/msg/SAXMessages_de.properties line 1:

> 1: #

The changes in this and the following files are just to align the file with the English master copy.

src/java.xml/share/classes/com/sun/org/apache/xerces/internal/impl/msg/XIncludeMessages.properties line 20:

> 18: # Messages for message reporting
> 19: BadMessageKey = The error message corresponding to the message key can not be found.
> 20: FormatFailed = An internal error occurred while formatting the following message:\n

At first glance, it might look like something should follow the :, but note that there is a \n so if anything this will only make the next line improperly indented.

src/java.xml/share/classes/com/sun/org/apache/xerces/internal/impl/msg/XIncludeMessages_de.properties line 1:

> 1: #

The changes in this and the following files are just to align the file with the English master copy.

src/java.xml/share/classes/com/sun/org/apache/xerces/internal/impl/msg/XMLMessages.properties line 27:

> 25: 
> 26:         BadMessageKey = The error message corresponding to the message key can not be found.
> 27:         FormatFailed = An internal error occurred while formatting the following message:\n

Same here with `:\n`...

src/java.xml/share/classes/com/sun/org/apache/xerces/internal/impl/msg/XPointerMessages.properties line 24:

> 22: # Messages for message reporting
> 23: BadMessageKey = The error message corresponding to the message key can not be found.
> 24: FormatFailed = An internal error occurred while formatting the following message:\n

Same here with `:\n`...

src/jdk.compiler/share/classes/sun/tools/serialver/resources/serialver.properties line 1:

> 1: #

I have converted all leading tabs to 8 spaces.

src/jdk.jartool/share/classes/sun/tools/jar/resources/jar.properties line 49:

> 47:         'u' flag requires manifest, 'e' flag or input files to be specified!
> 48: error.bad.eflag=\
> 49: 	'e' flag and manifest with the 'Main-Class' attribute cannot be specified \n\

Here were two lines that used tab instead of space; I converted them to 8 spaces.

test/jaxp/javax/xml/jaxp/unittest/common/config/files/catalog2.properties line 4:

> 2: #       XML Library (java.xml) Configuration File
> 3: #
> 4: # This file is in java.util.Properties format and typically located in the conf 

These spaces at the end of comment lines has crept in since I cleaned all such out in [JDK-8298047](https://bugs.openjdk.org/browse/JDK-8298047). It's a good example of why we need the jcheck verification to keep this from regressing once more.

test/jdk/sanity/client/lib/SwingSet3/src/com/sun/swingset3/demos/table/resources/TableDemo.properties line 12:

> 10: 
> 11: TableDemo.noDataStatusLabel=No data loaded
> 12: TableDemo.loadingStatusLabel=Loading data:\u0020

According to https://github.com/openjdk/jdk/pull/11488/files#r1038605801 the latter two are actually needed as spaces, and the first might be; so keeping it as well seems to be the safe choice.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484326435
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484326568
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484327614
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484327859
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484329632
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484329770
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484330650
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484332081
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484332649
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484334629
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484334259
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484335061
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484335669
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484337306
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484338418
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484339114
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484341847
PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484345466

From dfuchs at openjdk.org  Fri Feb  9 14:10:57 2024
From: dfuchs at openjdk.org (Daniel Fuchs)
Date: Fri, 9 Feb 2024 14:10:57 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
In-Reply-To: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
Message-ID: <MAPhOTYtvVaNcWCFKbDS-_1DUpWDjk7QPxjKCqRkcMU=.6138cf57-eec3-47fd-9932-3ab1d538e789@github.com>

On Fri, 9 Feb 2024 13:35:55 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
> 
> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
> 
> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.

changes to sun/net content-types.properties look OK

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

PR Comment: https://git.openjdk.org/jdk/pull/17789#issuecomment-1935996382

From erikj at openjdk.org  Fri Feb  9 14:56:57 2024
From: erikj at openjdk.org (Erik Joelsson)
Date: Fri, 9 Feb 2024 14:56:57 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
In-Reply-To: <aiUe8udp6Qtknwo8Ha3jenZ_TP_SMD5baGxnNlNz7WI=.86e01229-6456-4e46-ad0c-1e74c84c7c63@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
 <aiUe8udp6Qtknwo8Ha3jenZ_TP_SMD5baGxnNlNz7WI=.86e01229-6456-4e46-ad0c-1e74c84c7c63@github.com>
Message-ID: <nhpBrqfBtPnWkJykz1_einfiy1GazMV7NLU1-ukdtiw=.c2e3123b-9bc5-418e-9785-62a078ab9466@github.com>

On Fri, 9 Feb 2024 13:42:02 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
>> 
>> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
>> 
>> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.
>
> src/java.xml/share/classes/com/sun/org/apache/xerces/internal/impl/msg/DOMMessages.properties line 24:
> 
>> 22: 
>> 23:         BadMessageKey = The error message corresponding to the message key can not be found.
>> 24:         FormatFailed = An internal error occurred while formatting the following message:\n  
> 
> At first glance, it might look like something should follow the `:`, but note that there is a `\n` so if anything this will only make the next line improperly indented.

That could have been intentional though. Not sure if it was a good idea, but indenting something is a way of making something stand out as a quote. But looking at every use site, there is an extra space added anyway, so this seems fine. If we wanted to preserve the exact same behavior, all use sites should be updated to add 3 spaces.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1484416962

From naoto at openjdk.org  Fri Feb  9 18:12:06 2024
From: naoto at openjdk.org (Naoto Sato)
Date: Fri, 9 Feb 2024 18:12:06 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
In-Reply-To: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
Message-ID: <rB3HxteVgSXBiQnLDLdYgc2jXTL2fFPg5zdCQwxHt1g=.37699c1c-1dad-4451-b364-38d1b2170957@github.com>

On Fri, 9 Feb 2024 13:35:55 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
> 
> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
> 
> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.

Skimmed through the changes and all look good to me. Good to have `jcheck` detect those unneeded trailing spaces.

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

PR Review: https://git.openjdk.org/jdk/pull/17789#pullrequestreview-1872951198

From jjg at openjdk.org  Fri Feb  9 18:12:09 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 9 Feb 2024 18:12:09 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
In-Reply-To: <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0mlIFIZ2ec8oE2zlmKxoMwp59dBgOdUQs-vzTLnU7hI=.15fa2827-8c87-415b-ab74-0e42b45a5cf7@github.com>
 <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
Message-ID: <UPoDGtqJzFdUQ2K_WMcSGAYIny01XZ3yYJmRdp7m0S0=.dba7e91e-92a3-4cea-8d82-4bc35557c7ea@github.com>

On Sat, 13 Jan 2024 21:55:06 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons 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 seven additional commits since the last revision:
>> 
>>  - Merge with upstream/master
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Address review comments
>>  - Fix whitespace
>>  - Improve handling of embedded inline taglets
>>  - Customize support for Markdown headings
>>  - JDK-8298405: Support Markdown in Documentation Comments
>
> src/jdk.compiler/share/classes/com/sun/source/doctree/DocTreeVisitor.java line 257:
> 
>> 255:      *
>> 256:      * @implSpec Visits the provided {@code RawTextTree} node
>> 257:      * by calling {@code visitOther(node, p)}.
> 
> Nit: for consistency with the rest of the file, reorder `@param`-`@return` block with the `@implSpec` tag:
> 
> Suggestion:
> 
>      *
>      * @implSpec Visits the provided {@code RawTextTree} node
>      * by calling {@code visitOther(node, p)}.
>      *
>      * @param node the node being visited
>      * @param p a parameter value
>      * @return a result value

Done

> src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java line 1080:
> 
>> 1078:             }
>> 1079: 
>> 1080:             private String info(FileObject fo) {
> 
> This does not seem to be used; is it for debugging? If so, add your `// DEBUG` comment.

It probably was used for debugging at some point.  The method can be `static`, meaning it is not specific to this class and could be elsewhere if we wanted to retain the functionality.   Code like this is easy enough to regenerate, so I will delete this copy for now.

> src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java line 1156:
> 
>> 1154: 
>> 1155:     /**
>> 1156:      * {@return the {@linkplain ParserFactory} parser factory}.
> 
> Suggestion:
> 
>      * {@return the {@linkplain ParserFactory} parser factory}

done

> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java line 1065:
> 
>> 1063: 
>> 1064:                     if (accept('/')) { // (Spec. 3.7)
>> 1065:                         if (accept('/')) { // Markdown comment
> 
> I believe that some of the changes in `com/sun/tools/javac/parser` were contributed by @JimLaskey. If so, don't forget to add him as a co-author: `/contributor add jlaskey`.

did that

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484652974
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484650198
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484651230
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484651466

From jjg at openjdk.org  Fri Feb  9 18:31:14 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 9 Feb 2024 18:31:14 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
In-Reply-To: <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0mlIFIZ2ec8oE2zlmKxoMwp59dBgOdUQs-vzTLnU7hI=.15fa2827-8c87-415b-ab74-0e42b45a5cf7@github.com>
 <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
Message-ID: <WYXUTmwMTgMP4YjGJk4CIxXFqZ6LwAhhjHOgjDVkOU4=.7a797721-e94f-44a8-8cea-78f761187d0f@github.com>

On Mon, 15 Jan 2024 12:26:34 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons 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 seven additional commits since the last revision:
>> 
>>  - Merge with upstream/master
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Address review comments
>>  - Fix whitespace
>>  - Improve handling of embedded inline taglets
>>  - Customize support for Markdown headings
>>  - JDK-8298405: Support Markdown in Documentation Comments
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 201:
> 
>> 199:                 }
>> 200:                 newline = true;
>> 201:             }
> 
> I can see clean LF and CRLF, but no FF; was the latter intentional?
> 
> In any case, we should double-check the generated test output to see if there's anything unexpected.

We've been here, with `\f` before, noting the different handling of `\f` in `javac` and `javadoc`.

My recollection is that it was intentional to drop support for `\f`, thus aligning `javac` and `javadoc` behavior, and to normalize handling of the newline sequences, translating them to `\n`.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484669301

From jjg at openjdk.org  Fri Feb  9 18:57:27 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 9 Feb 2024 18:57:27 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v28]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <dfbZPdbtDSkKlqE7LBPsOxmhd35_xUsA68XNr8OjDrk=.5e7c7f26-2ce5-4ade-9094-703b3de0e3f4@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  address review feedback

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/3b1350b2..91588bc3

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=27
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=26-27

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

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

From prappo at openjdk.org  Fri Feb  9 19:05:09 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 9 Feb 2024 19:05:09 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
In-Reply-To: <5BjUOMWcopR-ouu-BVzMiDNUU5uZTFBhS4E0orGR9H4=.cb1112d1-7832-428f-b485-c417798248ab@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0mlIFIZ2ec8oE2zlmKxoMwp59dBgOdUQs-vzTLnU7hI=.15fa2827-8c87-415b-ab74-0e42b45a5cf7@github.com>
 <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
 <flR9QGfiaBhXqoK_j0z67KC8aSbVgmV15-ZGGU1Nfog=.a06bc2dc-7e1c-4586-af4a-80ddfa0cd753@github.com>
 <5BjUOMWcopR-ouu-BVzMiDNUU5uZTFBhS4E0orGR9H4=.cb1112d1-7832-428f-b485-c417798248ab@github.com>
Message-ID: <qD-aQf5OgdJVWsXGMnEZFUoITXMdtwr20UfURFTnsdQ=.0b86d1fa-1c5a-46b3-b543-80f1cd65a2b1@github.com>

On Tue, 30 Jan 2024 00:47:33 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> > Musing on this more.
> > Can/should we, without introducing probably unwelcome `Kind.MD` to `javax.tools.JavaFileObject.Kind`, teach javac to recognise `package.md` similarly to how it recognises legacy `package.html`? If we are aiming for Markdown to be a drop in replacement for traditional javadoc comments, we might want to go the extra mile.
> > I'm pleased to see that Markdown `-overview` files work just fine.
> 
> No. There are times to let go of legacy behavior, and even if this is not the time to remove support for `package.html`, there is no reason to go backwards and support `package.md`. The preferred replacement for `package.html` has long been `package-info.java` and you can put Markdown content in that file with no issues.
> 
> In similar fashion, remember the recent discussion as to whether we should support `@deprecated` in Markdown comments as marking the declaration as _deprecated_, even without the `@Deprecated` annotation. The general consensus was to not persist with that legacy behavior.

Okay.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484693923

From prappo at openjdk.org  Fri Feb  9 19:05:10 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 9 Feb 2024 19:05:10 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
In-Reply-To: <uv0-wEcbk0cdgcF2V4G7SHPu3WoH6hfdjspkWJk31SA=.40a3fe04-523b-40bd-83f9-28708de46901@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0mlIFIZ2ec8oE2zlmKxoMwp59dBgOdUQs-vzTLnU7hI=.15fa2827-8c87-415b-ab74-0e42b45a5cf7@github.com>
 <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
 <uv0-wEcbk0cdgcF2V4G7SHPu3WoH6hfdjspkWJk31SA=.40a3fe04-523b-40bd-83f9-28708de46901@github.com>
Message-ID: <imFMX3KSSPgzib_zMIjARkFIx9Mxk-yJ0neGRiZxzJE=.90f3887f-572b-4640-9d94-8285040ee6b1@github.com>

On Mon, 29 Jan 2024 23:34:24 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 215:
>> 
>>> 213:                  case '\n', '\r' -> {
>>> 214:                      return newString(bp, p);
>>> 215:                  }
>> 
>> Hm... this does not seem to be consistent with `newline` in `nextChar`; should it be consistent?
>
> I think it is OK, isn't it?
> 
> In both cases, a newline sequence can begin with `\r` or `\n`.
> 
> In this `peekLine` method, we only want the content up to but not including the newline, so there is no need to handle the possibility of `\r\n`.   In `nextChar`, we do want to detect `r` and `\r\n` and treat both as equivalent to `\n`.
> 
> Or am I missing something?

You don't seem to be missing anything; it's me who was confused.

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1295:
>> 
>>> 1293:             switch (ch) {
>>> 1294:                 case ' ' -> indent++;
>>> 1295:                 case '\t' -> indent = 4;
>> 
>> Shouldn't it be like this or it does not matter?
>>  ```suggestion
>>                  case '\t' -> indent += 4;
>
> I did mean `indent = 4`.
> It would not mean `indent +=4` because you would have to take preceding character count into account, to round up to a multiple of 4.
> But anyway, it's enough to know the indent is 4 or more, meaning the code is looking at an indented code block.
> https://spec.commonmark.org/0.30/#indented-code-blocks

I'm not sure I understood the _take preceding character count into account_ part, but if `indent = 4` is what you meant and having read that section of the spec, I'm okay with it. Thanks.

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1421:
>> 
>>> 1419:             case '#', '=', '-', '+', '_', '`', '~' -> {
>>> 1420:                 String line = peekLine();
>>> 1421:                 for (LineKind lk : LineKind.values()) {
>> 
>> Nothing wrong here, just noting that this is one more way one can depend on an enum constant order. Change it, and a peeked line kind might change too (e.g. `OTHER` matches everything.)
>
> Like it or not, JLS defines that enum members are ordered, and even has an example 8.9.3-1 of using the `values` method in an enhanced `for` loop. Any change to the order of the members of any enum has the potential to be a breaking change and should never be done lightly.  Curiously, JLS 13.4.26 does not say that reordering enum constants may break clients.
> 
> Anyway, I added comments to the LineKind enum declaration.

I think I'm still coming to terms with this feature of enum constants: being order-sensitive. https://docs.oracle.com/javase/specs/jls/se21/html/jls-13.html#jls-13.4.26 is concerned with "binary compatibility". What we are talking about here is more like "behavioural compatibilty" as defined in https://wiki.openjdk.org/display/csr/Kinds+of+Compatibility. But we digress.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484581568
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484593858
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484607076

From prappo at openjdk.org  Fri Feb  9 19:05:12 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 9 Feb 2024 19:05:12 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <_WLv7XFq2-900uOZFhRJ8rLQmjlFdTlHmC9wVfS6I-Y=.1ada9999-1a0e-4f88-aa67-5d4120585f35@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <_WLv7XFq2-900uOZFhRJ8rLQmjlFdTlHmC9wVfS6I-Y=.1ada9999-1a0e-4f88-aa67-5d4120585f35@github.com>
Message-ID: <qNT4gi2yF_GeQLZ8FE0_B_zvEoO5umtnBFX38QRG_dE=.56ab1794-a499-4759-a529-dcbd56cdb120@github.com>

On Tue, 23 Jan 2024 13:02:46 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains eight commits:
>> 
>>  - Merge with upstream/master
>>  - Merge with upstream/master
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Address review comments
>>  - Fix whitespace
>>  - Improve handling of embedded inline taglets
>>  - Customize support for Markdown headings
>>  - JDK-8298405: Support Markdown in Documentation Comments
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1315:
> 
>> 1313:     }
>> 1314: 
>> 1315:     void skipLine() {
> 
> Like `peekLike()`, this method also does not seem to be consistent with `newline` in `nextChar()`.

It's okay. You explained my confusion here: https://github.com/openjdk/jdk/pull/16388#discussion_r1470367971

> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1419:
> 
>> 1417:     LineKind peekLineKind() {
>> 1418:         switch (ch) {
>> 1419:             case '#', '=', '-', '+', '_', '`', '~' -> {
> 
> This change is to match that of `THEMATIC_BREAK`:
> Suggestion:
> 
>             case '#', '=', '-', '*', '_', '`', '~' -> {

While you seem to have forgotten to change it, no tests failed, which is sad.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484619952
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484617917

From prappo at openjdk.org  Fri Feb  9 19:05:09 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 9 Feb 2024 19:05:09 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
In-Reply-To: <4Tqtmfv4DzkI4sbb6bLBY9Ll0xd34vm9KBUzthu3fd8=.2e94fa19-e555-4371-bd2e-8506938527e8@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0mlIFIZ2ec8oE2zlmKxoMwp59dBgOdUQs-vzTLnU7hI=.15fa2827-8c87-415b-ab74-0e42b45a5cf7@github.com>
 <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
 <w8lQxY5brSRBfHvIQq-Qb12dg5HdAKbkfR_5tJIPjkY=.ae66d225-f916-4719-be19-03372eaf8b23@github.com>
 <4Tqtmfv4DzkI4sbb6bLBY9Ll0xd34vm9KBUzthu3fd8=.2e94fa19-e555-4371-bd2e-8506938527e8@github.com>
Message-ID: <z0-3fcMBCKOgPaEfSWe3NBOmXDHS-NDUiDVCIQBFUZQ=.95386f8d-e0cc-4cdf-96ba-307ccec06f27@github.com>

On Mon, 29 Jan 2024 23:50:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Probably, yes.
>
> New class comment added.

I can see it and it reads nicely; thanks!

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484586216

From prappo at openjdk.org  Fri Feb  9 19:05:12 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 9 Feb 2024 19:05:12 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <VIgOZy_4rC8rWkb-re-lYOmabLq6vwl9lpg9U1Lbz7U=.ac116c11-dd6c-4fe6-82d6-fbe92354702c@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <_WLv7XFq2-900uOZFhRJ8rLQmjlFdTlHmC9wVfS6I-Y=.1ada9999-1a0e-4f88-aa67-5d4120585f35@github.com>
 <VIgOZy_4rC8rWkb-re-lYOmabLq6vwl9lpg9U1Lbz7U=.ac116c11-dd6c-4fe6-82d6-fbe92354702c@github.com>
Message-ID: <fB3rnqUsK7o_0gHrF3deAM_k1LQLBbxd60EWJctq0SA=.3299c83c-1662-4aa9-be8e-7049857ea974@github.com>

On Tue, 30 Jan 2024 21:37:10 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java line 1065:
>> 
>>> 1063: 
>>> 1064:                     if (accept('/')) { // (Spec. 3.7)
>>> 1065:                         if (accept('/')) { // Markdown comment
>> 
>> Here and elsewhere in this file: do we need to mention Markdown?
>
> The "M" word appears 10 times in this file. I'll work to convert them to an alternate nomenclature, such as "line comment".

I can see that you've managed to remove all of those occurrences nicely; well done!

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484624573

From prappo at openjdk.org  Fri Feb  9 19:05:13 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 9 Feb 2024 19:05:13 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
In-Reply-To: <vrwe2U_b9K6EUSg760EHhm3x7sz2tp0D4thYIqknnGw=.e5c1c331-644a-4473-8a8b-d3c8f3128303@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <vrwe2U_b9K6EUSg760EHhm3x7sz2tp0D4thYIqknnGw=.e5c1c331-644a-4473-8a8b-d3c8f3128303@github.com>
Message-ID: <Fi4NuaFltjeOrEITZ6UI3osRWtQrnoDx566UsfCL0EE=.a042889e-e4f0-4ba7-b2f9-04b1d36c510d@github.com>

On Wed, 7 Feb 2024 18:14:24 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 28 commits:
> 
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it
>    merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.
>  - add test case contributed by @lahodaj
>  - initial fix for source offset problem
>  - remove unused imports
>  - First pass at remove DocCommentTransformer from the public API.
>    
>    It is still declared internally, and installed by default, using the service-provider mechanism.
>    If the standard impl is not available, an identity transformer is used.
>  - updates for "first sentence" issues and tests
>  - add info about provenance of `jdk.internal.md` module
>  - MarkdownTransformer: tweak doc comments
>  - MarkdownTransformer: change `Lower.replaceIter` to be `private final`
>  - MarkdownTransformer: use suggested text for using streams
>  - ... and 18 more: https://git.openjdk.org/jdk/compare/18e24d06...63dd8bf4

src/jdk.internal.md/share/classes/module-info.java line 41:

> 39: // * package and import statements are updated
> 40: // * characters outside the ASCII range are converted to Unicode escapes
> 41: // * @SuppressWarnings("fallthrough") is added to getSetextHeadingLevel

I wonder if it would be better to compile this module without (some) lint checks. Is it possible?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1483335356

From prappo at openjdk.org  Fri Feb  9 19:05:13 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 9 Feb 2024 19:05:13 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v28]
In-Reply-To: <vpCR8ztMJ6THwioLqFcmf_XaoBfgGU8hESSITzaZDgg=.e3ccf661-eff8-41e9-b203-a58d369ec710@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <bZq6pPTdtcJayLOFPeVpL2lth3zrxQFh7MVhw_RnD8Q=.13043746-8c61-474d-93b5-44743733441d@github.com>
 <vpCR8ztMJ6THwioLqFcmf_XaoBfgGU8hESSITzaZDgg=.e3ccf661-eff8-41e9-b203-a58d369ec710@github.com>
Message-ID: <p-5OpfgEIx2PZY2AiORJ1snS434p54SzB_HxJPZzxFM=.62a91526-0281-4ad7-ad89-a3b3c8a05b86@github.com>

On Thu, 8 Feb 2024 15:38:26 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> test/langtools/jdk/javadoc/tool/sampleapi/lib/sampleapi/generator/ModuleGenerator.java line 49:
>> 
>>> 47: import sampleapi.util.PoorDocCommentTable;
>>> 48: 
>>> 49: import static com.sun.tools.javac.parser.Tokens.Comment.CommentStyle.JAVADOC;
>> 
>> To clarify, the change to this file is that you removed two unused imports, right?
>
> Ping. Maybe if it is not essential, we could remove that change, to keep PR more focused.

Okay I can see that you tried to revert the change to that file and published a [PR] to optimise imports separately. Sadly, the "revert" introduced even more churn. Here's my proposal, which might not be elegant but does the job:


git checkout 8298405.doclet-markdown-v3
git diff -R head --not upstream/master -- test/langtools/jdk/javadoc/tool/sampleapi/lib/sampleapi/generator/ModuleGenerator.java | git apply
git commit -am "Revert all changes to ModuleGenerator.java"


If you have any issues with that snippet, ping me out of band; I hope the intent of the snippet is clear though.

[PR]: https://github.com/openjdk/jdk/pull/17782

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484477033

From prappo at openjdk.org  Fri Feb  9 19:05:13 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 9 Feb 2024 19:05:13 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v28]
In-Reply-To: <Zwe6y0vUwzwB1fCJM_FiKalBTvej10e5oxQIjX-xNJk=.ab043e54-14a4-4f9c-9687-7957354d460d@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <bZq6pPTdtcJayLOFPeVpL2lth3zrxQFh7MVhw_RnD8Q=.13043746-8c61-474d-93b5-44743733441d@github.com>
 <Zwe6y0vUwzwB1fCJM_FiKalBTvej10e5oxQIjX-xNJk=.ab043e54-14a4-4f9c-9687-7957354d460d@github.com>
Message-ID: <osiK1d46PggEwfKnkRcnwwgXRVsbRhD23JzayeLNzEo=.d035ba2a-90b1-46c0-ad4f-19b0cb97852e@github.com>

On Wed, 15 Nov 2023 00:37:06 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> test/langtools/jdk/javadoc/tool/testTransformer/TestTransformer.java line 96:
>> 
>>> 94:         var sl = ServiceLoader.load(DocTrees.DocCommentTreeTransformer.class);
>>> 95:         return StreamSupport.stream(sl.spliterator(), false)
>>> 96:                 .filter(p -> p.name().equals(name))
>> 
>> ServiceLoader specification suggests another way of streaming:
>> Suggestion:
>> 
>>         return sl.stream()
>>                 .map(ServiceLoader.Provider::get)
>>                 .filter(t -> t.name().equals(name))
>> 
>> Would it be the same and more readable?
>
> Hmm. It's longer, but arguably simpler to comprehend than using a spliterator. I've changed the code.

There's now a leftover `import java.util.stream.StreamSupport;` in that file.

>> test/langtools/tools/javac/doctree/MDPrinter.java line 67:
>> 
>>> 65:  * Conceptually based on javac's {@code DPrinter}.
>>> 66:  */
>>> 67: public class MDPrinter {
>> 
>> While DPrinter is used, MDPrinter isn't. (At least, I could't find any usages of it.) If you feel like MDPrinter is important, we should at least add a compile test for it, to protect it from bitrot.
>
> ?

MDPrinter.java is now a test that compiles itself; thanks.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484541756
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484196535

From prappo at openjdk.org  Fri Feb  9 19:05:13 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 9 Feb 2024 19:05:13 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v28]
In-Reply-To: <EzAfM-a1G_Im5dcX5GK1jCetaqZ7yPmdMvPBLlLsi2U=.9eb2b2be-4bf2-4ea3-8edd-315b88250f07@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <bZq6pPTdtcJayLOFPeVpL2lth3zrxQFh7MVhw_RnD8Q=.13043746-8c61-474d-93b5-44743733441d@github.com>
 <3N5guZn5SiRlcjZrWQt0JbqUMJr79EcQ999JpVtx8-k=.cf3f71c3-4fcb-4958-b673-76b6b9797cd5@github.com>
 <aRyFeUB0t9pLvRy-awz2Kr2gh1RDsiB0YGsuWTSItCQ=.b313e672-413f-46af-b95f-8d87707a8d70@github.com>
 <hdNONc20yvv1FsDu66KDbyJ72OJrmz8hmJygq46wiAI=.8d8a4743-7f27-45da-9bbd-5cf9b44b888b@github.com>
 <EzAfM-a1G_Im5dcX5GK1jCetaqZ7yPmdMvPBLlLsi2U=.9eb2b2be-4bf2-4ea3-8edd-315b88250f07@github.com>
Message-ID: <yc8uyiXGmd-ymdwUPFnGBe6md0vh5EyQgLSvIesmY00=.81eb3acd-3b20-47eb-b3f4-4552b3412744@github.com>

On Thu, 8 Feb 2024 21:46:34 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> I believe this is substantially covered in line 226-227.  See the third call to `test` in the following group of lines:
>> 
>> 
>> for (String src : sources) {
>>                 test(src);
>>                 test(src.replaceAll("@Deprecated", "/** @deprecated */"));
>>                 test(src.replaceAll("deprecated", "notDeprecated2") // change class name
>>                         .replaceAll("@Deprecated", "/// @deprecated\n"));
>>             }
>> 
>> 
>> * The first call, `test(src)`, runs all the test cases, using the `@Deprecated` annotation by default.  In these test cases, the name of the element encodes whether it is expected that the element is deprecated or not.
>> 
>> * The second call, `test(src.replaceAll("deprecated", "notDeprecated2")`, runs the test cases again, after changing the annotation to a traditional (`/** ...*/`) comment containing the `@deprecated` tag. This is a long-standing call, and tests the legacy behavior of `@deprecated` appearing in a traditional doc comment.  Effectively, it tests whether a `/** @deprecated */` comment has equivalent behavior to a `@Deprecated` comment.
>> 
>> * The third call is new to this PR and the functionality to support Markdown comments.  It makes two changes to the source for the test cases, before running them:
>>    1. as in the previous test, the annotations are replaced by a comment containing `@deprecated` -- except that this time, the comment is a new-style `/// ... ` comment instead of a traditional `/** ... */` comment, and ...
>>    2. because we do not expect `/// @deprecated` to indicate deprecation, we need to change the expected result for each test case, which we do by changing the element name for the test case.  The change is the first call to replace to avoid false positives after changing the doc comment. The change uses a new name, `notDeprecated2`, in which `notDeprecated` encodes the expected deprecation status, and the `2` is to differentiate the declarations from other declarations in the case case that already use the name `notDeprecated`.
>
> While the underlying mechanism in javac for indicating deprecation is the same for all, I accept this is primarily a test for generated class files. I can add a javadoc test for basic behavior of `@deprecated` in Markdown comments.

Thanks for confirming that there's a test to check that `/// @deprecated` is a no-op and for patiently explaining how that test works.

I confirm that test/langtools/tools/javac/classfiles/attributes/deprecated/DeprecatedTest.java starts failing if I introduce the following change:


--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java
@@ -1638,7 +1638,7 @@ protected void scanDocComment() {
                             ? trimJavadocLineComment(line, indent)
                             : trimJavadocComment(line);
 
-                    if (cs == CommentStyle.JAVADOC_BLOCK) {
+//                    if (cs == CommentStyle.JAVADOC_BLOCK) {
                         // If standalone @deprecated tag
                         int pos = line.position();
                         line.skipWhitespace();
@@ -1652,7 +1652,7 @@ protected void scanDocComment() {
                         }
 
                         line.reset(pos);
-                    }
+//                    }
 
                     putLine(line);
                 }


I can also see that you have introduced a dedicated test/langtools/jdk/javadoc/doclet/testMarkdown/TestMarkdown.java#testDeprecated which also starts failing with that change of mine.

Please update the copyright year in test/langtools/jdk/javadoc/doclet/testMarkdown/TestMarkdown.java.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484410402

From prappo at openjdk.org  Fri Feb  9 19:05:13 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 9 Feb 2024 19:05:13 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v28]
In-Reply-To: <aRyFeUB0t9pLvRy-awz2Kr2gh1RDsiB0YGsuWTSItCQ=.b313e672-413f-46af-b95f-8d87707a8d70@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <bZq6pPTdtcJayLOFPeVpL2lth3zrxQFh7MVhw_RnD8Q=.13043746-8c61-474d-93b5-44743733441d@github.com>
 <3N5guZn5SiRlcjZrWQt0JbqUMJr79EcQ999JpVtx8-k=.cf3f71c3-4fcb-4958-b673-76b6b9797cd5@github.com>
 <aRyFeUB0t9pLvRy-awz2Kr2gh1RDsiB0YGsuWTSItCQ=.b313e672-413f-46af-b95f-8d87707a8d70@github.com>
Message-ID: <ss_jUjkp9czFGbMUUQ2nUdTrvJrFMmDv3zGUXtGTblw=.30fb6106-7606-41ee-8ecd-edc445286258@github.com>

On Thu, 8 Feb 2024 15:35:58 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Please update the DocComment printout in that commented out test: the actual content is different. It would be nice if the test were passing at least at the moment of its initial commit.
>> 
>> Here's what I see locally:
>> 
>> 
>> Expect:
>> DocComment[DOC_COMMENT, pos:0
>>   firstSentence: 1
>>     Summary[SUMMARY, pos:4
>>       summary: 1
>>         Erroneous[ERRONEOUS, pos:14, prefPos:37
>>           code: compiler.err.dc.unterminated.inline.tag
>>           body: abc_`|_def}|_rest_`more`
>>         ]
>>     ]
>>   body: empty
>>   block tags: empty
>> ]
>> 
>> Found:
>> DocComment[DOC_COMMENT, pos:0
>>   firstSentence: 1
>>     Summary[SUMMARY, pos:1
>>       summary: 1
>>         Erroneous[ERRONEOUS, pos:11, prefPos:32
>>           code: compiler.err.dc.unterminated.inline.tag
>>           body: abc_`|def}|rest_`more`
>>         ]
>>     ]
>>   body: empty
>>   block tags: empty
>> ]
>
> Ping.

Thanks for fixing the test and clarifying its comment.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484174598

From jjg at openjdk.org  Fri Feb  9 19:48:15 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 9 Feb 2024 19:48:15 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
In-Reply-To: <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0mlIFIZ2ec8oE2zlmKxoMwp59dBgOdUQs-vzTLnU7hI=.15fa2827-8c87-415b-ab74-0e42b45a5cf7@github.com>
 <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
Message-ID: <azswcdZYNHX6p00wKlN4P6z1EkXio2WNRdsXWWeDA_A=.be0d0648-f530-4262-aa7a-27bceea7e5df@github.com>

On Mon, 15 Jan 2024 12:20:57 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons 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 seven additional commits since the last revision:
>> 
>>  - Merge with upstream/master
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Address review comments
>>  - Fix whitespace
>>  - Improve handling of embedded inline taglets
>>  - Customize support for Markdown headings
>>  - JDK-8298405: Support Markdown in Documentation Comments
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 130:
> 
>> 128: 
>> 129:     /**
>> 130:      * Create a parser for a documentation comment.
> 
> Suggestion:
> 
>      * Creates a parser for a documentation comment.

Done

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484737196

From jjg at openjdk.org  Fri Feb  9 21:04:14 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 9 Feb 2024 21:04:14 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
In-Reply-To: <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0mlIFIZ2ec8oE2zlmKxoMwp59dBgOdUQs-vzTLnU7hI=.15fa2827-8c87-415b-ab74-0e42b45a5cf7@github.com>
 <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
Message-ID: <Pj1tkRMx-qPl7LG9T0ALXZyMtirj4CA-QB3hQ0TNxA4=.d18c10bf-fcde-40fa-b914-a197b2dd395f@github.com>

On Mon, 15 Jan 2024 11:48:23 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons 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 seven additional commits since the last revision:
>> 
>>  - Merge with upstream/master
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Address review comments
>>  - Fix whitespace
>>  - Improve handling of embedded inline taglets
>>  - Customize support for Markdown headings
>>  - JDK-8298405: Support Markdown in Documentation Comments
>
> src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java line 299:
> 
>> 297:      * @param code the code
>> 298:      * @return a {@code RawTextTree} object
>> 299:      * @throws IllegalArgumentException if the kind is not a recognized kind for raw text
> 
> This method's implementation also throws `NullPointerException` if kind is null, which is unusual for these methods. You can either add `@throws`, or workaround it by using `String.valueOf(kind)` instead of `kind.toString()` down in the implementation.

It took me a while to understand this comment.
For here and now, I will use `String.valueOf(kind)`
Long term, it would be good to better document `null` behavior in this API. 
[JDK-8325577](https://bugs.openjdk.org/browse/JDK-8325577)

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484798682

From jjg at openjdk.org  Fri Feb  9 21:20:08 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 9 Feb 2024 21:20:08 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v6]
In-Reply-To: <WYXUTmwMTgMP4YjGJk4CIxXFqZ6LwAhhjHOgjDVkOU4=.7a797721-e94f-44a8-8cea-78f761187d0f@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0mlIFIZ2ec8oE2zlmKxoMwp59dBgOdUQs-vzTLnU7hI=.15fa2827-8c87-415b-ab74-0e42b45a5cf7@github.com>
 <6df9dQzBK0M7SlHDpNO4T_bhE7i6WqwLP64cs6Df9A8=.e08f76a3-8753-4bad-9325-b0ab042645a4@github.com>
 <WYXUTmwMTgMP4YjGJk4CIxXFqZ6LwAhhjHOgjDVkOU4=.7a797721-e94f-44a8-8cea-78f761187d0f@github.com>
Message-ID: <PiqEAJdFc4w3Ub9drdvdE5s33UBmL1Q03c0EDvlb2P8=.bdf13154-75a0-45bf-848f-3ce4855c4ac7@github.com>

On Fri, 9 Feb 2024 18:27:59 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 201:
>> 
>>> 199:                 }
>>> 200:                 newline = true;
>>> 201:             }
>> 
>> I can see clean LF and CRLF, but no FF; was the latter intentional?
>> 
>> In any case, we should double-check the generated test output to see if there's anything unexpected.
>
> We've been here, with `\f` before, noting the different handling of `\f` in `javac` and `javadoc`.
> 
> My recollection is that it was intentional to drop support for `\f`, thus aligning `javac` and `javadoc` behavior, and to normalize handling of the newline sequences, translating them to `\n`.

> In any case, we should double-check the generated test output to see if there's anything unexpected.

verified tests pass and no change in generated JDK API docs

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1484812046

From jjg at openjdk.org  Fri Feb  9 21:24:25 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 9 Feb 2024 21:24:25 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v29]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <034sIbO5WNQTE779M9KSaGfIefM0m50Hsle5KBc_QH8=.1703bc55-c733-4702-b064-54bd65173cff@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  address review feedback

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/91588bc3..d22668da

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=28
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=27-28

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

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

From jjg at openjdk.org  Fri Feb  9 22:17:43 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 9 Feb 2024 22:17:43 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v30]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <jyz30BnzzLWkefI92p092QSHqOafHMQSP4819QxpS_8=.c548e7cc-33c2-4c26-9d89-65de18397cfe@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  refactor recent new test case in TestMarkdown.java

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/d22668da..3f8aa6b5

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=29
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=28-29

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

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

From ihse at openjdk.org  Mon Feb 12 08:11:03 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Mon, 12 Feb 2024 08:11:03 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
In-Reply-To: <rB3HxteVgSXBiQnLDLdYgc2jXTL2fFPg5zdCQwxHt1g=.37699c1c-1dad-4451-b364-38d1b2170957@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
 <rB3HxteVgSXBiQnLDLdYgc2jXTL2fFPg5zdCQwxHt1g=.37699c1c-1dad-4451-b364-38d1b2170957@github.com>
Message-ID: <8BLLuuu7gTj4P8bDZ40PWRJDT7668CSSqMiywzlPrIs=.1f188e66-2327-43e3-b30e-16798937eefe@github.com>

On Fri, 9 Feb 2024 18:09:11 GMT, Naoto Sato <naoto at openjdk.org> wrote:

>> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
>> 
>> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
>> 
>> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.
>
> Skimmed through the changes and all look good to me. Good to have `jcheck` detect those unneeded trailing spaces.

@naotoj Thanks! Would you care to also submit a review?

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

PR Comment: https://git.openjdk.org/jdk/pull/17789#issuecomment-1938204446

From prappo at openjdk.org  Mon Feb 12 15:30:10 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 12 Feb 2024 15:30:10 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <e0aoGsEBu6BxJgwRLe8EWXsZuRzJYC8POqB22FVVWhE=.c15250b4-1680-48d7-82de-bb512e0f3afd@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <HZQiJKB0i4jqcVhsKgdzF3_q0vXLC2IIEi6JeZpdq5w=.5cc0180c-8db2-4768-ad38-95aa3ec85403@github.com>
 <e0aoGsEBu6BxJgwRLe8EWXsZuRzJYC8POqB22FVVWhE=.c15250b4-1680-48d7-82de-bb512e0f3afd@github.com>
Message-ID: <wicEi4HomuO7CTYRviD8GDZWm0FcNgauHW-2Nd3mJxc=.ea6da35a-ec2b-434e-909d-0a7119739829@github.com>

On Tue, 30 Jan 2024 23:15:32 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java line 790:
>> 
>>> 788: 
>>> 789:         // end of paragraph is newline, followed by a blank line or the beginning of the next block
>>> 790:         private static final Pattern endPara = Pattern.compile("\n(([ \t]*\n)|( {0,3}[-+*#=]))");
>> 
>> So DocTreeMaker now also knows about Markdown. I wonder if we can avoid that. Also, I assume you mean this (`+` is not a part of "thematic break"):
>> Suggestion:
>> 
>>         private static final Pattern endPara = Pattern.compile("\n(([ \t]*\n)|( {0,3}[-_*#=]))");
>
> The code is doing its best to model the non-Markdown behavior, which is to detect paragraph breaks, which terminate the first sentence in the absence of any period.
> 
> `+` is in the pattern as a list marker; I added `_` for thematic break, and added more comments.

I can see that you have fixed it to recognise lists `+` and thematic breaks `_`; good.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486343596

From prappo at openjdk.org  Mon Feb 12 15:47:08 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 12 Feb 2024 15:47:08 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <HfTVo2rOdZeEXe3qGclLIHgptXeQ568_eWNRU66dOWU=.94fa57b9-1e4d-4151-a7f7-0cbd66598f50@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <zrqu3x52AXuB6DBs1kg66rC0arBB3MUFFokkL8CIF_k=.7935ef71-4d3c-4246-bf5c-afe5fd5fb625@github.com>
 <82KgOfWLlL77CZkJUnSaiWxaSuu4C1uLkzr6BHnCUd4=.aeeb8842-7c6c-4db3-bf70-690e0008f74c@github.com>
 <HfTVo2rOdZeEXe3qGclLIHgptXeQ568_eWNRU66dOWU=.94fa57b9-1e4d-4151-a7f7-0cbd66598f50@github.com>
Message-ID: <gqNWtYhM4nv9c-cGDwvZJgu1AvfCoBDaGbhns5kdgQ0=.14b7c2ac-aed4-4e0e-906d-1204f73404e1@github.com>

On Wed, 31 Jan 2024 22:15:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> I guess I don't see this as being as big a deal as you seem to think it is. What is it that you are so concerned about?
>> 
>> I also think it is a potential feature to document and use reference links with `code:` URLs, using the reference link syntax to avoid having long method signatures in narrative text.
>> 
>> For example, 
>> 
>>    One of the methods on [List] has [lots of args][List.of10].
>>    
>>    [List.of10]code:List.of(E,E,E,E,E,E,E,E,E,E)
>
> I've changed the prefix to be dynamically generated. It's now called `autorefScheme` and is passed around as needed. It contains a hex hashcode, so is reasonably unguessable.
> 
> I'm still sort-of sad to lose the ability to use `code:` URLs directly, so I've left a comment in the code hinting that that is a possibility.

Thanks for accepting this; we could revert it later if the fixed, known scheme is deemed more useful.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486364459

From prappo at openjdk.org  Mon Feb 12 15:47:08 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 12 Feb 2024 15:47:08 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <xdbBz5jNKMyTzPYYjGZ993AJ53U6DQm-LZHahZLLKfc=.0de14de4-08fe-435b-a173-6d7c5518d21b@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <zrqu3x52AXuB6DBs1kg66rC0arBB3MUFFokkL8CIF_k=.7935ef71-4d3c-4246-bf5c-afe5fd5fb625@github.com>
 <UbOd3C2ZrB35hFrkossEp7LIUWFk9dpBZh6v8IS0HeA=.84a2e253-8eb2-40fc-8256-c38a8a4e4399@github.com>
 <t12_cx8L88XOIB668UOHrnt7TPsyJiVC48ic7BribrI=.4b9996e0-a930-48cb-a8f4-6f2f7e0d717a@github.com>
 <9udnoUCtCVEEO3rIQypPb3f14bMp6wVRRO4x0yNKZpw=.b1245fbf-e2eb-44c1-9b44-76ccbefe200f@github.com>
 <xdbBz5jNKMyTzPYYjGZ993AJ53U6DQm-LZHahZLLKfc=.0de14de4-08fe-435b-a173-6d7c5518d21b@github.com>
Message-ID: <TiPSARTKDJ4VWiM_lCretvQrNBUbUhKUS98BnHF49h8=.b1a6fe08-5b70-46e9-a586-bf4f085fd5f0@github.com>

On Thu, 1 Feb 2024 00:19:42 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> I'll add a test case.
>
> Done

Thank you. I double-checked: if that `replace` is removed, jdk/javadoc/doclet/testMarkdown/TestMarkdown.java fails.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486361794

From prappo at openjdk.org  Mon Feb 12 15:47:09 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 12 Feb 2024 15:47:09 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <82KgOfWLlL77CZkJUnSaiWxaSuu4C1uLkzr6BHnCUd4=.aeeb8842-7c6c-4db3-bf70-690e0008f74c@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <zrqu3x52AXuB6DBs1kg66rC0arBB3MUFFokkL8CIF_k=.7935ef71-4d3c-4246-bf5c-afe5fd5fb625@github.com>
 <82KgOfWLlL77CZkJUnSaiWxaSuu4C1uLkzr6BHnCUd4=.aeeb8842-7c6c-4db3-bf70-690e0008f74c@github.com>
Message-ID: <WsEs4rMgpP1bgJihQA4Cn137iqTAf4DzI4LL0HC2Rvk=.bc95846d-55d9-47f8-9552-0e84087832ea@github.com>

On Tue, 30 Jan 2024 23:47:00 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 771:
>> 
>>> 769:                 copyTo(getStartPos(link));
>>> 770:                 // push temporary value for {@code trees} while handling the content of the node
>>> 771:                 var saveTrees = trees;
>> 
>> "saveTrees": I see what you did there :-)
>
> ?? Not sure I understand this comment.

It's just a funny word play evoking the famous eco slogan, is all.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486368352

From prappo at openjdk.org  Mon Feb 12 15:57:09 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 12 Feb 2024 15:57:09 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v7]
In-Reply-To: <5-LBnp9pQaksnQQQIe1MPmqdKGD2-0-UZgNnhtY5294=.db5cb4ce-dd03-4d5e-8533-48fdf15d9371@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <0pRMUgBnvCfb7DTm_pDnIlmuYdXH8URKFAIk5cT082Y=.f4c324b6-ef98-41b3-9b06-9cb82e03b08f@github.com>
 <MDprROiV35Q1rjuL_TD_cFkhYEGkN2B-xuH3eRcz0e0=.878238df-e7fd-4054-918b-17f77a5a4ecd@github.com>
 <5-LBnp9pQaksnQQQIe1MPmqdKGD2-0-UZgNnhtY5294=.db5cb4ce-dd03-4d5e-8533-48fdf15d9371@github.com>
Message-ID: <XAE5labHBGRVMR4FpGRSlq9RLdRhn1ynU2ObVOx8UJ4=.d41b9dcc-4f9a-493c-9a0e-41d34879a73b@github.com>

On Thu, 8 Feb 2024 18:52:54 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java line 145:
>> 
>>> 143:     }
>>> 144: 
>>> 145:     Pattern tag = Pattern.compile("<(?<tag>[A-Za-z0-9]+)(\\s|>)");
>> 
>> I'm not sure I grok this pattern; what's up with `\\s`?
>
> The code is looking for HTML tag names, The match for a tag name is one of
> * `<` _tag-name_ `>`
> * `<` _tag-name_ _whitespace_

I see, thanks.
Suggestion:

    private final Pattern tag = Pattern.compile("<(?<tag>[A-Za-z0-9]+)(\\s|>)");

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486384478

From abimpoudis at openjdk.org  Mon Feb 12 16:17:24 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Mon, 12 Feb 2024 16:17:24 GMT
Subject: RFR: 8325653: Erroneous exhaustivity analysis for primitive patterns
Message-ID: <Sg2H-e-fw0C4A9HABFSqKVeFyFZ0XBgHN-ItGnaLy6U=.8062003d-7e96-49b7-b675-6cb844e14912@github.com>

This PR fixes an exhaustivity analysis issue with primitive patterns, that was implementing the clause in [14.11.1.1](https://cr.openjdk.org/~abimpoudis/instanceof/jep455-20240122/specs/instanceof-jls.html#jls-14.11.1.1) (in the case where the selector is a reference type) erroneously.

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

Commit messages:
 - 8325653: Erroneous exhaustivity analysis for primitive patterns

Changes: https://git.openjdk.org/jdk/pull/17810/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17810&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325653
  Stats: 31 lines in 3 files changed: 27 ins; 0 del; 4 mod
  Patch: https://git.openjdk.org/jdk/pull/17810.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17810/head:pull/17810

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

From jjg at openjdk.org  Mon Feb 12 16:34:10 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 12 Feb 2024 16:34:10 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
In-Reply-To: <Fi4NuaFltjeOrEITZ6UI3osRWtQrnoDx566UsfCL0EE=.a042889e-e4f0-4ba7-b2f9-04b1d36c510d@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <vrwe2U_b9K6EUSg760EHhm3x7sz2tp0D4thYIqknnGw=.e5c1c331-644a-4473-8a8b-d3c8f3128303@github.com>
 <Fi4NuaFltjeOrEITZ6UI3osRWtQrnoDx566UsfCL0EE=.a042889e-e4f0-4ba7-b2f9-04b1d36c510d@github.com>
Message-ID: <I_HQtpxnIvC3m3U8px26lJifLB5vUuw_PjQMUjn2nus=.c02f3cb7-5786-4095-bb87-7f7b7bfa42f0@github.com>

On Thu, 8 Feb 2024 17:20:23 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 28 commits:
>> 
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it
>>    merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.
>>  - add test case contributed by @lahodaj
>>  - initial fix for source offset problem
>>  - remove unused imports
>>  - First pass at remove DocCommentTransformer from the public API.
>>    
>>    It is still declared internally, and installed by default, using the service-provider mechanism.
>>    If the standard impl is not available, an identity transformer is used.
>>  - updates for "first sentence" issues and tests
>>  - add info about provenance of `jdk.internal.md` module
>>  - MarkdownTransformer: tweak doc comments
>>  - MarkdownTransformer: change `Lower.replaceIter` to be `private final`
>>  - MarkdownTransformer: use suggested text for using streams
>>  - ... and 18 more: https://git.openjdk.org/jdk/compare/18e24d06...63dd8bf4
>
> src/jdk.internal.md/share/classes/module-info.java line 41:
> 
>> 39: // * package and import statements are updated
>> 40: // * characters outside the ASCII range are converted to Unicode escapes
>> 41: // * @SuppressWarnings("fallthrough") is added to getSetextHeadingLevel
> 
> I wonder if it would be better to compile this module without (some) lint checks. Is it possible?

It's possible, but that would be a more global setting, whereas this is a very targeted modification.

I guess it depends how much we want to import the code as-is, without knowing any lint-warts.

FWIW, any module can be compiled with module-specific lint settings, if we choose to do so.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486450189

From prappo at openjdk.org  Mon Feb 12 17:27:14 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 12 Feb 2024 17:27:14 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
In-Reply-To: <I_HQtpxnIvC3m3U8px26lJifLB5vUuw_PjQMUjn2nus=.c02f3cb7-5786-4095-bb87-7f7b7bfa42f0@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <vrwe2U_b9K6EUSg760EHhm3x7sz2tp0D4thYIqknnGw=.e5c1c331-644a-4473-8a8b-d3c8f3128303@github.com>
 <Fi4NuaFltjeOrEITZ6UI3osRWtQrnoDx566UsfCL0EE=.a042889e-e4f0-4ba7-b2f9-04b1d36c510d@github.com>
 <I_HQtpxnIvC3m3U8px26lJifLB5vUuw_PjQMUjn2nus=.c02f3cb7-5786-4095-bb87-7f7b7bfa42f0@github.com>
Message-ID: <qQg5KGUPY08AUSD7dN2bubu21q8r79NPgcuqZBXgefg=.f2d7f31f-8266-4b0b-9ae9-2df72e720a41@github.com>

On Mon, 12 Feb 2024 16:29:19 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> I guess it depends how much we want to import the code as-is, without knowing any lint-warts.

I think it would be nice not to have to modify code beyond superficial edits: addition of headers, renaming of packages, and converting of non-ASCII symbols.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486526603

From jjg at openjdk.org  Mon Feb 12 17:30:09 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 12 Feb 2024 17:30:09 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
In-Reply-To: <qQg5KGUPY08AUSD7dN2bubu21q8r79NPgcuqZBXgefg=.f2d7f31f-8266-4b0b-9ae9-2df72e720a41@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <vrwe2U_b9K6EUSg760EHhm3x7sz2tp0D4thYIqknnGw=.e5c1c331-644a-4473-8a8b-d3c8f3128303@github.com>
 <Fi4NuaFltjeOrEITZ6UI3osRWtQrnoDx566UsfCL0EE=.a042889e-e4f0-4ba7-b2f9-04b1d36c510d@github.com>
 <I_HQtpxnIvC3m3U8px26lJifLB5vUuw_PjQMUjn2nus=.c02f3cb7-5786-4095-bb87-7f7b7bfa42f0@github.com>
 <qQg5KGUPY08AUSD7dN2bubu21q8r79NPgcuqZBXgefg=.f2d7f31f-8266-4b0b-9ae9-2df72e720a41@github.com>
Message-ID: <2ASC_hZEZa6tXgQaHWm690WnGxWOQOzDzMkgCi1I8Ug=.3884f658-b1f5-4016-9195-6784dc5b407e@github.com>

On Mon, 12 Feb 2024 17:23:56 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> It's possible, but that would be a more global setting, whereas this is a very targeted modification.
>> 
>> I guess it depends how much we want to import the code as-is, without knowing any lint-warts.
>> 
>> FWIW, any module can be compiled with module-specific lint settings, if we choose to do so.
>
>> I guess it depends how much we want to import the code as-is, without knowing any lint-warts.
> 
> I think it would be nice not to have to modify code beyond superficial edits: addition of headers, renaming of packages, and converting of non-ASCII symbols.

I think adding `@SuppressWarnings` is a superficial edit, but I see the writing on the wall.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486531142

From naoto at openjdk.org  Mon Feb 12 17:37:56 2024
From: naoto at openjdk.org (Naoto Sato)
Date: Mon, 12 Feb 2024 17:37:56 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
In-Reply-To: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
Message-ID: <NscNVRE66ok6SSHmMGQaeVZSxYEnWS_WzhLMve54xbU=.5ecae045-37aa-45aa-86c3-926bfb04599e@github.com>

On Fri, 9 Feb 2024 13:35:55 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
> 
> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
> 
> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.

> @naotoj Thanks! Would you care to also submit a review?

My bad. I thought I approved this PR.

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

Marked as reviewed by naoto (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17789#pullrequestreview-1875811619

From dfuchs at openjdk.org  Mon Feb 12 17:42:06 2024
From: dfuchs at openjdk.org (Daniel Fuchs)
Date: Mon, 12 Feb 2024 17:42:06 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
In-Reply-To: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
Message-ID: <aP9GcIjHZudg8GUlGYhOK4kUlFo5m6aWU4_adCeIIU8=.8634bdeb-198c-4827-b90f-bdee1a94e0f4@github.com>

On Fri, 9 Feb 2024 13:35:55 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
> 
> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
> 
> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.

Approving the sun.net changes.

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

Marked as reviewed by dfuchs (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17789#pullrequestreview-1875818676

From prappo at openjdk.org  Mon Feb 12 17:48:09 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Mon, 12 Feb 2024 17:48:09 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v30]
In-Reply-To: <jyz30BnzzLWkefI92p092QSHqOafHMQSP4819QxpS_8=.c548e7cc-33c2-4c26-9d89-65de18397cfe@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <jyz30BnzzLWkefI92p092QSHqOafHMQSP4819QxpS_8=.c548e7cc-33c2-4c26-9d89-65de18397cfe@github.com>
Message-ID: <CW0r0SR17XtCUmH695N_7pNv1sgAMEHEuIXVGXUTGsU=.ed41f8a4-795c-4a51-a9d9-4867ced745f7@github.com>

On Fri, 9 Feb 2024 22:17:43 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   refactor recent new test case in TestMarkdown.java

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1465:

> 1463:                         markdownInput.append('\n');
> 1464:                     }
> 1465:                     markdownInput.append(PLACEHOLDER_BLOCK);

There's quite a lot of overlap with the recently simplified https://github.com/openjdk/jdk/blob/7c6316886d1ae86a663d996dae373c42281622fd/src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java#L220-L238

If it's impractical to factor out the common bits, maybe we could at least make the respective parts of HtmlDocletWriter as close as possible to those of MarkdownTransformer.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486548869

From jjg at openjdk.org  Mon Feb 12 18:39:10 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 12 Feb 2024 18:39:10 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v30]
In-Reply-To: <CW0r0SR17XtCUmH695N_7pNv1sgAMEHEuIXVGXUTGsU=.ed41f8a4-795c-4a51-a9d9-4867ced745f7@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <jyz30BnzzLWkefI92p092QSHqOafHMQSP4819QxpS_8=.c548e7cc-33c2-4c26-9d89-65de18397cfe@github.com>
 <CW0r0SR17XtCUmH695N_7pNv1sgAMEHEuIXVGXUTGsU=.ed41f8a4-795c-4a51-a9d9-4867ced745f7@github.com>
Message-ID: <zkV7ZHVcTqBE2r4AFZGaaAF7KBQT6-roaka9NJ3eI4c=.3c0be81f-6c5a-4a03-a56d-280dcb731dce@github.com>

On Mon, 12 Feb 2024 17:44:29 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   refactor recent new test case in TestMarkdown.java
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1465:
> 
>> 1463:                         markdownInput.append('\n');
>> 1464:                     }
>> 1465:                     markdownInput.append(PLACEHOLDER_BLOCK);
> 
> There's quite a lot of overlap with the recently simplified https://github.com/openjdk/jdk/blob/7c6316886d1ae86a663d996dae373c42281622fd/src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java#L220-L238
> 
> If it's impractical to factor out the common bits, maybe we could at least make the respective parts of HtmlDocletWriter as close as possible to those of MarkdownTransformer.

I think it is impractical to factor out the common bits, but I will look at the possibility of making the code more similar -- but no promises.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486609585

From jjg at openjdk.org  Mon Feb 12 19:39:06 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 12 Feb 2024 19:39:06 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v22]
In-Reply-To: <2ASC_hZEZa6tXgQaHWm690WnGxWOQOzDzMkgCi1I8Ug=.3884f658-b1f5-4016-9195-6784dc5b407e@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <vrwe2U_b9K6EUSg760EHhm3x7sz2tp0D4thYIqknnGw=.e5c1c331-644a-4473-8a8b-d3c8f3128303@github.com>
 <Fi4NuaFltjeOrEITZ6UI3osRWtQrnoDx566UsfCL0EE=.a042889e-e4f0-4ba7-b2f9-04b1d36c510d@github.com>
 <I_HQtpxnIvC3m3U8px26lJifLB5vUuw_PjQMUjn2nus=.c02f3cb7-5786-4095-bb87-7f7b7bfa42f0@github.com>
 <qQg5KGUPY08AUSD7dN2bubu21q8r79NPgcuqZBXgefg=.f2d7f31f-8266-4b0b-9ae9-2df72e720a41@github.com>
 <2ASC_hZEZa6tXgQaHWm690WnGxWOQOzDzMkgCi1I8Ug=.3884f658-b1f5-4016-9195-6784dc5b407e@github.com>
Message-ID: <a6Kn7uMmbMnqUknoiHshT_JDcZyMGcWW9oyH22VZTQ0=.5ce739b4-9401-4d12-a725-d8045ccac564@github.com>

On Mon, 12 Feb 2024 17:27:42 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>>> I guess it depends how much we want to import the code as-is, without knowing any lint-warts.
>> 
>> I think it would be nice not to have to modify code beyond superficial edits: addition of headers, renaming of packages, and converting of non-ASCII symbols.
>
> I think adding `@SuppressWarnings` is a superficial edit, but I see the writing on the wall.

Based on additional private conversations, and because the annotation is added automatically by the same utility used to address other issues in the imported code (package declarations, import statements, non-ASCII characters, etc), I will leave the annotation in at this time.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1486674245

From joehw at openjdk.org  Mon Feb 12 20:25:59 2024
From: joehw at openjdk.org (Joe Wang)
Date: Mon, 12 Feb 2024 20:25:59 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
In-Reply-To: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
Message-ID: <o8ZfKM3dvC-eD-ryNHYogkK94Ha8ArlUiw1qb9Bw51U=.bc0a293b-0dff-43d9-98d0-a798b2ba2dc7@github.com>

On Fri, 9 Feb 2024 13:35:55 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
> 
> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
> 
> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.

java.xml changes look fine to me.

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

Marked as reviewed by joehw (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17789#pullrequestreview-1876181019

From joehw at openjdk.org  Mon Feb 12 20:26:00 2024
From: joehw at openjdk.org (Joe Wang)
Date: Mon, 12 Feb 2024 20:26:00 GMT
Subject: RFR: 8325558: Add jcheck whitespace checking for properties files
In-Reply-To: <aiUe8udp6Qtknwo8Ha3jenZ_TP_SMD5baGxnNlNz7WI=.86e01229-6456-4e46-ad0c-1e74c84c7c63@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
 <aiUe8udp6Qtknwo8Ha3jenZ_TP_SMD5baGxnNlNz7WI=.86e01229-6456-4e46-ad0c-1e74c84c7c63@github.com>
Message-ID: <xLIVBeMz0nzp8xjs9ukxIJ1CAe4Aflvz0mtCgDL3RU4=.61371bf6-7719-4bc5-9537-df645d3fa640@github.com>

On Fri, 9 Feb 2024 13:46:06 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
>> 
>> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
>> 
>> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.
>
> src/java.xml/share/classes/com/sun/org/apache/xerces/internal/impl/msg/XPointerMessages.properties line 24:
> 
>> 22: # Messages for message reporting
>> 23: BadMessageKey = The error message corresponding to the message key can not be found.
>> 24: FormatFailed = An internal error occurred while formatting the following message:\n
> 
> Same here with `:\n`...

It's done with the code (that is, a key is appended with the code). In fact, the whole Xerces stack was implemented this way. I'd leave it as is.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17789#discussion_r1486731927

From jjg at openjdk.org  Mon Feb 12 23:52:35 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 12 Feb 2024 23:52:35 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <Imc_x0a26ALH3KO5jdgjvvwqZ8SL7eC-cotk7AphhRI=.8fcfe332-53cd-4aa9-8ff7-fc2082b23ece@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 40 commits:

 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - improve support for DocCommentParser.LineKind
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the
   commit.
 - update copyright year on test
 - refactor recent new test case in TestMarkdown.java
 - address review feedback
 - address review feedback
 - added test case in TestMarkdown.java for handling of `@deprecated` tag
 - amend comment in test
 - improve comments on negative test case
 - ... and 30 more: https://git.openjdk.org/jdk/compare/2ed889b7...1c64a6e0

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

Changes: https://git.openjdk.org/jdk/pull/16388/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=30
  Stats: 22058 lines in 194 files changed: 21390 ins; 271 del; 397 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From abimpoudis at openjdk.org  Tue Feb 13 09:35:08 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Tue, 13 Feb 2024 09:35:08 GMT
Subject: RFR: 8325653: Erroneous exhaustivity analysis for primitive
 patterns [v2]
In-Reply-To: <Sg2H-e-fw0C4A9HABFSqKVeFyFZ0XBgHN-ItGnaLy6U=.8062003d-7e96-49b7-b675-6cb844e14912@github.com>
References: <Sg2H-e-fw0C4A9HABFSqKVeFyFZ0XBgHN-ItGnaLy6U=.8062003d-7e96-49b7-b675-6cb844e14912@github.com>
Message-ID: <XH0P2155bzpBhEC2IaNRKFuVMsj1pvYh-D4KcYgXusw=.86899bfa-8350-492c-b232-711cc2df4814@github.com>

> This PR fixes an exhaustivity analysis issue with primitive patterns, that was implementing the clause in [14.11.1.1](https://cr.openjdk.org/~abimpoudis/instanceof/jep455-20240122/specs/instanceof-jls.html#jls-14.11.1.1) (in the case where the selector is a reference type) erroneously.

Aggelos Biboudis has updated the pull request incrementally with one additional commit since the last revision:

  Cleanup

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17810/files
  - new: https://git.openjdk.org/jdk/pull/17810/files/7064dd36..8dd340b3

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17810&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17810&range=00-01

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

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

From ihse at openjdk.org  Tue Feb 13 10:03:08 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Tue, 13 Feb 2024 10:03:08 GMT
Subject: Integrated: 8325558: Add jcheck whitespace checking for properties
 files
In-Reply-To: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
References: <Uwmj8L0as9HbHd362qpSAArpgCzYvkAyI6OOSq5J9Dk=.670c5220-c7df-40cc-817d-f0cf55fbb955@github.com>
Message-ID: <1_5f_JhU7k2LuEKn7w-rn3FkkBpaBDiz3o_uBy-uKiw=.7ed5bef7-6484-435f-8d87-12dadc4d9e9d@github.com>

On Fri, 9 Feb 2024 13:35:55 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is an attempt to finally implement the idea brought forward in JDK-8295729:  Properties files is essentially source code. It should have the same whitespace checks as all other source code, so we don't get spurious trailing whitespace changes or leading tabs instead of spaces. 
> 
> With Skara jcheck, it is possible to increase the coverage of the whitespace checks.
> 
> However, this turned out to be problematic, since trailing whitespace is significant in properties files. That issue has mostly been sorted out in a series of PRs, and this patch will finish the job with the few remaining files, and actually enable the check in jcheck.

This pull request has now been integrated.

Changeset: c266800a
Author:    Magnus Ihse Bursie <ihse at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/c266800a3a7dd44416b0b4df3bdd78410241d74b
Stats:     761 lines in 95 files changed: 0 ins; 5 del; 756 mod

8325558: Add jcheck whitespace checking for properties files

Reviewed-by: naoto, dfuchs, joehw

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

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

From vromero at openjdk.org  Tue Feb 13 16:39:05 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Tue, 13 Feb 2024 16:39:05 GMT
Subject: RFR: 8325653: Erroneous exhaustivity analysis for primitive
 patterns [v2]
In-Reply-To: <XH0P2155bzpBhEC2IaNRKFuVMsj1pvYh-D4KcYgXusw=.86899bfa-8350-492c-b232-711cc2df4814@github.com>
References: <Sg2H-e-fw0C4A9HABFSqKVeFyFZ0XBgHN-ItGnaLy6U=.8062003d-7e96-49b7-b675-6cb844e14912@github.com>
 <XH0P2155bzpBhEC2IaNRKFuVMsj1pvYh-D4KcYgXusw=.86899bfa-8350-492c-b232-711cc2df4814@github.com>
Message-ID: <dWRPTfucJ7c-XmRZreuXB58rhdNiPynqdcXVnudmn94=.0ebc6f9f-28fe-48df-b580-e1d518e3ce45@github.com>

On Tue, 13 Feb 2024 09:35:08 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

>> This PR fixes an exhaustivity analysis issue with primitive patterns, that was implementing the clause in [14.11.1.1](https://cr.openjdk.org/~abimpoudis/instanceof/jep455-20240122/specs/instanceof-jls.html#jls-14.11.1.1) erroneously (in the case where the selector is a reference type).
>
> Aggelos Biboudis has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Cleanup

lgtm

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17810#pullrequestreview-1878456698

From prappo at openjdk.org  Tue Feb 13 18:18:10 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Tue, 13 Feb 2024 18:18:10 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]
In-Reply-To: <Imc_x0a26ALH3KO5jdgjvvwqZ8SL7eC-cotk7AphhRI=.8fcfe332-53cd-4aa9-8ff7-fc2082b23ece@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <Imc_x0a26ALH3KO5jdgjvvwqZ8SL7eC-cotk7AphhRI=.8fcfe332-53cd-4aa9-8ff7-fc2082b23ece@github.com>
Message-ID: <revTaYUgM40q0U5bHloqsO56zzKGpaMVRdj_LLyHQrs=.047fe7ff-2f0e-4fad-b4b8-10bdee6b639c@github.com>

On Mon, 12 Feb 2024 23:52:35 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 40 commits:
> 
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>  - improve support for DocCommentParser.LineKind
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the
>    commit.
>  - update copyright year on test
>  - refactor recent new test case in TestMarkdown.java
>  - address review feedback
>  - address review feedback
>  - added test case in TestMarkdown.java for handling of `@deprecated` tag
>  - amend comment in test
>  - improve comments on negative test case
>  - ... and 30 more: https://git.openjdk.org/jdk/compare/2ed889b7...1c64a6e0

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 563:

> 561: 
> 562:     /**
> 563:      * {@returns the plain-text content of a named HTML element in a list of content}

Suggestion:

     * {@return the plain-text content of a named HTML element in a list of content}

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 1021:

> 1019:                     .findFirst();
> 1020:             if (first.isEmpty() || first.get() != tree) {
> 1021:                 dct.getFirstSentence().forEach(t -> System.err.println(t.getKind() + ": >>|" + t + "|<<"));

Is it leftover debug output?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 571:

> 569:         // of a doclet to be specified instead of the name of the
> 570:         // doclet class and optional doclet path.
> 571:         // See https://bugs.openjdk.org/browse/JDK-8263219

It's hard to understand this:

> to permit an instance of an appropriately configured instance of a doclet

Also: how is that piece of code used? When I commented it out, no test/langtools:langtools_javadoc tests failed.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1487629102
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1487659843
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1487642764

From abimpoudis at openjdk.org  Wed Feb 14 09:22:07 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Wed, 14 Feb 2024 09:22:07 GMT
Subject: Integrated: 8325653: Erroneous exhaustivity analysis for primitive
 patterns
In-Reply-To: <Sg2H-e-fw0C4A9HABFSqKVeFyFZ0XBgHN-ItGnaLy6U=.8062003d-7e96-49b7-b675-6cb844e14912@github.com>
References: <Sg2H-e-fw0C4A9HABFSqKVeFyFZ0XBgHN-ItGnaLy6U=.8062003d-7e96-49b7-b675-6cb844e14912@github.com>
Message-ID: <0A15qEk51We75kgvzsLeSU5U-2uOxbZutV1ouKO65JU=.f99b0268-ed86-4e56-bb81-18f5b574b2bc@github.com>

On Mon, 12 Feb 2024 16:12:14 GMT, Aggelos Biboudis <abimpoudis at openjdk.org> wrote:

> This PR fixes an exhaustivity analysis issue with primitive patterns, that was implementing the clause in [14.11.1.1](https://cr.openjdk.org/~abimpoudis/instanceof/jep455-20240122/specs/instanceof-jls.html#jls-14.11.1.1) erroneously (in the case where the selector is a reference type).

This pull request has now been integrated.

Changeset: 0c2def0e
Author:    Aggelos Biboudis <abimpoudis at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/0c2def0e3eaa4925746158294f798d37d42c50f3
Stats:     48 lines in 3 files changed: 28 ins; 13 del; 7 mod

8325653: Erroneous exhaustivity analysis for primitive patterns

Reviewed-by: vromero

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

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

From darcy at openjdk.org  Wed Feb 14 21:57:22 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Wed, 14 Feb 2024 21:57:22 GMT
Subject: RFR: JDK-8325687: SimpleJavaFileObject specification would benefit
 from implSpec
Message-ID: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>

While reading the spec in the context of another potential change, noticed some cases where using implSpec would lead to a better structured specification.

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

Commit messages:
 - JDK-8325687: SimpleJavaFileObject specification would benefit from implSpec

Changes: https://git.openjdk.org/jdk/pull/17854/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17854&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325687
  Stats: 41 lines in 2 files changed: 8 ins; 9 del; 24 mod
  Patch: https://git.openjdk.org/jdk/pull/17854.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17854/head:pull/17854

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

From jjg at openjdk.org  Thu Feb 15 00:30:25 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 00:30:25 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <5f-y-x2KRcAGr501XkShj08p51vAl8wxD8l8PYFcQmI=.08ee889e-8abb-47e2-b3ba-49bb09ae600d@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 44 commits:

 - fill in `visitRawText` in `CommentHelper.getTags` visitor
 - fixes for the "New API" page
 - change "standard" to "traditional" when referring to a comment
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
 - improve support for DocCommentParser.LineKind
 - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the
   commit.
 - update copyright year on test
 - refactor recent new test case in TestMarkdown.java
 - address review feedback
 - ... and 34 more: https://git.openjdk.org/jdk/compare/8765b176...2801c2e1

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

Changes: https://git.openjdk.org/jdk/pull/16388/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=31
  Stats: 22094 lines in 197 files changed: 21411 ins; 286 del; 397 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From wdietl at gmail.com  Thu Feb 15 14:59:03 2024
From: wdietl at gmail.com (Werner Dietl)
Date: Thu, 15 Feb 2024 09:59:03 -0500
Subject: diagnostics for non-applicable type annotations
In-Reply-To: <CAL4Qsguy5LayCJ8Ytr_=UHz-vcvdsWwOa6FG8DNp9w3spm12Rw@mail.gmail.com>
References: <CAL4QsgvWtaqG-9SarR8eut07tsmq0RRXAbK-JDd0FxApB+wPLA@mail.gmail.com>
 <CAEvq2noJ05eQNnHVoGVv80WXMcB7jL3FQp3qm1SubYO+THj6kg@mail.gmail.com>
 <CAL4Qsguy5LayCJ8Ytr_=UHz-vcvdsWwOa6FG8DNp9w3spm12Rw@mail.gmail.com>
Message-ID: <CAJYRO=6jCgX-kKu8VX6zyF9eVCsZ9oxx+4xZ8Y_0yg+VvM04ww@mail.gmail.com>

Thanks for fixing this issue, Liam!

The revised diagnostic is much better and including a suggested fix makes
it even more useful.
Like Chris said, this has been a frequent confusion for people.

I had a look at the PR in January and it looks good to me.
There needs to be some discussion
<https://github.com/openjdk/jdk/pull/16592#discussion_r1444978083> about
whether to use "admissible" or "applicable", but that's a quick fix.

I'm not a "R"eviewer, but do hope that we can get this PR merged. Please
let me know if there is anything I can do to help.

Best,
cu, WMD.


On Mon, Feb 5, 2024 at 7:09?PM Liam Miller-Cushon <cushon at google.com> wrote:

> Thanks Chris!
>
> Does anyone else have feedback on the proposal?
>
> On Tue, Jan 9, 2024 at 8:26?AM Chris Povirk <cpovirk at google.com> wrote:
>
>> Thanks, Liam.
>>
>> We've found the current error messages to be a source of confusion: While
>> the average user doesn't use type-use annotations, those users who do use
>> them seem to hit this pretty frequently. We have our own FAQ entry about it
>> in our internal documentation, and I also refer people to the Checker
>> Framework's documentation
>> <https://checkerframework.org/manual/#common-problems-non-typechecking>,
>> which gives advice similar to that implemented by Liam's PR. I would expect
>> for that page and this Stack Overflow answer
>> <https://stackoverflow.com/a/21385939/28465> to get more traffic as
>> type-use annotations grow in popularity, as we're aiming for them to do as
>> part of our work on JSpecify nullness. The error-message changes could save
>> users a trip to those docs.
>>
>

-- 
https://ece.uwaterloo.ca/~wdietl/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/compiler-dev/attachments/20240215/0ae1c534/attachment.htm>

From hgreule at openjdk.org  Thu Feb 15 17:05:21 2024
From: hgreule at openjdk.org (Hannes Greule)
Date: Thu, 15 Feb 2024 17:05:21 GMT
Subject: RFR: 8325936: jshell - crash on 'new Object().""'
Message-ID: <mmk7Z4PwD60HiIIDF7CyLwT_AuebEU861BQ7doT9jx4=.048e01de-431f-4693-acd7-01e8a5a6dc32@github.com>

This fixes a crash in jshell when the target of a StringTemplate is not a processor. We only look up the `process` method if the type is actually a processor. The added test case fails without that fix.

Please let me know what you think of this fix, and if there are things that should be changed.

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

Commit messages:
 - cleanup
 - add test case
 - Simplify, add test
 - Don't expect confusing errors
 - Fix fatal error when string template target is not a processor

Changes: https://git.openjdk.org/jdk/pull/17876/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17876&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325936
  Stats: 29 lines in 4 files changed: 12 ins; 10 del; 7 mod
  Patch: https://git.openjdk.org/jdk/pull/17876.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17876/head:pull/17876

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

From hgreule at openjdk.org  Thu Feb 15 17:05:21 2024
From: hgreule at openjdk.org (Hannes Greule)
Date: Thu, 15 Feb 2024 17:05:21 GMT
Subject: RFR: 8325936: jshell - crash on 'new Object().""'
In-Reply-To: <mmk7Z4PwD60HiIIDF7CyLwT_AuebEU861BQ7doT9jx4=.048e01de-431f-4693-acd7-01e8a5a6dc32@github.com>
References: <mmk7Z4PwD60HiIIDF7CyLwT_AuebEU861BQ7doT9jx4=.048e01de-431f-4693-acd7-01e8a5a6dc32@github.com>
Message-ID: <OVj2iS6RddjUVehML2ySYTIvnp_7cRx3F_3SXgIKd2A=.c7b11e1d-2720-49d3-81b8-a06f78545735@github.com>

On Thu, 15 Feb 2024 16:55:31 GMT, Hannes Greule <hgreule at openjdk.org> wrote:

> This fixes a crash in jshell when the target of a StringTemplate is not a processor. We only look up the `process` method if the type is actually a processor. The added test case fails without that fix.
> 
> Please let me know what you think of this fix, and if there are things that should be changed.

test/langtools/tools/javac/diags/examples/StringTemplateNotProcessor.java line 26:

> 24:  // key: compiler.note.preview.filename
> 25:  // key: compiler.err.cant.resolve.location.args
> 26:  // key: compiler.misc.location

I think this error was rather confusing, e.g.

Simple2.java:3: error: cannot find symbol
        System.out.println(e."{e}");
                             ^
  symbol:   method process(StringTemplate)
  location: class String

It mentions the `process` method while it's not visible in the code. It also always came directly after e.g.

Simple2.java:3: error: not a processor type: String
        System.out.println(e."{e}");

so it basically just caused 2 errors when there actually only is 1.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17876#discussion_r1491337338

From prappo at openjdk.org  Thu Feb 15 17:21:07 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 15 Feb 2024 17:21:07 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
In-Reply-To: <5f-y-x2KRcAGr501XkShj08p51vAl8wxD8l8PYFcQmI=.08ee889e-8abb-47e2-b3ba-49bb09ae600d@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <5f-y-x2KRcAGr501XkShj08p51vAl8wxD8l8PYFcQmI=.08ee889e-8abb-47e2-b3ba-49bb09ae600d@github.com>
Message-ID: <7hjkEusPyjQpzUGNArF4qKR_tSVyi3ekgkyX7gZ2LZw=.ad6b2cd6-f29b-4fca-b246-73572689180b@github.com>

On Thu, 15 Feb 2024 00:30:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 44 commits:
> 
>  - fill in `visitRawText` in `CommentHelper.getTags` visitor
>  - fixes for the "New API" page
>  - change "standard" to "traditional" when referring to a comment
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>  - improve support for DocCommentParser.LineKind
>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the
>    commit.
>  - update copyright year on test
>  - refactor recent new test case in TestMarkdown.java
>  - address review feedback
>  - ... and 34 more: https://git.openjdk.org/jdk/compare/8765b176...2801c2e1

I'm again looking `LineKind`. This time because of 9eaf84e5dd6.

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 422:

> 420:                             defaultContentCharacter();
> 421:                         }
> 422:                     }

Is it to pass `` through to Markdown, to allow it to deal with Markdown escapes?

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1401:

> 1399:      */
> 1400:     enum LineKind {
> 1401:         BLANK(Pattern.compile("[ \t]*")),

`BLANK` is a pseudo kind, because it is set manually, but never returned from `peekLine()`. I wonder if we can change it somehow.

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1433:

> 1431:          * @see <a href="https://spec.commonmark.org/0.30/#list-items">List items</a>
> 1432:          */
> 1433:         BULLETED_LIST_ITEM(Pattern.compile("[-+*] .*")),

This comment is about `BULLETED_LIST_ITEM` and `ORDERED_LIST_ITEM` constants. I know that we don't need to be very precise, but perhaps in this case we should. While the CommonMark spec is a vague on that, from my experiments with [dingus](https://spec.commonmark.org/dingus/), it appears that a list marker can be preceded and followed by some number of whitespace characters.

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

PR Review: https://git.openjdk.org/jdk/pull/16388#pullrequestreview-1883374712
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491362821
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491344667
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491354450

From jjg at openjdk.org  Thu Feb 15 19:04:18 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 19:04:18 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v33]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <ZWiDa55stEIAQtlU6oL0XUfqTEZlPe2UcWjBC9E_2js=.e2d42833-7e4a-40d4-aebc-718a94909f14@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  fix compilation and whitespace issues

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/2801c2e1..f6d08db9

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=32
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=31-32

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

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

From jjg at openjdk.org  Thu Feb 15 19:20:06 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 19:20:06 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]
In-Reply-To: <revTaYUgM40q0U5bHloqsO56zzKGpaMVRdj_LLyHQrs=.047fe7ff-2f0e-4fad-b4b8-10bdee6b639c@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <Imc_x0a26ALH3KO5jdgjvvwqZ8SL7eC-cotk7AphhRI=.8fcfe332-53cd-4aa9-8ff7-fc2082b23ece@github.com>
 <revTaYUgM40q0U5bHloqsO56zzKGpaMVRdj_LLyHQrs=.047fe7ff-2f0e-4fad-b4b8-10bdee6b639c@github.com>
Message-ID: <g82TmBi3DkRmU2UGOnXqtNsUSowqEHZOWGZv7171xOE=.695378bb-1a9e-4931-9db0-a7d43395e8cd@github.com>

On Tue, 13 Feb 2024 11:15:55 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 40 commits:
>> 
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - improve support for DocCommentParser.LineKind
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the
>>    commit.
>>  - update copyright year on test
>>  - refactor recent new test case in TestMarkdown.java
>>  - address review feedback
>>  - address review feedback
>>  - added test case in TestMarkdown.java for handling of `@deprecated` tag
>>  - amend comment in test
>>  - improve comments on negative test case
>>  - ... and 30 more: https://git.openjdk.org/jdk/compare/2ed889b7...1c64a6e0
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line 1021:
> 
>> 1019:                     .findFirst();
>> 1020:             if (first.isEmpty() || first.get() != tree) {
>> 1021:                 dct.getFirstSentence().forEach(t -> System.err.println(t.getKind() + ": >>|" + t + "|<<"));
> 
> Is it leftover debug output?

Oops, yes.  Thanks.

> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 571:
> 
>> 569:         // of a doclet to be specified instead of the name of the
>> 570:         // doclet class and optional doclet path.
>> 571:         // See https://bugs.openjdk.org/browse/JDK-8263219
> 
> It's hard to understand this:
> 
>> to permit an instance of an appropriately configured instance of a doclet
> 
> Also: how is that piece of code used? When I commented it out, no test/langtools:langtools_javadoc tests failed.

1.  Since forever, and still true, the way to specify a doclet is by its name, and the tool will create the instance for you.  This goes back to the original old days before any API, when the only entry point was the command line.
This implies that (a) the doclet has a no-args constructor and (b) that all doclet config is done through command line options.  A better solution would be to add new functionality to the various javadoc tool API (some or all of `Main`/`Start`/`DocumentationTool`) so that a client can initialize an instance of a doclet and pass that instance into the API.

2. If I understand the question correctly, the code is invoked by using the command-line option `-XDaccessInternalAPI` which is a preexisting hidden feature already supported by `javac`.  It is used in `TestTransformer.java` on line 161.

        javadoc("-d", base.resolve("api").toString(),
                "-Xdoclint:none",
                "-XDaccessInternalAPI", // required to access JavacTrees
                "-doclet", "TestTransformer$MyDoclet",
                "-docletpath", System.getProperty("test.classes"),
                "-sourcepath", src.toString(),
                "p");

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491504223
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491502389

From jjg at openjdk.org  Thu Feb 15 19:25:05 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 19:25:05 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
In-Reply-To: <7hjkEusPyjQpzUGNArF4qKR_tSVyi3ekgkyX7gZ2LZw=.ad6b2cd6-f29b-4fca-b246-73572689180b@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <5f-y-x2KRcAGr501XkShj08p51vAl8wxD8l8PYFcQmI=.08ee889e-8abb-47e2-b3ba-49bb09ae600d@github.com>
 <7hjkEusPyjQpzUGNArF4qKR_tSVyi3ekgkyX7gZ2LZw=.ad6b2cd6-f29b-4fca-b246-73572689180b@github.com>
Message-ID: <2S7ZUtfa7Dnc0ttfGUEG4F0hZbj78o5U6h3Spi-qzR0=.53d767bc-faec-4bd8-a916-9364efcf5d28@github.com>

On Thu, 15 Feb 2024 17:03:09 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 44 commits:
>> 
>>  - fill in `visitRawText` in `CommentHelper.getTags` visitor
>>  - fixes for the "New API" page
>>  - change "standard" to "traditional" when referring to a comment
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - improve support for DocCommentParser.LineKind
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the
>>    commit.
>>  - update copyright year on test
>>  - refactor recent new test case in TestMarkdown.java
>>  - address review feedback
>>  - ... and 34 more: https://git.openjdk.org/jdk/compare/8765b176...2801c2e1
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1401:
> 
>> 1399:      */
>> 1400:     enum LineKind {
>> 1401:         BLANK(Pattern.compile("[ \t]*")),
> 
> `BLANK` is a pseudo kind, because it is set manually, but never returned from `peekLine()`. I wonder if we can change it somehow.

Even if it is set manually, it is still appropriate to have it as a member in the `LineKind` enum class.

> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1433:
> 
>> 1431:          * @see <a href="https://spec.commonmark.org/0.30/#list-items">List items</a>
>> 1432:          */
>> 1433:         BULLETED_LIST_ITEM(Pattern.compile("[-+*] .*")),
> 
> This comment is about `BULLETED_LIST_ITEM` and `ORDERED_LIST_ITEM` constants. I know that we don't need to be very precise, but perhaps in this case we should. While the CommonMark spec is a vague on that, from my experiments with [dingus](https://spec.commonmark.org/dingus/), it appears that a list marker can be preceded and followed by some number of whitespace characters.

whitespace is handled separately, on line 280 (`readIndent`) and285 (`: (indent <= 3) ? peekLineKind()`)

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491508303
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491512611

From jjg at openjdk.org  Thu Feb 15 19:30:06 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 19:30:06 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
In-Reply-To: <7hjkEusPyjQpzUGNArF4qKR_tSVyi3ekgkyX7gZ2LZw=.ad6b2cd6-f29b-4fca-b246-73572689180b@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <5f-y-x2KRcAGr501XkShj08p51vAl8wxD8l8PYFcQmI=.08ee889e-8abb-47e2-b3ba-49bb09ae600d@github.com>
 <7hjkEusPyjQpzUGNArF4qKR_tSVyi3ekgkyX7gZ2LZw=.ad6b2cd6-f29b-4fca-b246-73572689180b@github.com>
Message-ID: <fWIF6Cid8DdR7xC7A7-CCs21YTSwt6LDII5XZ0mxfnM=.fa08a84e-24fe-4441-95ae-1568ec27ce5e@github.com>

On Thu, 15 Feb 2024 17:17:46 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 44 commits:
>> 
>>  - fill in `visitRawText` in `CommentHelper.getTags` visitor
>>  - fixes for the "New API" page
>>  - change "standard" to "traditional" when referring to a comment
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3
>>  - improve support for DocCommentParser.LineKind
>>  - Merge remote-tracking branch 'upstream/master' into 8298405.doclet-markdown-v3 # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the
>>    commit.
>>  - update copyright year on test
>>  - refactor recent new test case in TestMarkdown.java
>>  - address review feedback
>>  - ... and 34 more: https://git.openjdk.org/jdk/compare/8765b176...2801c2e1
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 422:
> 
>> 420:                             defaultContentCharacter();
>> 421:                         }
>> 422:                     }
> 
> Is it to pass `` through to Markdown, to allow it to deal with Markdown escapes?

It is more about supporting the sequence `` ` `` so that the backtick is treated as a literal character and not the beginning of a code span.   This is the "backstop" preferred way to ensure that a single backtick is treated literally, without relying on detected that it is unbalanced when the end of the current block is reached.  The alternative workaround would be a single backtick enclosed in multiple backticks, such as this ``` `` ` `` ```. (I leave you to figure out what I actually typed there!!!)

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491519707

From jjg at openjdk.org  Thu Feb 15 19:35:44 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 19:35:44 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v34]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <camkOJUbRfPCbUliYwMRzmXdrE4DAYIls3IpEl9FlEM=.6174333a-7172-41bd-a7c8-b6dd7c96f302@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:

 - fix return tag name
 - remove debug print

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/f6d08db9..393d3a9c

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=33
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=32-33

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

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

From jjg at openjdk.org  Thu Feb 15 19:35:44 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 19:35:44 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
In-Reply-To: <fWIF6Cid8DdR7xC7A7-CCs21YTSwt6LDII5XZ0mxfnM=.fa08a84e-24fe-4441-95ae-1568ec27ce5e@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <5f-y-x2KRcAGr501XkShj08p51vAl8wxD8l8PYFcQmI=.08ee889e-8abb-47e2-b3ba-49bb09ae600d@github.com>
 <7hjkEusPyjQpzUGNArF4qKR_tSVyi3ekgkyX7gZ2LZw=.ad6b2cd6-f29b-4fca-b246-73572689180b@github.com>
 <fWIF6Cid8DdR7xC7A7-CCs21YTSwt6LDII5XZ0mxfnM=.fa08a84e-24fe-4441-95ae-1568ec27ce5e@github.com>
Message-ID: <hWgzrX0mXRaqaRQl2drISdRMChmLivSG6jqW6kNlAAc=.3ddd7191-7386-4164-b14f-e6da398ac2fd@github.com>

On Thu, 15 Feb 2024 19:27:12 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 422:
>> 
>>> 420:                             defaultContentCharacter();
>>> 421:                         }
>>> 422:                     }
>> 
>> Is it to pass `` through to Markdown, to allow it to deal with Markdown escapes?
>
> It is more about supporting the sequence `` ` `` so that the backtick is treated as a literal character and not the beginning of a code span.   This is the "backstop" preferred way to ensure that a single backtick is treated literally, without relying on detected that it is unbalanced when the end of the current block is reached.  The alternative workaround would be a single backtick enclosed in multiple backticks, such as this ``` `` ` `` ```. (I leave you to figure out what I actually typed there!!!)

You might also need to use `` ` `` when there are two literal backticks in a sentence.

After the first backtick (`), another backtick (`) can be used to delimit a code span.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491528153

From jjg at openjdk.org  Thu Feb 15 19:39:06 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 19:39:06 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]
In-Reply-To: <g82TmBi3DkRmU2UGOnXqtNsUSowqEHZOWGZv7171xOE=.695378bb-1a9e-4931-9db0-a7d43395e8cd@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <Imc_x0a26ALH3KO5jdgjvvwqZ8SL7eC-cotk7AphhRI=.8fcfe332-53cd-4aa9-8ff7-fc2082b23ece@github.com>
 <revTaYUgM40q0U5bHloqsO56zzKGpaMVRdj_LLyHQrs=.047fe7ff-2f0e-4fad-b4b8-10bdee6b639c@github.com>
 <g82TmBi3DkRmU2UGOnXqtNsUSowqEHZOWGZv7171xOE=.695378bb-1a9e-4931-9db0-a7d43395e8cd@github.com>
Message-ID: <m-Qoz5S_VxMK8gRc8aqiyeEjFdwfABqK793vhq42BTU=.c1e136d4-1f27-488d-ab35-f0c65a31d81f@github.com>

On Thu, 15 Feb 2024 19:15:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/Start.java line 571:
>> 
>>> 569:         // of a doclet to be specified instead of the name of the
>>> 570:         // doclet class and optional doclet path.
>>> 571:         // See https://bugs.openjdk.org/browse/JDK-8263219
>> 
>> It's hard to understand this:
>> 
>>> to permit an instance of an appropriately configured instance of a doclet
>> 
>> Also: how is that piece of code used? When I commented it out, no test/langtools:langtools_javadoc tests failed.
>
> 1.  Since forever, and still true, the way to specify a doclet is by its name, and the tool will create the instance for you.  This goes back to the original old days before any API, when the only entry point was the command line.
> This implies that (a) the doclet has a no-args constructor and (b) that all doclet config is done through command line options.  A better solution would be to add new functionality to the various javadoc tool API (some or all of `Main`/`Start`/`DocumentationTool`) so that a client can initialize an instance of a doclet and pass that instance into the API.
> 
> 2. If I understand the question correctly, the code is invoked by using the command-line option `-XDaccessInternalAPI` which is a preexisting hidden feature already supported by `javac`.  It is used in `TestTransformer.java` on line 161.
> 
>         javadoc("-d", base.resolve("api").toString(),
>                 "-Xdoclint:none",
>                 "-XDaccessInternalAPI", // required to access JavacTrees
>                 "-doclet", "TestTransformer$MyDoclet",
>                 "-docletpath", System.getProperty("test.classes"),
>                 "-sourcepath", src.toString(),
>                 "p");

I confirm that `TestTransformer.java` fails as expected with an `IllegalAccessError` if the option is not used.

java.lang.IllegalAccessError: class TestTransformer$MyDoclet (in unnamed module @0x355de863) cannot access class com.sun.tools.javac.api.JavacTrees (in module jdk.compiler) because module jdk.compiler does not export com.sun.tools.javac.api to unnamed module @0x355de863
        at TestTransformer$MyDoclet.run(TestTransformer.java:139)
        at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:589)

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491538120

From prappo at openjdk.org  Thu Feb 15 19:46:06 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 15 Feb 2024 19:46:06 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
In-Reply-To: <2S7ZUtfa7Dnc0ttfGUEG4F0hZbj78o5U6h3Spi-qzR0=.53d767bc-faec-4bd8-a916-9364efcf5d28@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <5f-y-x2KRcAGr501XkShj08p51vAl8wxD8l8PYFcQmI=.08ee889e-8abb-47e2-b3ba-49bb09ae600d@github.com>
 <7hjkEusPyjQpzUGNArF4qKR_tSVyi3ekgkyX7gZ2LZw=.ad6b2cd6-f29b-4fca-b246-73572689180b@github.com>
 <2S7ZUtfa7Dnc0ttfGUEG4F0hZbj78o5U6h3Spi-qzR0=.53d767bc-faec-4bd8-a916-9364efcf5d28@github.com>
Message-ID: <72nE2l_N_wo2zHtS3wZSDyIYZJU2MqopYv422LDio74=.6c267f6f-0856-40b5-aff0-1288749ccd78@github.com>

On Thu, 15 Feb 2024 19:20:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1401:
>> 
>>> 1399:      */
>>> 1400:     enum LineKind {
>>> 1401:         BLANK(Pattern.compile("[ \t]*")),
>> 
>> `BLANK` is a pseudo kind, because it is set manually, but never returned from `peekLine()`. I wonder if we can change it somehow.
>
> Even if it is set manually, it is still appropriate to have it as a member in the `LineKind` enum class.

Not that it invalidates your reply; clarification: I meant `peekLineKind()`, not `peekLine()`.

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1433:
>> 
>>> 1431:          * @see <a href="https://spec.commonmark.org/0.30/#list-items">List items</a>
>>> 1432:          */
>>> 1433:         BULLETED_LIST_ITEM(Pattern.compile("[-+*] .*")),
>> 
>> This comment is about `BULLETED_LIST_ITEM` and `ORDERED_LIST_ITEM` constants. I know that we don't need to be very precise, but perhaps in this case we should. While the CommonMark spec is a vague on that, from my experiments with [dingus](https://spec.commonmark.org/dingus/), it appears that a list marker can be preceded and followed by some number of whitespace characters.
>
> whitespace is handled separately, on line 280 (`readIndent`) and285 (`: (indent <= 3) ? peekLineKind()`)

Correct, but I believe the ordered list marker should be like this:

    ORDERED_LIST_ITEM(Pattern.compile("[0-9]{1,9}[.)] .*"))
                                                     ^

Note extra whitespace character. I think we should really add this to our tests, since lists are foundational Markdown structures, probably right after italics and bold.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491550784
PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491545609

From jjg at openjdk.org  Thu Feb 15 19:46:07 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 19:46:07 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
In-Reply-To: <72nE2l_N_wo2zHtS3wZSDyIYZJU2MqopYv422LDio74=.6c267f6f-0856-40b5-aff0-1288749ccd78@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <5f-y-x2KRcAGr501XkShj08p51vAl8wxD8l8PYFcQmI=.08ee889e-8abb-47e2-b3ba-49bb09ae600d@github.com>
 <7hjkEusPyjQpzUGNArF4qKR_tSVyi3ekgkyX7gZ2LZw=.ad6b2cd6-f29b-4fca-b246-73572689180b@github.com>
 <2S7ZUtfa7Dnc0ttfGUEG4F0hZbj78o5U6h3Spi-qzR0=.53d767bc-faec-4bd8-a916-9364efcf5d28@github.com>
 <72nE2l_N_wo2zHtS3wZSDyIYZJU2MqopYv422LDio74=.6c267f6f-0856-40b5-aff0-1288749ccd78@github.com>
Message-ID: <uuj70xG0D9dO9cq_NI_mjEthLOwDvp2VuuiBm5dBNrc=.3064c029-c577-4aa3-ad05-bcdbd9c93f98@github.com>

On Thu, 15 Feb 2024 19:39:07 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> whitespace is handled separately, on line 280 (`readIndent`) and285 (`: (indent <= 3) ? peekLineKind()`)
>
> Correct, but I believe the ordered list marker should be like this:
> 
>     ORDERED_LIST_ITEM(Pattern.compile("[0-9]{1,9}[.)] .*"))
>                                                      ^
> 
> Note extra whitespace character. I think we should really add this to our tests, since lists are foundational Markdown structures, probably right after italics and bold.

My recollection is that the space is required.   I will double check.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491552312

From jjg at openjdk.org  Thu Feb 15 19:46:07 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 19:46:07 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v31]
In-Reply-To: <m-Qoz5S_VxMK8gRc8aqiyeEjFdwfABqK793vhq42BTU=.c1e136d4-1f27-488d-ab35-f0c65a31d81f@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <Imc_x0a26ALH3KO5jdgjvvwqZ8SL7eC-cotk7AphhRI=.8fcfe332-53cd-4aa9-8ff7-fc2082b23ece@github.com>
 <revTaYUgM40q0U5bHloqsO56zzKGpaMVRdj_LLyHQrs=.047fe7ff-2f0e-4fad-b4b8-10bdee6b639c@github.com>
 <g82TmBi3DkRmU2UGOnXqtNsUSowqEHZOWGZv7171xOE=.695378bb-1a9e-4931-9db0-a7d43395e8cd@github.com>
 <m-Qoz5S_VxMK8gRc8aqiyeEjFdwfABqK793vhq42BTU=.c1e136d4-1f27-488d-ab35-f0c65a31d81f@github.com>
Message-ID: <Zj9a1owB2ySz0xwJYGhBw1BMHww1lc7movAdCG2p360=.fbdd3315-063a-41a6-9369-28df1139eb13@github.com>

On Thu, 15 Feb 2024 19:36:36 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 1.  Since forever, and still true, the way to specify a doclet is by its name, and the tool will create the instance for you.  This goes back to the original old days before any API, when the only entry point was the command line.
>> This implies that (a) the doclet has a no-args constructor and (b) that all doclet config is done through command line options.  A better solution would be to add new functionality to the various javadoc tool API (some or all of `Main`/`Start`/`DocumentationTool`) so that a client can initialize an instance of a doclet and pass that instance into the API.
>> 
>> 2. If I understand the question correctly, the code is invoked by using the command-line option `-XDaccessInternalAPI` which is a preexisting hidden feature already supported by `javac`.  It is used in `TestTransformer.java` on line 161.
>> 
>>         javadoc("-d", base.resolve("api").toString(),
>>                 "-Xdoclint:none",
>>                 "-XDaccessInternalAPI", // required to access JavacTrees
>>                 "-doclet", "TestTransformer$MyDoclet",
>>                 "-docletpath", System.getProperty("test.classes"),
>>                 "-sourcepath", src.toString(),
>>                 "p");
>
> I confirm that `TestTransformer.java` fails as expected with an `IllegalAccessError` if the option is not used.
> 
> java.lang.IllegalAccessError: class TestTransformer$MyDoclet (in unnamed module @0x355de863) cannot access class com.sun.tools.javac.api.JavacTrees (in module jdk.compiler) because module jdk.compiler does not export com.sun.tools.javac.api to unnamed module @0x355de863
>         at TestTransformer$MyDoclet.run(TestTransformer.java:139)
>         at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:589)

Generally, the error occurs because the `MyDoclet` class is run in a different class loader than that used for the test.  The class loader for the test already has the necessary access permissions given, from the lines in `@modules` in the `jtreg` test description.  Ideally, we could call `new MyDoclet()` in the main test code, and pas the instance in to the `javadoc` call and from there to the javadoc `Start` method.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491547571

From prappo at openjdk.org  Thu Feb 15 19:55:06 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 15 Feb 2024 19:55:06 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v32]
In-Reply-To: <72nE2l_N_wo2zHtS3wZSDyIYZJU2MqopYv422LDio74=.6c267f6f-0856-40b5-aff0-1288749ccd78@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <5f-y-x2KRcAGr501XkShj08p51vAl8wxD8l8PYFcQmI=.08ee889e-8abb-47e2-b3ba-49bb09ae600d@github.com>
 <7hjkEusPyjQpzUGNArF4qKR_tSVyi3ekgkyX7gZ2LZw=.ad6b2cd6-f29b-4fca-b246-73572689180b@github.com>
 <2S7ZUtfa7Dnc0ttfGUEG4F0hZbj78o5U6h3Spi-qzR0=.53d767bc-faec-4bd8-a916-9364efcf5d28@github.com>
 <72nE2l_N_wo2zHtS3wZSDyIYZJU2MqopYv422LDio74=.6c267f6f-0856-40b5-aff0-1288749ccd78@github.com>
Message-ID: <Dg6jpPfJIfk5w2u2OvsE_HjJ5CQJO3helJS3g7svLuQ=.c3547e7d-34c7-4f92-ba86-ef1207364fc6@github.com>

On Thu, 15 Feb 2024 19:39:07 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> whitespace is handled separately, on line 280 (`readIndent`) and285 (`: (indent <= 3) ? peekLineKind()`)
>
> Correct, but I believe the ordered list marker should be like this:
> 
>     ORDERED_LIST_ITEM(Pattern.compile("[0-9]{1,9}[.)] .*"))
>                                                      ^
> 
> Note extra whitespace character. I think we should really add this to our tests, since lists are foundational Markdown structures, probably right after italics and bold.

Then we should add `[ \t]` to both constants, right:

    BULLETED_LIST_ITEM(Pattern.compile("[-+*][ \t].*"))
    ORDERED_LIST_ITEM(Pattern.compile("[0-9]{1,9}[.)][ \t].*"))

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1491564839

From jjg at openjdk.org  Thu Feb 15 21:10:55 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 21:10:55 GMT
Subject: RFR: JDK-8325687: SimpleJavaFileObject specification would benefit
 from implSpec
In-Reply-To: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
References: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
Message-ID: <Oiy-XIl0n7v6zyvqCE_3YhjkDkFC6UZshNghRMlI2Q4=.e4a9fa85-a4ef-4a90-afc9-c0d529b4831c@github.com>

On Wed, 14 Feb 2024 21:51:57 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> While reading the spec in the context of another potential change, noticed some cases where using implSpec would lead to a better structured specification.

src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java line 106:

> 104:      * {@inheritDoc FileObject}
> 105:      * @implSpec
> 106:      * This implementation wraps the result of {@linkplain #getCharContent} in a Reader.

suggest `{@code Reader}` or `{@link Reader}`

src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java line 139:

> 137:      * {@inheritDoc FileObject}
> 138:      * @implSpec
> 139:      * This implementation wraps the result of openOutputStream in a Writer.

Suggest using `{@code }` or `{@link }` for `openOutputStream` and `Writer`

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17854#discussion_r1491669533
PR Review Comment: https://git.openjdk.org/jdk/pull/17854#discussion_r1491670667

From jjg at openjdk.org  Thu Feb 15 21:20:21 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 15 Feb 2024 21:20:21 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v35]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <5a4XLWHSLG_xQeQDr0Ibz4Rl31m8phZCZl5UAdhukF8=.0a0d8cdd-2a13-4b27-8f4b-3cbcab241899@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with three additional commits since the last revision:

 - fix handling of `@' in a Markdown comment
 - improve comments for some LineKind members
 - update LineKind members and test

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/393d3a9c..da8752c8

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=34
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=33-34

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

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

From darcy at openjdk.org  Thu Feb 15 21:22:07 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Thu, 15 Feb 2024 21:22:07 GMT
Subject: RFR: JDK-8325687: SimpleJavaFileObject specification would benefit
 from implSpec [v2]
In-Reply-To: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
References: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
Message-ID: <NQsCPTYi5JEDv_m5WgMlSrN8kOOFjBEl5cjEMXE47CM=.8d92b17c-c3bf-434d-b871-f7f1d226a71c@github.com>

> While reading the spec in the context of another potential change, noticed some cases where using implSpec would lead to a better structured specification.

Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:

  Implement review feedback.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17854/files
  - new: https://git.openjdk.org/jdk/pull/17854/files/e035c02b..e5b57897

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17854&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17854&range=00-01

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

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

From jjg at openjdk.org  Fri Feb 16 00:46:34 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 16 Feb 2024 00:46:34 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v36]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <u2J4zt4oo-GbgV2u6DYkdV3IlyeO-NxpbIzy6bGcX14=.c0bd758d-66f7-40cd-b046-4ef496cc9118@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:

 - Support for Table Of Contents in Markdown headings
 - fix typo

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/da8752c8..53afd804

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=35
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=34-35

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

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

From hannesw at openjdk.org  Fri Feb 16 07:45:06 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Fri, 16 Feb 2024 07:45:06 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v36]
In-Reply-To: <u2J4zt4oo-GbgV2u6DYkdV3IlyeO-NxpbIzy6bGcX14=.c0bd758d-66f7-40cd-b046-4ef496cc9118@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <u2J4zt4oo-GbgV2u6DYkdV3IlyeO-NxpbIzy6bGcX14=.c0bd758d-66f7-40cd-b046-4ef496cc9118@github.com>
Message-ID: <1hRkg0waT73IaCbhd7h-0bEgG5JirfxttEMjcY9EYM0=.827a07c5-d256-4b8e-9a3a-266506725f26@github.com>

On Fri, 16 Feb 2024 00:46:34 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Support for Table Of Contents in Markdown headings
>  - fix typo

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 286:

> 284:                         lineKind = (ch == '\n' || ch == '\r') ? LineKind.BLANK
> 285:                                 : (indent <= 3) ? peekLineKind()
> 286:                                 : lineKind != LineKind.OTHER ? LineKind.INDENTED_CODE_BLOCK

Doesn't this cause false positives for indented code blocks? In my understanding, indented lines in a list context and directly following a blockquote are not interpreted as code blocks, but as part of the list or blockquote. So my guess would be that `not OTHER` should be something like `BLANK or INDENTED_CODE_BLOCK or HEADER`, and that still leaves the problem of a [blank line in a list context](https://spec.commonmark.org/0.30/#example-108).

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1492065799

From prappo at openjdk.org  Fri Feb 16 13:09:09 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Fri, 16 Feb 2024 13:09:09 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v36]
In-Reply-To: <1hRkg0waT73IaCbhd7h-0bEgG5JirfxttEMjcY9EYM0=.827a07c5-d256-4b8e-9a3a-266506725f26@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <u2J4zt4oo-GbgV2u6DYkdV3IlyeO-NxpbIzy6bGcX14=.c0bd758d-66f7-40cd-b046-4ef496cc9118@github.com>
 <1hRkg0waT73IaCbhd7h-0bEgG5JirfxttEMjcY9EYM0=.827a07c5-d256-4b8e-9a3a-266506725f26@github.com>
Message-ID: <WaymeBVWCFIWWt3eIKBTitH7EPgWTEvBuwhqRdJId-w=.aad1b61a-2828-4585-b227-ed967dee377e@github.com>

On Fri, 16 Feb 2024 07:42:47 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Support for Table Of Contents in Markdown headings
>>  - fix typo
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 286:
> 
>> 284:                         lineKind = (ch == '\n' || ch == '\r') ? LineKind.BLANK
>> 285:                                 : (indent <= 3) ? peekLineKind()
>> 286:                                 : lineKind != LineKind.OTHER ? LineKind.INDENTED_CODE_BLOCK
> 
> Doesn't this cause false positives for indented code blocks? In my understanding, indented lines [in a list context](https://spec.commonmark.org/0.30/#example-258) and [directly following a blockquote](https://spec.commonmark.org/dingus/?text=%3E%20%20%20%20foo%0A%20%20%20%20%20bar%0A) are not interpreted as code blocks, but as part of the list or blockquote. So my guess would be that `not OTHER` should be something like `BLANK or INDENTED_CODE_BLOCK or HEADER`, and that still leaves the problem of a [blank line in a list context](https://spec.commonmark.org/0.30/#example-108).

Sigh. I remember when we all hoped that we wouldn't need to go in the weeds of Markdown parsing, but here we are. Hannes is right. Here are a coupe of problematic examples:

 -     /// List
       ///
       ///   - item
       ///
       ///     @param

 -     /// > Quote
       /// >
       /// >     {@link java.lang.Object}

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1492430822

From duke at openjdk.org  Fri Feb 16 15:35:54 2024
From: duke at openjdk.org (ExE Boss)
Date: Fri, 16 Feb 2024 15:35:54 GMT
Subject: RFR: JDK-8325687: SimpleJavaFileObject specification would benefit
 from implSpec [v2]
In-Reply-To: <NQsCPTYi5JEDv_m5WgMlSrN8kOOFjBEl5cjEMXE47CM=.8d92b17c-c3bf-434d-b871-f7f1d226a71c@github.com>
References: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
 <NQsCPTYi5JEDv_m5WgMlSrN8kOOFjBEl5cjEMXE47CM=.8d92b17c-c3bf-434d-b871-f7f1d226a71c@github.com>
Message-ID: <fkC4wcWgvcrH53D67Wf3zbM3Dj3F2jv0fo6VWUcXqXg=.8441b030-7707-414d-8e4e-78527096ce08@github.com>

On Thu, 15 Feb 2024 21:22:07 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> While reading the spec in the context of another potential change, noticed some cases where using implSpec would lead to a better structured specification.
>
> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Implement review feedback.

src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java line 107:

> 105:      * @implSpec
> 106:      * This implementation wraps the result of {@linkplain
> 107:      * #getCharContent} in a {@link Reader}.

Suggestion:

     * This implementation wraps the result of {@linkplain #getCharContent}
     * in a {@link Reader}.

src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java line 141:

> 139:      * @implSpec
> 140:      * This implementation wraps the result of {@link
> 141:      * openOutputStream} in a {@link Writer}.

Suggestion:

     * This implementation wraps the result of {@linkplain #openOutputStream}
     * in a {@link Writer}.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17854#discussion_r1492643539
PR Review Comment: https://git.openjdk.org/jdk/pull/17854#discussion_r1492644828

From jlahoda at openjdk.org  Fri Feb 16 15:55:54 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Fri, 16 Feb 2024 15:55:54 GMT
Subject: RFR: JDK-8325687: SimpleJavaFileObject specification would benefit
 from implSpec [v2]
In-Reply-To: <NQsCPTYi5JEDv_m5WgMlSrN8kOOFjBEl5cjEMXE47CM=.8d92b17c-c3bf-434d-b871-f7f1d226a71c@github.com>
References: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
 <NQsCPTYi5JEDv_m5WgMlSrN8kOOFjBEl5cjEMXE47CM=.8d92b17c-c3bf-434d-b871-f7f1d226a71c@github.com>
Message-ID: <8Yo9Vk5u6B6qZ3gdu_hhj01PjhRkhsamnCINca0dqUo=.e0eaf4f5-33eb-4c2a-84b4-240f66aa9b50@github.com>

On Thu, 15 Feb 2024 21:22:07 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> While reading the spec in the context of another potential change, noticed some cases where using implSpec would lead to a better structured specification.
>
> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Implement review feedback.

Makes sense to me, thanks!

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

Marked as reviewed by jlahoda (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17854#pullrequestreview-1885469843

From jjg at openjdk.org  Fri Feb 16 17:03:25 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 16 Feb 2024 17:03:25 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v37]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <28i4g6IynoB72EH0TiCPLtRASiHamLlXOzyKlpHzrI4=.c01d8c67-86ca-4282-8382-099bc98f6061@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  remove obsolete comment

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/53afd804..25921fd0

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=36
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=35-36

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

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

From acobbs at openjdk.org  Fri Feb 16 17:14:09 2024
From: acobbs at openjdk.org (Archie Cobbs)
Date: Fri, 16 Feb 2024 17:14:09 GMT
Subject: RFR: 8317376: Minor improvements to the 'this' escape analyzer
 [v3]
In-Reply-To: <BBO-U3RwIUINQuQ3OGLpoHlwiQ2OutqJV-d0Y6AsUlc=.2fba21cd-5967-4469-9f9e-070aa2ed990e@github.com>
References: <BBO-U3RwIUINQuQ3OGLpoHlwiQ2OutqJV-d0Y6AsUlc=.2fba21cd-5967-4469-9f9e-070aa2ed990e@github.com>
Message-ID: <QvX6vQp-aXt2jCvUMCVhwrna3Gr8m8NVesUmexUdMcI=.4f5e5118-97b6-4484-a838-808800bfbec8@github.com>

> Please review several fixes and improvements to the `this-escape` lint warning analyzer.
> 
> The goal here is to apply some relatively simple logical fixes that improve the precision and accuracy of the analyzer, and capture the remaining low-hanging fruit so we can consider the analyzer relatively complete with respect to what's feasible with its current design.
> 
> Although the changes are small from a logical point of view, they generate a fairly large patch due to impact of refactoring (sorry!). Most of the patch derives from the first two changes listed below.
> 
> The changes are summarized here:
> 
> #### 1. Generalize how we categorize references
> 
> The `Ref` class hierarchy models the various ways in which, at any point during the execution of a constructor or some other method/constructor that it invokes, there can be live references to the original object under construction lying around. We then look for places where one of these `Ref`'s might be passed to a subclass method. In other words, the analyzer keeps track of these references and watches what happens to them as the code executes so it can catch them trying to "escape".
> 
> Previously the `Ref` categories were:
> * `ThisRef` - The current instance of the (non-static) method or constructor being analyzed
> * `OuterRef` - The current outer instance of the (non-static) method or constructor being analyzed
> * `VarRef` - A local variable or method parameter currently in scope
> * `ExprRef` - An object reference sitting on top of the Java execution stack
> * `YieldRef` - The current switch expression's yield value(s)
> * `ReturnRef` - The current method's return value(s)
> 
> For each of those types, we further classified the "indirection" of the reference, i.e., whether the reference was direct (from the thing itself) or indirect (from something the thing referenced).
> 
> The problem with that hierarchy is that we could only track outer instance references that happened to be associated with the current instance. So we might know that `this` had an outer instance reference, but if we said `var x = this` we wouldn't know that `x` had an outer instance reference.
> 
> In other words, we should be treating "via an outer instance" as just another flavor of indirection along with "direct" and "indirect".
> 
> As a result, with this patch the `OuterRef` class goes away and a new `Indirection` enum has been created, with values `DIRECT`, `INDIRECT`, and `OUTER`.
> 
> #### 2. Track the types of all references
> 
> By keeping track of the actual type of...

Archie Cobbs has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains seven commits:

 - Merge branch 'master' into JDK-8317376
 - Merge branch 'master' into JDK-8317376
 - Merge branch 'master' into JDK-8317376
 - Merge branch 'master' into JDK-8317376
 - Javadoc++
 - Merge branch 'master' into JDK-8317376
 - Several improvements to the 'this' escape analyzer.
   
   - Track direct, indirect, and outer references for all Ref types.
   - Keep type information about all references to improve tracking precision.
   - Track enhanced for() invocations of iterator(), hasNext(), and next().
   - Don't report an escape of a non-public outer instances as a leak.
   - Fix omitted tracking of references from newly instantiated instances.
   - Fix omitted tracking of leaks via lambda return values.
   - Remove unneccesary suppressions of this-escape lint warning.

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

Changes: https://git.openjdk.org/jdk/pull/16208/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16208&range=02
  Stats: 869 lines in 19 files changed: 513 ins; 146 del; 210 mod
  Patch: https://git.openjdk.org/jdk/pull/16208.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16208/head:pull/16208

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

From darcy at openjdk.org  Fri Feb 16 17:50:10 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Fri, 16 Feb 2024 17:50:10 GMT
Subject: RFR: JDK-8325687: SimpleJavaFileObject specification would benefit
 from implSpec [v3]
In-Reply-To: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
References: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
Message-ID: <g-cZ0BUEYZ8awoR9APRkmwIeOVVisy63hTKDXDy905k=.26b7bb1c-0e0c-4e67-806c-6a740b94d29f@github.com>

> While reading the spec in the context of another potential change, noticed some cases where using implSpec would lead to a better structured specification.

Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:

  Change type of link tag.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17854/files
  - new: https://git.openjdk.org/jdk/pull/17854/files/e5b57897..fe974f62

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17854&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17854&range=01-02

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

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

From iris at openjdk.org  Fri Feb 16 20:08:56 2024
From: iris at openjdk.org (Iris Clark)
Date: Fri, 16 Feb 2024 20:08:56 GMT
Subject: RFR: JDK-8325687: SimpleJavaFileObject specification would benefit
 from implSpec [v3]
In-Reply-To: <g-cZ0BUEYZ8awoR9APRkmwIeOVVisy63hTKDXDy905k=.26b7bb1c-0e0c-4e67-806c-6a740b94d29f@github.com>
References: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
 <g-cZ0BUEYZ8awoR9APRkmwIeOVVisy63hTKDXDy905k=.26b7bb1c-0e0c-4e67-806c-6a740b94d29f@github.com>
Message-ID: <OTj-NL1qQpz3dC3NCWlnTTWgp7sh55hfLSceMFWpr0s=.1556237d-8c5c-4967-9dc0-3d48618e2870@github.com>

On Fri, 16 Feb 2024 17:50:10 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> While reading the spec in the context of another potential change, noticed some cases where using implSpec would lead to a better structured specification.
>
> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Change type of link tag.

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/17854#pullrequestreview-1885923522

From duke at openjdk.org  Fri Feb 16 22:05:53 2024
From: duke at openjdk.org (ExE Boss)
Date: Fri, 16 Feb 2024 22:05:53 GMT
Subject: RFR: JDK-8325687: SimpleJavaFileObject specification would benefit
 from implSpec [v2]
In-Reply-To: <fkC4wcWgvcrH53D67Wf3zbM3Dj3F2jv0fo6VWUcXqXg=.8441b030-7707-414d-8e4e-78527096ce08@github.com>
References: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
 <NQsCPTYi5JEDv_m5WgMlSrN8kOOFjBEl5cjEMXE47CM=.8d92b17c-c3bf-434d-b871-f7f1d226a71c@github.com>
 <fkC4wcWgvcrH53D67Wf3zbM3Dj3F2jv0fo6VWUcXqXg=.8441b030-7707-414d-8e4e-78527096ce08@github.com>
Message-ID: <UDdE8OmTzNkWOCpAcL969CW2jsXGUuHNxa0KzYx3gjk=.8880d873-4734-4bd8-baf8-325dcf588e61@github.com>

On Fri, 16 Feb 2024 15:32:30 GMT, ExE Boss <duke at openjdk.org> wrote:

>> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Implement review feedback.
>
> src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java line 141:
> 
>> 139:      * @implSpec
>> 140:      * This implementation wraps the result of {@link
>> 141:      * openOutputStream} in a {@link Writer}.
> 
> Suggestion:
> 
>      * This implementation wraps the result of {@linkplain #openOutputStream}
>      * in a {@link Writer}.

Still?missing the?`#` to?make a?valid?link:
Suggestion:

     * This implementation wraps the result of {@link #openOutputStream}
     * in a {@link Writer}.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17854#discussion_r1493023829

From darcy at openjdk.org  Fri Feb 16 22:55:04 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Fri, 16 Feb 2024 22:55:04 GMT
Subject: RFR: JDK-8325687: SimpleJavaFileObject specification would benefit
 from implSpec [v4]
In-Reply-To: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
References: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
Message-ID: <NJE9il-NOGao5MixkB6BgMjey0Hg61tePt3-WbamHbM=.49bfb0c0-0984-49ec-9900-80c2a9b53436@github.com>

> While reading the spec in the context of another potential change, noticed some cases where using implSpec would lead to a better structured specification.

Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:

  Add octothrope to link.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17854/files
  - new: https://git.openjdk.org/jdk/pull/17854/files/fe974f62..ea8ce026

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17854&range=03
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17854&range=02-03

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

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

From darcy at openjdk.org  Fri Feb 16 22:55:04 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Fri, 16 Feb 2024 22:55:04 GMT
Subject: RFR: JDK-8325687: SimpleJavaFileObject specification would benefit
 from implSpec [v2]
In-Reply-To: <UDdE8OmTzNkWOCpAcL969CW2jsXGUuHNxa0KzYx3gjk=.8880d873-4734-4bd8-baf8-325dcf588e61@github.com>
References: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
 <NQsCPTYi5JEDv_m5WgMlSrN8kOOFjBEl5cjEMXE47CM=.8d92b17c-c3bf-434d-b871-f7f1d226a71c@github.com>
 <fkC4wcWgvcrH53D67Wf3zbM3Dj3F2jv0fo6VWUcXqXg=.8441b030-7707-414d-8e4e-78527096ce08@github.com>
 <UDdE8OmTzNkWOCpAcL969CW2jsXGUuHNxa0KzYx3gjk=.8880d873-4734-4bd8-baf8-325dcf588e61@github.com>
Message-ID: <ILRkGiHDPCcNAqyn1X_yeCxOrW7XX4_D_h2wVX-n_o8=.11d084b6-2f96-468b-908b-e23ba496c375@github.com>

On Fri, 16 Feb 2024 22:02:55 GMT, ExE Boss <duke at openjdk.org> wrote:

>> src/java.compiler/share/classes/javax/tools/SimpleJavaFileObject.java line 141:
>> 
>>> 139:      * @implSpec
>>> 140:      * This implementation wraps the result of {@link
>>> 141:      * openOutputStream} in a {@link Writer}.
>> 
>> Suggestion:
>> 
>>      * This implementation wraps the result of {@linkplain #openOutputStream}
>>      * in a {@link Writer}.
>
> Still?missing the?`#` to?make a?valid?link:
> Suggestion:
> 
>      * This implementation wraps the result of {@link #openOutputStream}
>      * in a {@link Writer}.

Hmm. Well, the build and docs build succeed with the `#` and produce a link in the generated HTML, but I'll add it before pushing. Thanks,

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17854#discussion_r1493052787

From darcy at openjdk.org  Fri Feb 16 22:58:57 2024
From: darcy at openjdk.org (Joe Darcy)
Date: Fri, 16 Feb 2024 22:58:57 GMT
Subject: Integrated: JDK-8325687: SimpleJavaFileObject specification would
 benefit from implSpec
In-Reply-To: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
References: <0bhbMnRPjF6fSIA5BlSup3UDV9wIhcRILKwN2TElles=.eda807b5-83f7-4159-ad9a-9827fb0319b2@github.com>
Message-ID: <C4mLxyRBI8JJnMceQnrRxaVHQanxIdhBeWVvyXmv8bA=.7d7413d4-fe3c-4951-b671-fd13cdc40e19@github.com>

On Wed, 14 Feb 2024 21:51:57 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> While reading the spec in the context of another potential change, noticed some cases where using implSpec would lead to a better structured specification.

This pull request has now been integrated.

Changeset: 3b763722
Author:    Joe Darcy <darcy at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/3b76372254aa638f5dcae1d54b963cd43bca7102
Stats:     43 lines in 2 files changed: 10 ins; 9 del; 24 mod

8325687: SimpleJavaFileObject specification would benefit from implSpec

Reviewed-by: jlahoda, iris

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

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

From liach at openjdk.org  Sun Feb 18 15:29:06 2024
From: liach at openjdk.org (Chen Liang)
Date: Sun, 18 Feb 2024 15:29:06 GMT
Subject: RFR: 8323707: Adjust Classfile API's type arg model to better
 represent the embodied type [v2]
In-Reply-To: <MHOvwnWcnocbfiiIdkzyqB6qdt-f2HwiaTurds0p3Pg=.cda1d910-6ef4-4577-a539-10a959adcd1f@github.com>
References: <MHOvwnWcnocbfiiIdkzyqB6qdt-f2HwiaTurds0p3Pg=.cda1d910-6ef4-4577-a539-10a959adcd1f@github.com>
Message-ID: <2QT0Vlh_6-kZ2cUtpf2Ezd2AtVn53SVKoKq1THO72-Y=.736a9f4f-a997-430a-a63c-0851f8d37a84@github.com>

> API changes as discussed on the mailing list: https://mail.openjdk.org/pipermail/classfile-api-dev/2023-November/000419.html
> 
> Additional questions:
> 1. Whether to rename `WildcardIndicator.DEFAULT` to `NONE`

Chen Liang has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains ten commits:

 - Merge branch 'master' into fix/typearg-model
 - redundant line
 - Fix a test in langtools, copyright year
 - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
 - Implementation cleanup, test update
 - Merge branch 'master' into fix/typearg-model
 - Formatting
 - Nuke signatureString and fix test fialure from bad cast
 - Adjust the type arg model to better represent the embodied type

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

Changes: https://git.openjdk.org/jdk/pull/16517/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16517&range=01
  Stats: 129 lines in 6 files changed: 46 ins; 32 del; 51 mod
  Patch: https://git.openjdk.org/jdk/pull/16517.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16517/head:pull/16517

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

From jlahoda at openjdk.org  Mon Feb 19 12:27:04 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Mon, 19 Feb 2024 12:27:04 GMT
Subject: [jdk22] Withdrawn: 8322159: ThisEscapeAnalyzer crashes for erroneous
 code
In-Reply-To: <W0kG7mO0T3nzSuq051cg0Ljx2uo2BMArDgVXgDje1kU=.8888df7d-9ae9-44ce-8121-434e9a758e5d@github.com>
References: <W0kG7mO0T3nzSuq051cg0Ljx2uo2BMArDgVXgDje1kU=.8888df7d-9ae9-44ce-8121-434e9a758e5d@github.com>
Message-ID: <ABSluKjk7BXADckfcgDc8YU4NriHGTYePFpxbKI0ZCY=.b885ac3c-2de1-47e3-a6ee-ddc2aed2c7eb@github.com>

On Tue, 2 Jan 2024 12:32:04 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Hi all,
> 
> This pull request contains a backport of commit [7455b1b5](https://github.com/openjdk/jdk/commit/7455b1b527568aff5b1c16a29fd80b05260c0fad) from the [openjdk/jdk](https://git.openjdk.org/jdk) repository.
> 
> The commit being backported was authored by Jan Lahoda on 2 Jan 2024 and was reviewed by Vicente Romero.
> 
> Thanks!

This pull request has been closed without being integrated.

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

PR: https://git.openjdk.org/jdk22/pull/26

From duke at openjdk.org  Mon Feb 19 15:31:00 2024
From: duke at openjdk.org (David M. Lloyd)
Date: Mon, 19 Feb 2024 15:31:00 GMT
Subject: RFR: 8323707: Adjust Classfile API's type arg model to better
 represent the embodied type [v2]
In-Reply-To: <ucgottWGuHTVA_NdHh2ihwUieoQBMknwHLfQetEqyB8=.1bfca408-a3ee-47ad-90eb-ac2d14b128ad@github.com>
References: <MHOvwnWcnocbfiiIdkzyqB6qdt-f2HwiaTurds0p3Pg=.cda1d910-6ef4-4577-a539-10a959adcd1f@github.com>
 <ucgottWGuHTVA_NdHh2ihwUieoQBMknwHLfQetEqyB8=.1bfca408-a3ee-47ad-90eb-ac2d14b128ad@github.com>
Message-ID: <i_8OaRahDXxOaQTsxOg2U357qSaWnVTKuPBzxBevigI=.6ededec2-4435-43b2-a27e-55ef80986801@github.com>

On Mon, 15 Jan 2024 02:30:39 GMT, ExE Boss <duke at openjdk.org> wrote:

>> Chen Liang has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains ten commits:
>> 
>>  - Merge branch 'master' into fix/typearg-model
>>  - redundant line
>>  - Fix a test in langtools, copyright year
>>  - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
>>  - Implementation cleanup, test update
>>  - Merge branch 'master' into fix/typearg-model
>>  - Formatting
>>  - Nuke signatureString and fix test fialure from bad cast
>>  - Adjust the type arg model to better represent the embodied type
>
> src/java.base/share/classes/java/lang/classfile/Signature.java line 219:
> 
>> 217:                  * no wildcard (empty), an exact type
>> 218:                  */
>> 219:                 DEFAULT,
> 
> I?m?personally in?favour of?naming this?`NONE`.

A belated +1 to this, at least not calling it `DEFAULT` because that has at best no meaning, and at worst it's outright confusing. If not `NONE`, then what about `EXACT`?

In my own old parsing code I have an enum called `Variance` with values `INVARIANT`, `COVARIANT`, and `CONTRAVARIANT`, but that might be a bit confusing considering that `EXTENDS` and `SUPER` match the Java language keywords directly.

As an aside, the javadoc here could be a little better IMO.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16517#discussion_r1494726792

From jjg at openjdk.org  Mon Feb 19 18:23:05 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 19 Feb 2024 18:23:05 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v36]
In-Reply-To: <1hRkg0waT73IaCbhd7h-0bEgG5JirfxttEMjcY9EYM0=.827a07c5-d256-4b8e-9a3a-266506725f26@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <u2J4zt4oo-GbgV2u6DYkdV3IlyeO-NxpbIzy6bGcX14=.c0bd758d-66f7-40cd-b046-4ef496cc9118@github.com>
 <1hRkg0waT73IaCbhd7h-0bEgG5JirfxttEMjcY9EYM0=.827a07c5-d256-4b8e-9a3a-266506725f26@github.com>
Message-ID: <dpksm8jrXyvld3ATgbHzPVJGqClj1iMjwADcZdP3Pg0=.f69e1822-1294-43f4-9119-4344cf4154d6@github.com>

On Fri, 16 Feb 2024 07:42:47 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Support for Table Of Contents in Markdown headings
>>  - fix typo
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 286:
> 
>> 284:                         lineKind = (ch == '\n' || ch == '\r') ? LineKind.BLANK
>> 285:                                 : (indent <= 3) ? peekLineKind()
>> 286:                                 : lineKind != LineKind.OTHER ? LineKind.INDENTED_CODE_BLOCK
> 
> Doesn't this cause false positives for indented code blocks? In my understanding, indented lines [in a list context](https://spec.commonmark.org/0.30/#example-258) and [directly following a blockquote](https://spec.commonmark.org/dingus/?text=%3E%20%20%20%20foo%0A%20%20%20%20%20bar%0A) are not interpreted as code blocks (always in the case of blockquote, and depending on the offset of text after the list marker in list items). 
> 
> Note: edited because my initial suggestion was incorrect.

@hns @pavelrappo noted; working on it ...

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1494909524

From jjg at openjdk.org  Tue Feb 20 19:07:55 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 20 Feb 2024 19:07:55 GMT
Subject: RFR: JDK-8164094: javadoc allows to create a @link to a
 non-existent method [v2]
In-Reply-To: <boJdnkhR2GiQNMwOcJX2MLv32Nk20TeKrnivxrgXwvM=.10646638-d84f-4c87-89de-2489bef3a26c@github.com>
References: <-xM8YSleEZ-CQY1FwsTvPsgYW3s8GmkOkGi-9r8icuI=.da06c781-54fe-463a-abd7-c714e4d3982f@github.com>
 <boJdnkhR2GiQNMwOcJX2MLv32Nk20TeKrnivxrgXwvM=.10646638-d84f-4c87-89de-2489bef3a26c@github.com>
Message-ID: <B7QJYcpd5rL4bSIhSybF92N2Q5p7Q0NNi1CUTXyjaYY=.1b391332-b776-491d-8f04-f27554cb027e@github.com>

On Tue, 12 Dec 2023 12:42:41 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Please review a simple fix in `JavacTrees` to only look up member references in the enclosing type if the reference does not contain an explicit type name. For example, `@see #method()` in a a doc comment of class `Outer.Inner` should find method `Outer.method()`, but `@see Inner#method()` should not (regardless of comment location).
>
> Hannes Walln?fer 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 three additional commits since the last revision:
> 
>  - Merge branch 'master' into JDK-8164094
>  - Additional test
>  - JDK-8164094: javadoc allows to create a @link to a non-existent method

Marked as reviewed by jjg (Reviewer).

test/langtools/tools/javac/doctree/ReferenceTest.java line 2:

> 1: /*
> 2:  * Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.

2024?

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

PR Review: https://git.openjdk.org/jdk/pull/17069#pullrequestreview-1891310639
PR Review Comment: https://git.openjdk.org/jdk/pull/17069#discussion_r1496352451

From hannesw at openjdk.org  Tue Feb 20 19:59:11 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 20 Feb 2024 19:59:11 GMT
Subject: RFR: JDK-8164094: javadoc allows to create a @link to a
 non-existent method [v3]
In-Reply-To: <-xM8YSleEZ-CQY1FwsTvPsgYW3s8GmkOkGi-9r8icuI=.da06c781-54fe-463a-abd7-c714e4d3982f@github.com>
References: <-xM8YSleEZ-CQY1FwsTvPsgYW3s8GmkOkGi-9r8icuI=.da06c781-54fe-463a-abd7-c714e4d3982f@github.com>
Message-ID: <JUxb0TJrsx6HWwcweGuMkN1z9LhtMqTs_r05eYO1Dqk=.5d28119f-c9b3-424e-a931-45cd67e42c5b@github.com>

> Please review a simple fix in `JavacTrees` to only look up member references in the enclosing type if the reference does not contain an explicit type name. For example, `@see #method()` in a a doc comment of class `Outer.Inner` should find method `Outer.method()`, but `@see Inner#method()` should not (regardless of comment location).

Hannes Walln?fer has updated the pull request incrementally with one additional commit since the last revision:

  Update copyright date

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17069/files
  - new: https://git.openjdk.org/jdk/pull/17069/files/4f08440e..9575bf1c

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17069&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17069&range=01-02

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

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

From hannesw at openjdk.org  Tue Feb 20 19:59:12 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 20 Feb 2024 19:59:12 GMT
Subject: RFR: JDK-8164094: javadoc allows to create a @link to a
 non-existent method [v2]
In-Reply-To: <B7QJYcpd5rL4bSIhSybF92N2Q5p7Q0NNi1CUTXyjaYY=.1b391332-b776-491d-8f04-f27554cb027e@github.com>
References: <-xM8YSleEZ-CQY1FwsTvPsgYW3s8GmkOkGi-9r8icuI=.da06c781-54fe-463a-abd7-c714e4d3982f@github.com>
 <boJdnkhR2GiQNMwOcJX2MLv32Nk20TeKrnivxrgXwvM=.10646638-d84f-4c87-89de-2489bef3a26c@github.com>
 <B7QJYcpd5rL4bSIhSybF92N2Q5p7Q0NNi1CUTXyjaYY=.1b391332-b776-491d-8f04-f27554cb027e@github.com>
Message-ID: <pjJwV0EuAf70izp8gLzgsLm6jktq7dLlCvmqTnxaz7Q=.3361a8b9-3adc-4215-bd33-4b7fab7aa7f7@github.com>

On Tue, 20 Feb 2024 19:04:23 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Hannes Walln?fer 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 three additional commits since the last revision:
>> 
>>  - Merge branch 'master' into JDK-8164094
>>  - Additional test
>>  - JDK-8164094: javadoc allows to create a @link to a non-existent method
>
> test/langtools/tools/javac/doctree/ReferenceTest.java line 2:
> 
>> 1: /*
>> 2:  * Copyright (c) 2012, 2023, Oracle and/or its affiliates. All rights reserved.
> 
> 2024?

Updated

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17069#discussion_r1496406566

From hannesw at openjdk.org  Tue Feb 20 19:59:13 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Tue, 20 Feb 2024 19:59:13 GMT
Subject: Integrated: JDK-8164094: javadoc allows to create a @link to a
 non-existent method
In-Reply-To: <-xM8YSleEZ-CQY1FwsTvPsgYW3s8GmkOkGi-9r8icuI=.da06c781-54fe-463a-abd7-c714e4d3982f@github.com>
References: <-xM8YSleEZ-CQY1FwsTvPsgYW3s8GmkOkGi-9r8icuI=.da06c781-54fe-463a-abd7-c714e4d3982f@github.com>
Message-ID: <Bbzm-iJC6REuqIOpvNNOoMqKZuQPdWQIz0W_Tkwn7IU=.3593e7e3-a270-4a09-b040-353e3fbf1065@github.com>

On Mon, 11 Dec 2023 21:18:57 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

> Please review a simple fix in `JavacTrees` to only look up member references in the enclosing type if the reference does not contain an explicit type name. For example, `@see #method()` in a a doc comment of class `Outer.Inner` should find method `Outer.method()`, but `@see Inner#method()` should not (regardless of comment location).

This pull request has now been integrated.

Changeset: aa792eab
Author:    Hannes Walln?fer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/aa792eababda966c1195dc5701906c66f1628f49
Stats:     56 lines in 2 files changed: 29 ins; 1 del; 26 mod

8164094: javadoc allows to create a @link to a non-existent method

Reviewed-by: prappo, jjg

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

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

From jlahoda at openjdk.org  Wed Feb 21 14:53:14 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Wed, 21 Feb 2024 14:53:14 GMT
Subject: RFR: 8325215: Incorrect not exhaustive switch error
Message-ID: <mrhqhI191FNOiIHnUU7b2ggs77ZzZIGkeUK0OtZXVCc=.a7ccefbc-51a2-4a20-af8f-2531a90b0e1a@github.com>

Consider code like:

public class Test {

    sealed interface A permits T, U {}
    sealed interface B permits V, W {}
    static final class T implements A {}
    static final class U implements A {}
    static final class V implements B {}
    static final class W implements B {}
    final static record R(A a, B b) {}

    static int r(R r) {
        return switch (r) {
            case R(A a, V b) -> 1;
            case R(T a, W b) -> 2;
            case R(U a, W b) -> 3;
        };
    }
}


javac will correctly consider this to be exhaustive, as `R(T a, W b)` and `R(U a, W b)` can be merged into `R(A a, W b)`, and then `R(A a, V b)` and `R(A a, W b)` are merge into `R(A a, B b)` and then into `R`.

But, if we replace `R(T a, W b)` with a more general `R(T a, B b)`, which matches everything that `R(T a, W b)` does:

public class Test {

    sealed interface A permits T, U {}
    sealed interface B permits V, W {}
    static final class T implements A {}
    static final class U implements A {}
    static final class V implements B {}
    static final class W implements B {}
    final static record R(A a, B b) {}

    static int r(R r) {
        return switch (r) {
            case R(A a, V b) -> 1;
            case R(T a, B b) -> 2;
            case R(U a, W b) -> 3;
        };
    }
}


Leads to:

$ javac /tmp/Test.java
/tmp/Test.java:12: error: the switch expression does not cover all possible input values
        return switch (r) {
               ^
1 error


The issue is that the exhaustivity algorithm is no longer able to merge `R(T a, B b)` and `R(U a, W b)` into `R(A a, W b)`, as the second nested pattern is not the same.

The rules permit replacing patterns with more strict patterns, i.e. it is permitted to replace `R(T a, B b)` with `R(T a, W b)`, and hence proceed with the merging as in the original case. The trouble is that doing such conversions may lead to high computational complexity.

The proposal in this patch is to replace all binding patterns in all patterns with their transitive permitted subtypes, but only once, and only if the algorithm fails to determine the exhaustiveness using the standing approach. This may lead to a potentially significant performance penalty, but only in case where the algorithm would mark the switch exhaustive.

The main alternative to this proposal would be to allow the algorithm to see `B` and `W` as equivalent when attempting to merge  `R(T a, B b)` and `R(U a, W b)`. But, currently, this equivalence check is based on hash codes, which prevents doing the check using subtyping checks, and this hashing improved performance in "common" cases tremendously. So, I would like to attempt to keep that. But it is possible we might need to fall back on the subtyping check for equivalence instead of hashing if other solutions will prove to be unusable.

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

Commit messages:
 - Enhancing test.
 - 8325215: Incorrect not exhaustive switch error

Changes: https://git.openjdk.org/jdk/pull/17949/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17949&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8325215
  Stats: 130 lines in 2 files changed: 128 ins; 1 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/17949.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17949/head:pull/17949

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

From jlahoda at openjdk.org  Wed Feb 21 15:11:02 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Wed, 21 Feb 2024 15:11:02 GMT
Subject: RFR: 8326129: Java Record Pattern Match leads to infinite loop
Message-ID: <QKK2RvbTvU7fd2q2Dy-LxQ18c7lKJGbWD6Ar1FhLbww=.e9b52617-74e0-4c53-b883-d1438fcd3ffe@github.com>

Consider code like:

private int test(Box b) {
    return switch (b) {
        case Box(Integer i) -> 0;
        case Box(Object o) when check(o) -> 1;
        case Box(Object o) -> 2;
    };
}

public record Box(Object o) {}


Note the nested `Object o` both accept `null`.

javac will compile this using two nested switches, like:


int $restartIndex = 0;
return switch (b, $restartIndex) { //will start matching as $restartIndex
     case Box $b -> {
         int $nestedRestartIndex = 0;
         yield switch ($b.o(), $nestedRestartIndex) {  //will start matching as $nestedRestartIndex
             case Integer i -> 0;
             case null, Object o -> {
                 if (!check(o)) {
                     $nestedRestartIndex = 2;
                     continue-nested-switch; //goto to the start of the nested switch again, with the updated $nestedRestartIndex
                 }
                 yield 1;
             }
             default -> {
                  $restartIndex = 1;
                  continue-main-switch; //goto to begining of the main switch again, with the updated $restartIndex
             }
        };
    case Box(Object o) -> 2;
}


javac uses the restart index to implement (especially) guards - if the guard returns true, the matching (the whole switch) is restarted on the next case. javac tries to merge multiple cases with patterns with the same prefix into the same case, to reduce unnecessary matching.

There's a problem with the restarts, and that is that for `case null`, the restart index is ignored. I.e. even though the nested switch in `case null, Object o` sets the `$nestedRestartIndex` to 2, the switch will jump to `null` again after being restarted. This is because for the `null` selector, `SwitchBootstraps.typeSwitch` always returns `-1`.

The solution proposed here is to avoid factoring the nullable patterns into nested switches with any other patterns, as we cannot keep the semantics for the nested switch in such a case.

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

Commit messages:
 - 8326129: Java Record Pattern Match leads to infinite loop

Changes: https://git.openjdk.org/jdk/pull/17951/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17951&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8326129
  Stats: 84 lines in 2 files changed: 82 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/17951.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17951/head:pull/17951

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

From jjg at openjdk.org  Thu Feb 22 00:17:29 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 22 Feb 2024 00:17:29 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <v4pGQYCagdT28cdABJW1F4NYIfyDmcmdQSHjER__oj4=.00669703-c320-4111-a791-3d2652e247fc@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:

 - update DocCommentParser and tests to improve handling of code blocks and code spans in Markdown documentation comments
 - fix indentation, for consistency

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/25921fd0..5fc9c84a

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=37
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=36-37

  Stats: 1240 lines in 4 files changed: 918 ins; 275 del; 47 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From liach at openjdk.org  Thu Feb 22 05:38:19 2024
From: liach at openjdk.org (Chen Liang)
Date: Thu, 22 Feb 2024 05:38:19 GMT
Subject: RFR: 8323707: Adjust Classfile API's type arg model to better
 represent the embodied type [v3]
In-Reply-To: <MHOvwnWcnocbfiiIdkzyqB6qdt-f2HwiaTurds0p3Pg=.cda1d910-6ef4-4577-a539-10a959adcd1f@github.com>
References: <MHOvwnWcnocbfiiIdkzyqB6qdt-f2HwiaTurds0p3Pg=.cda1d910-6ef4-4577-a539-10a959adcd1f@github.com>
Message-ID: <NAB5piZWVQzqTDA-ge3wz3OsPq4l7qOQAqlVGz9bLq0=.d7708369-2acb-4dc4-869d-78ffc8219601@github.com>

> API changes as discussed on the mailing list: https://mail.openjdk.org/pipermail/classfile-api-dev/2023-November/000419.html
> 
> Additional questions:
> 1. Whether to rename `WildcardIndicator.DEFAULT` to `NONE`

Chen Liang has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 11 commits:

 - Rename no wildcard indicator, improve docs slightly
 - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
 - Merge branch 'master' into fix/typearg-model
 - redundant line
 - Fix a test in langtools, copyright year
 - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
 - Implementation cleanup, test update
 - Merge branch 'master' into fix/typearg-model
 - Formatting
 - Nuke signatureString and fix test fialure from bad cast
 - ... and 1 more: https://git.openjdk.org/jdk/compare/0bcece99...62d25642

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

Changes: https://git.openjdk.org/jdk/pull/16517/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16517&range=02
  Stats: 132 lines in 6 files changed: 49 ins; 32 del; 51 mod
  Patch: https://git.openjdk.org/jdk/pull/16517.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16517/head:pull/16517

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

From liach at openjdk.org  Thu Feb 22 05:41:55 2024
From: liach at openjdk.org (Chen Liang)
Date: Thu, 22 Feb 2024 05:41:55 GMT
Subject: RFR: 8323707: Adjust Classfile API's type arg model to better
 represent the embodied type [v3]
In-Reply-To: <i_8OaRahDXxOaQTsxOg2U357qSaWnVTKuPBzxBevigI=.6ededec2-4435-43b2-a27e-55ef80986801@github.com>
References: <MHOvwnWcnocbfiiIdkzyqB6qdt-f2HwiaTurds0p3Pg=.cda1d910-6ef4-4577-a539-10a959adcd1f@github.com>
 <ucgottWGuHTVA_NdHh2ihwUieoQBMknwHLfQetEqyB8=.1bfca408-a3ee-47ad-90eb-ac2d14b128ad@github.com>
 <i_8OaRahDXxOaQTsxOg2U357qSaWnVTKuPBzxBevigI=.6ededec2-4435-43b2-a27e-55ef80986801@github.com>
Message-ID: <jd3pr__YAhfUms7GRFCAmwJjfcSW2y1G475Y1BX8edc=.5ce83c09-9810-49a3-a4b9-cfdf49191e34@github.com>

On Mon, 19 Feb 2024 15:28:23 GMT, David M. Lloyd <duke at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/classfile/Signature.java line 219:
>> 
>>> 217:                  * no wildcard (empty), an exact type
>>> 218:                  */
>>> 219:                 DEFAULT,
>> 
>> I?m?personally in?favour of?naming this?`NONE`.
>
> A belated +1 to this, at least not calling it `DEFAULT` because that has at best no meaning, and at worst it's outright confusing. If not `NONE`, then what about `EXACT`?
> 
> In my own old parsing code I have an enum called `Variance` with values `INVARIANT`, `COVARIANT`, and `CONTRAVARIANT`, but that might be a bit confusing considering that `EXTENDS` and `SUPER` match the Java language keywords directly.
> 
> As an aside, the javadoc here could be a little better IMO.

Performed the rename. `NONE` is better than `EXACT`, as there indeed is no indicator char for this bounded type argument.

I have added the terms of `invariant` `covariant` `contravariant` to the docs, so that they can be searched with the Javadoc search function. (These are official CS terms so shouldn't be ambiguous)

I decided not too add exact descriptions, like "method parameters EXTENDS can only accept null" or "method return type SUPER can only return Object". These details of Java type system may be subject to change in the future, and this is really describing details of a ClassFile attribute instead of the Java type system.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16517#discussion_r1498670793

From liach at openjdk.org  Thu Feb 22 05:45:54 2024
From: liach at openjdk.org (Chen Liang)
Date: Thu, 22 Feb 2024 05:45:54 GMT
Subject: RFR: 8323707: Adjust Classfile API's type arg model to better
 represent the embodied type [v3]
In-Reply-To: <NAB5piZWVQzqTDA-ge3wz3OsPq4l7qOQAqlVGz9bLq0=.d7708369-2acb-4dc4-869d-78ffc8219601@github.com>
References: <MHOvwnWcnocbfiiIdkzyqB6qdt-f2HwiaTurds0p3Pg=.cda1d910-6ef4-4577-a539-10a959adcd1f@github.com>
 <NAB5piZWVQzqTDA-ge3wz3OsPq4l7qOQAqlVGz9bLq0=.d7708369-2acb-4dc4-869d-78ffc8219601@github.com>
Message-ID: <3ybH_l-uRy3HOz9raNFBRoFGgfuUCTsf-sh357NSkZk=.880ccd32-fcc8-4e70-b08d-1fc350ea19d5@github.com>

On Thu, 22 Feb 2024 05:38:19 GMT, Chen Liang <liach at openjdk.org> wrote:

>> API changes as discussed on the mailing list: https://mail.openjdk.org/pipermail/classfile-api-dev/2023-November/000419.html
>> 
>> Additional questions:
>> 1. Whether to rename `WildcardIndicator.DEFAULT` to `NONE`
>
> Chen Liang has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 11 commits:
> 
>  - Rename no wildcard indicator, improve docs slightly
>  - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
>  - Merge branch 'master' into fix/typearg-model
>  - redundant line
>  - Fix a test in langtools, copyright year
>  - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
>  - Implementation cleanup, test update
>  - Merge branch 'master' into fix/typearg-model
>  - Formatting
>  - Nuke signatureString and fix test fialure from bad cast
>  - ... and 1 more: https://git.openjdk.org/jdk/compare/0bcece99...62d25642

@asotona How does this patch look for the roadmap of Class-File API 2nd review? Brian agreed to it before, will we consider or reject this?

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

PR Comment: https://git.openjdk.org/jdk/pull/16517#issuecomment-1958743153

From hannesw at openjdk.org  Thu Feb 22 14:56:13 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 22 Feb 2024 14:56:13 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
In-Reply-To: <v4pGQYCagdT28cdABJW1F4NYIfyDmcmdQSHjER__oj4=.00669703-c320-4111-a791-3d2652e247fc@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <v4pGQYCagdT28cdABJW1F4NYIfyDmcmdQSHjER__oj4=.00669703-c320-4111-a791-3d2652e247fc@github.com>
Message-ID: <lZ0LMtIaIccoOtMm4jDBR1FgfXOk82GHrGkqgjFCBOw=.ec4699ff-ddde-4fed-ba22-960ab9a60538@github.com>

On Thu, 22 Feb 2024 00:17:29 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - update DocCommentParser and tests to improve handling of code blocks and code spans in Markdown documentation comments
>  - fix indentation, for consistency

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1373:

> 1371:                 while (indent < currIndent) {
> 1372:                     currIndent = indentStack.pop();
> 1373:                 }

This new Markdown class looks very good!

I think in this place we also need to check for indented code blocks, since we reduced `currIndent` and may have 4 or more character indentation compared to the new `currIndent` value. 

My tentative fix is to add the following code here, but maybe there's a more elegant solution by restructuring the method to first check for `indent < currIndent` and then for new indented code blocks.


                if (indent >= currIndent + 4 && !isParagraph(prevLineKind)) {
                    blockId++;
                    lineKind = LineKind.INDENTED_CODE_BLOCK;
                    return;
                }


The following could be added to `TestMarkdownCodeBlocks.java` to test this case:


            POST_LIST_INDENT(
                    """
                         1.  list item
                         
                             second paragraph
                       
                            {@code CODE}
                            @Anno

                        end""",
                    """
                        <ol>
                        <li>
                        <p>list item</p>
                        <p>second paragraph</p>
                        </li>
                        </ol>
                        <pre><code>{@code CODE}
                        @Anno
                        </code></pre>
                        <p>end</p>"""),

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1499375866

From jjg at openjdk.org  Thu Feb 22 15:17:10 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 22 Feb 2024 15:17:10 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
In-Reply-To: <lZ0LMtIaIccoOtMm4jDBR1FgfXOk82GHrGkqgjFCBOw=.ec4699ff-ddde-4fed-ba22-960ab9a60538@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <v4pGQYCagdT28cdABJW1F4NYIfyDmcmdQSHjER__oj4=.00669703-c320-4111-a791-3d2652e247fc@github.com>
 <lZ0LMtIaIccoOtMm4jDBR1FgfXOk82GHrGkqgjFCBOw=.ec4699ff-ddde-4fed-ba22-960ab9a60538@github.com>
Message-ID: <GFw06006VTxdN05GICC5FMB-JEj7tD_GyYdhFUzIals=.66d6226d-95e7-4164-9864-c773d8100fe6@github.com>

On Thu, 22 Feb 2024 14:53:11 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - update DocCommentParser and tests to improve handling of code blocks and code spans in Markdown documentation comments
>>  - fix indentation, for consistency
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1373:
> 
>> 1371:                 while (indent < currIndent) {
>> 1372:                     currIndent = indentStack.pop();
>> 1373:                 }
> 
> This new Markdown class looks very good!
> 
> I think in this place we also need to check for indented code blocks, since we reduced `currIndent` and may have 4 or more character indentation compared to the new `currIndent` value. 
> 
> My tentative fix is to add the following code here, but maybe a more elegant solution can be found by restructuring the method to first check for `indent < currIndent` and then only having to check for new indented code blocks once.
> 
> 
>                 if (indent >= currIndent + 4 && !isParagraph(prevLineKind)) {
>                     blockId++;
>                     lineKind = LineKind.INDENTED_CODE_BLOCK;
>                     return;
>                 }
> 
> 
> The following could be added to `TestMarkdownCodeBlocks.java` to test this case:
> 
> 
>             POST_LIST_INDENT(
>                     """
>                          1.  list item
>                          
>                              second paragraph
>                        
>                             {@code CODE}
>                             @Anno
> 
>                         end""",
>                     """
>                         <ol>
>                         <li>
>                         <p>list item</p>
>                         <p>second paragraph</p>
>                         </li>
>                         </ol>
>                         <pre><code>{@code CODE}
>                         @Anno
>                         </code></pre>
>                         <p>end</p>"""),

Thanks.  I will investigate your hint to look for a more elegant solution.  Thanks for the new test case.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1499408829

From vromero at openjdk.org  Thu Feb 22 18:29:54 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Thu, 22 Feb 2024 18:29:54 GMT
Subject: RFR: 8326129: Java Record Pattern Match leads to infinite loop
In-Reply-To: <QKK2RvbTvU7fd2q2Dy-LxQ18c7lKJGbWD6Ar1FhLbww=.e9b52617-74e0-4c53-b883-d1438fcd3ffe@github.com>
References: <QKK2RvbTvU7fd2q2Dy-LxQ18c7lKJGbWD6Ar1FhLbww=.e9b52617-74e0-4c53-b883-d1438fcd3ffe@github.com>
Message-ID: <3CvhqVbjiQ3nijy8pdGMoAs--7gKUl7j1eXmDPY7Je0=.3c44a063-2922-4bc8-bf12-7eb8553f13d3@github.com>

On Wed, 21 Feb 2024 15:05:28 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Consider code like:
> 
> private int test(Box b) {
>     return switch (b) {
>         case Box(Integer i) -> 0;
>         case Box(Object o) when check(o) -> 1;
>         case Box(Object o) -> 2;
>     };
> }
> 
> public record Box(Object o) {}
> 
> 
> Note the nested `Object o` both accept `null`.
> 
> javac will compile this using two nested switches, like:
> 
> 
> int $restartIndex = 0;
> return switch (b, $restartIndex) { //will start matching as $restartIndex
>      case Box $b -> {
>          int $nestedRestartIndex = 0;
>          yield switch ($b.o(), $nestedRestartIndex) {  //will start matching as $nestedRestartIndex
>              case Integer i -> 0;
>              case null, Object o -> {
>                  if (!check(o)) {
>                      $nestedRestartIndex = 2;
>                      continue-nested-switch; //goto to the start of the nested switch again, with the updated $nestedRestartIndex
>                  }
>                  yield 1;
>              }
>              default -> {
>                   $restartIndex = 1;
>                   continue-main-switch; //goto to begining of the main switch again, with the updated $restartIndex
>              }
>         };
>     case Box(Object o) -> 2;
> }
> 
> 
> javac uses the restart index to implement (especially) guards - if the guard returns true, the matching (the whole switch) is restarted on the next case. javac tries to merge multiple cases with patterns with the same prefix into the same case, to reduce unnecessary matching.
> 
> There's a problem with the restarts, and that is that for `case null`, the restart index is ignored. I.e. even though the nested switch in `case null, Object o` sets the `$nestedRestartIndex` to 2, the switch will jump to `null` again after being restarted. This is because for the `null` selector, `SwitchBootstraps.typeSwitch` always returns `-1`.
> 
> The solution proposed here is to avoid factoring the nullable patterns into nested switches with any other patterns, as we cannot keep the semantics for the nested switch in such a case.

looks sensible

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17951#pullrequestreview-1896612411

From jjg at openjdk.org  Thu Feb 22 18:52:23 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 22 Feb 2024 18:52:23 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v39]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <5SSS_1z3Obdod4_VuERMXIEGR1MJO4HPJ0S809IHIbw=.99506367-dacb-4b75-b1c6-116f5b6f842e@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  refactor tests for Markdown headings into a separate test class.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/5fc9c84a..72420419

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=38
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=37-38

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

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

From jjg at openjdk.org  Thu Feb 22 19:17:04 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 22 Feb 2024 19:17:04 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
In-Reply-To: <GFw06006VTxdN05GICC5FMB-JEj7tD_GyYdhFUzIals=.66d6226d-95e7-4164-9864-c773d8100fe6@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <v4pGQYCagdT28cdABJW1F4NYIfyDmcmdQSHjER__oj4=.00669703-c320-4111-a791-3d2652e247fc@github.com>
 <lZ0LMtIaIccoOtMm4jDBR1FgfXOk82GHrGkqgjFCBOw=.ec4699ff-ddde-4fed-ba22-960ab9a60538@github.com>
 <GFw06006VTxdN05GICC5FMB-JEj7tD_GyYdhFUzIals=.66d6226d-95e7-4164-9864-c773d8100fe6@github.com>
Message-ID: <yOLgfI9s-ucYNS_TkfFnF-PSeT45Jwbr9ezb1dKXhxs=.87c81bb6-8f22-4a32-bd86-67854eb3abf7@github.com>

On Thu, 22 Feb 2024 15:14:32 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1373:
>> 
>>> 1371:                 while (indent < currIndent) {
>>> 1372:                     currIndent = indentStack.pop();
>>> 1373:                 }
>> 
>> This new Markdown class looks very good!
>> 
>> I think in this place we also need to check for indented code blocks, since we reduced `currIndent` and may have 4 or more character indentation compared to the new `currIndent` value. 
>> 
>> My tentative fix is to add the following code here, but maybe a more elegant solution can be found by restructuring the method to first check for `indent < currIndent` and then only having to check for new indented code blocks once.
>> 
>> 
>>                 if (indent >= currIndent + 4 && !isParagraph(prevLineKind)) {
>>                     blockId++;
>>                     lineKind = LineKind.INDENTED_CODE_BLOCK;
>>                     return;
>>                 }
>> 
>> 
>> The following could be added to `TestMarkdownCodeBlocks.java` to test this case:
>> 
>> 
>>             POST_LIST_INDENT(
>>                     """
>>                          1.  list item
>>                          
>>                              second paragraph
>>                        
>>                             {@code CODE}
>>                             @Anno
>> 
>>                         end""",
>>                     """
>>                         <ol>
>>                         <li>
>>                         <p>list item</p>
>>                         <p>second paragraph</p>
>>                         </li>
>>                         </ol>
>>                         <pre><code>{@code CODE}
>>                         @Anno
>>                         </code></pre>
>>                         <p>end</p>"""),
>
> Thanks.  I will investigate your hint to look for a more elegant solution.  Thanks for the new test case.

>I think in this place we also need to check for indented code blocks, since we reduced currIndent and may have 4 or more character indentation compared to the new currIndent value.

This seems wrong. Surely, we should not reduce the indentation and then for the same line in the comment check for an extra-indented line. Or else I am missing something.

That being said, thanks for the test case. I will investigate it.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1499779864

From jjg at openjdk.org  Thu Feb 22 19:20:03 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 22 Feb 2024 19:20:03 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
In-Reply-To: <yOLgfI9s-ucYNS_TkfFnF-PSeT45Jwbr9ezb1dKXhxs=.87c81bb6-8f22-4a32-bd86-67854eb3abf7@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <v4pGQYCagdT28cdABJW1F4NYIfyDmcmdQSHjER__oj4=.00669703-c320-4111-a791-3d2652e247fc@github.com>
 <lZ0LMtIaIccoOtMm4jDBR1FgfXOk82GHrGkqgjFCBOw=.ec4699ff-ddde-4fed-ba22-960ab9a60538@github.com>
 <GFw06006VTxdN05GICC5FMB-JEj7tD_GyYdhFUzIals=.66d6226d-95e7-4164-9864-c773d8100fe6@github.com>
 <yOLgfI9s-ucYNS_TkfFnF-PSeT45Jwbr9ezb1dKXhxs=.87c81bb6-8f22-4a32-bd86-67854eb3abf7@github.com>
Message-ID: <c-Pj-sknElhYrvYqC7a9MTd_Kn5KktGnvXtvz2-RXeE=.0ae724da-1770-495a-a4c9-126a61d7e9b3@github.com>

On Thu, 22 Feb 2024 19:13:57 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Thanks.  I will investigate your hint to look for a more elegant solution.  Thanks for the new test case.
>
>>I think in this place we also need to check for indented code blocks, since we reduced currIndent and may have 4 or more character indentation compared to the new currIndent value.
> 
> This seems wrong. Surely, we should not reduce the indentation and then for the same line in the comment check for an extra-indented line. Or else I am missing something.
> 
> That being said, thanks for the test case. I will investigate it.

Update: I see and understand your test case.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1499787391

From jjg at openjdk.org  Thu Feb 22 20:47:25 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 22 Feb 2024 20:47:25 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v40]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <ir_8ofnXSTpl0w9d-a47PuuGX6QLp8Lcnc4jPoVAIl8=.3aaf8ef9-5997-44ae-b8ee-0b83cb80967e@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  fix Markdown.update for new POST_LIST_INDENT test case given in review feedback

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/72420419..27bc0b9d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=39
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=38-39

  Stats: 94 lines in 4 files changed: 53 ins; 16 del; 25 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From jjg at openjdk.org  Thu Feb 22 20:52:10 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 22 Feb 2024 20:52:10 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v38]
In-Reply-To: <c-Pj-sknElhYrvYqC7a9MTd_Kn5KktGnvXtvz2-RXeE=.0ae724da-1770-495a-a4c9-126a61d7e9b3@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <v4pGQYCagdT28cdABJW1F4NYIfyDmcmdQSHjER__oj4=.00669703-c320-4111-a791-3d2652e247fc@github.com>
 <lZ0LMtIaIccoOtMm4jDBR1FgfXOk82GHrGkqgjFCBOw=.ec4699ff-ddde-4fed-ba22-960ab9a60538@github.com>
 <GFw06006VTxdN05GICC5FMB-JEj7tD_GyYdhFUzIals=.66d6226d-95e7-4164-9864-c773d8100fe6@github.com>
 <yOLgfI9s-ucYNS_TkfFnF-PSeT45Jwbr9ezb1dKXhxs=.87c81bb6-8f22-4a32-bd86-67854eb3abf7@github.com>
 <c-Pj-sknElhYrvYqC7a9MTd_Kn5KktGnvXtvz2-RXeE=.0ae724da-1770-495a-a4c9-126a61d7e9b3@github.com>
Message-ID: <mC1vsfZi_1FTX5mQ4d4ZNmSiSJcmhg0ENUc4UwO1nU0=.555fc394-f1d9-4f84-9061-f192725d9835@github.com>

On Thu, 22 Feb 2024 19:17:09 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>>>I think in this place we also need to check for indented code blocks, since we reduced currIndent and may have 4 or more character indentation compared to the new currIndent value.
>> 
>> This seems wrong. Surely, we should not reduce the indentation and then for the same line in the comment check for an extra-indented line. Or else I am missing something.
>> 
>> That being said, thanks for the test case. I will investigate it.
>
> Update: I see and understand your test case.

Update: I found that more elegant solution you hinted at, by refactoring the method from nested `if` statements to a series of checks with early returns.

The test case you provided now works as expected.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1499918026

From jjg at openjdk.org  Thu Feb 22 21:00:35 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 22 Feb 2024 21:00:35 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v41]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <WkCCiFicRs9pw6GfmGtqlojAaHFuLfyfnw1elgmajiA=.cd12a572-8339-4869-9292-59b6fd347529@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  fix whitespace

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/27bc0b9d..40616865

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=40
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=39-40

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

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

From vromero at openjdk.org  Thu Feb 22 21:52:53 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Thu, 22 Feb 2024 21:52:53 GMT
Subject: RFR: 8325215: Incorrect not exhaustive switch error
In-Reply-To: <mrhqhI191FNOiIHnUU7b2ggs77ZzZIGkeUK0OtZXVCc=.a7ccefbc-51a2-4a20-af8f-2531a90b0e1a@github.com>
References: <mrhqhI191FNOiIHnUU7b2ggs77ZzZIGkeUK0OtZXVCc=.a7ccefbc-51a2-4a20-af8f-2531a90b0e1a@github.com>
Message-ID: <c4xuLCTgDexkHldqYCLYNAMM0-xJ0HU_xQ-OfOM2yhI=.8baebf5b-b385-4c50-9345-40d70ffa21ea@github.com>

On Wed, 21 Feb 2024 14:48:54 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Consider code like:
> 
> public class Test {
> 
>     sealed interface A permits T, U {}
>     sealed interface B permits V, W {}
>     static final class T implements A {}
>     static final class U implements A {}
>     static final class V implements B {}
>     static final class W implements B {}
>     final static record R(A a, B b) {}
> 
>     static int r(R r) {
>         return switch (r) {
>             case R(A a, V b) -> 1;
>             case R(T a, W b) -> 2;
>             case R(U a, W b) -> 3;
>         };
>     }
> }
> 
> 
> javac will correctly consider this to be exhaustive, as `R(T a, W b)` and `R(U a, W b)` can be merged into `R(A a, W b)`, and then `R(A a, V b)` and `R(A a, W b)` are merge into `R(A a, B b)` and then into `R`.
> 
> But, if we replace `R(T a, W b)` with a more general `R(T a, B b)`, which matches everything that `R(T a, W b)` does:
> 
> public class Test {
> 
>     sealed interface A permits T, U {}
>     sealed interface B permits V, W {}
>     static final class T implements A {}
>     static final class U implements A {}
>     static final class V implements B {}
>     static final class W implements B {}
>     final static record R(A a, B b) {}
> 
>     static int r(R r) {
>         return switch (r) {
>             case R(A a, V b) -> 1;
>             case R(T a, B b) -> 2;
>             case R(U a, W b) -> 3;
>         };
>     }
> }
> 
> 
> Leads to:
> 
> $ javac /tmp/Test.java
> /tmp/Test.java:12: error: the switch expression does not cover all possible input values
>         return switch (r) {
>                ^
> 1 error
> 
> 
> The issue is that the exhaustivity algorithm is no longer able to merge `R(T a, B b)` and `R(U a, W b)` into `R(A a, W b)`, as the second nested pattern is not the same.
> 
> The rules permit replacing patterns with more strict patterns, i.e. it is permitted to replace `R(T a, B b)` with `R(T a, W b)`, and hence proceed with the merging as in the original case. The trouble is that doing such conversions may lead to high computational complexity.
> 
> The proposal in this patch is to replace all binding patterns in all patterns with their transitive permitted subtypes, but only once, and only if the algorithm fails to determine the exhaustiveness using the standing approach. This may lead to a potentially significant performance penalty, but only in case where the algorithm would mark the switch exhaustive.
> 
> The main alternative to this proposal would be to allow the algorithm to see `B` and `W` as equivalent when attempting to merge  `R(T a, B b)` and `R(U a, W b)`. But, currently, this equivalence ch...

lgtm

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17949#pullrequestreview-1897020897

From jjg at openjdk.org  Thu Feb 22 23:20:31 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 22 Feb 2024 23:20:31 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v42]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <BYhObV610c2nUt1KyZyl1tSawl2C9lvTp24XWnUUzuA=.e591edce-ee80-4beb-91d4-f9cd45505025@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  add support for (top-level) trailing code blocks
  add simple test case with tabs
  add TestMarkdownCodeBlocks.testTypical

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/40616865..d460ee33

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=41
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=40-41

  Stats: 143 lines in 3 files changed: 135 ins; 2 del; 6 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From jlahoda at openjdk.org  Fri Feb 23 08:59:00 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Fri, 23 Feb 2024 08:59:00 GMT
Subject: Integrated: 8325215: Incorrect not exhaustive switch error
In-Reply-To: <mrhqhI191FNOiIHnUU7b2ggs77ZzZIGkeUK0OtZXVCc=.a7ccefbc-51a2-4a20-af8f-2531a90b0e1a@github.com>
References: <mrhqhI191FNOiIHnUU7b2ggs77ZzZIGkeUK0OtZXVCc=.a7ccefbc-51a2-4a20-af8f-2531a90b0e1a@github.com>
Message-ID: <NKusBloqFyiFuUfXXvLvR8R-qO4an6dTHhnc3RYcA2A=.3bd02d9a-e04a-457e-b5e7-1b64e927b63b@github.com>

On Wed, 21 Feb 2024 14:48:54 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Consider code like:
> 
> public class Test {
> 
>     sealed interface A permits T, U {}
>     sealed interface B permits V, W {}
>     static final class T implements A {}
>     static final class U implements A {}
>     static final class V implements B {}
>     static final class W implements B {}
>     final static record R(A a, B b) {}
> 
>     static int r(R r) {
>         return switch (r) {
>             case R(A a, V b) -> 1;
>             case R(T a, W b) -> 2;
>             case R(U a, W b) -> 3;
>         };
>     }
> }
> 
> 
> javac will correctly consider this to be exhaustive, as `R(T a, W b)` and `R(U a, W b)` can be merged into `R(A a, W b)`, and then `R(A a, V b)` and `R(A a, W b)` are merge into `R(A a, B b)` and then into `R`.
> 
> But, if we replace `R(T a, W b)` with a more general `R(T a, B b)`, which matches everything that `R(T a, W b)` does:
> 
> public class Test {
> 
>     sealed interface A permits T, U {}
>     sealed interface B permits V, W {}
>     static final class T implements A {}
>     static final class U implements A {}
>     static final class V implements B {}
>     static final class W implements B {}
>     final static record R(A a, B b) {}
> 
>     static int r(R r) {
>         return switch (r) {
>             case R(A a, V b) -> 1;
>             case R(T a, B b) -> 2;
>             case R(U a, W b) -> 3;
>         };
>     }
> }
> 
> 
> Leads to:
> 
> $ javac /tmp/Test.java
> /tmp/Test.java:12: error: the switch expression does not cover all possible input values
>         return switch (r) {
>                ^
> 1 error
> 
> 
> The issue is that the exhaustivity algorithm is no longer able to merge `R(T a, B b)` and `R(U a, W b)` into `R(A a, W b)`, as the second nested pattern is not the same.
> 
> The rules permit replacing patterns with more strict patterns, i.e. it is permitted to replace `R(T a, B b)` with `R(T a, W b)`, and hence proceed with the merging as in the original case. The trouble is that doing such conversions may lead to high computational complexity.
> 
> The proposal in this patch is to replace all binding patterns in all patterns with their transitive permitted subtypes, but only once, and only if the algorithm fails to determine the exhaustiveness using the standing approach. This may lead to a potentially significant performance penalty, but only in case where the algorithm would mark the switch exhaustive.
> 
> The main alternative to this proposal would be to allow the algorithm to see `B` and `W` as equivalent when attempting to merge  `R(T a, B b)` and `R(U a, W b)`. But, currently, this equivalence ch...

This pull request has now been integrated.

Changeset: cb809f8e
Author:    Jan Lahoda <jlahoda at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/cb809f8e04c12f0d06237c9c3fd05f6c585098a6
Stats:     130 lines in 2 files changed: 128 ins; 1 del; 1 mod

8325215: Incorrect not exhaustive switch error

Reviewed-by: vromero

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

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

From jlahoda at openjdk.org  Fri Feb 23 10:12:00 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Fri, 23 Feb 2024 10:12:00 GMT
Subject: Integrated: 8326129: Java Record Pattern Match leads to infinite loop
In-Reply-To: <QKK2RvbTvU7fd2q2Dy-LxQ18c7lKJGbWD6Ar1FhLbww=.e9b52617-74e0-4c53-b883-d1438fcd3ffe@github.com>
References: <QKK2RvbTvU7fd2q2Dy-LxQ18c7lKJGbWD6Ar1FhLbww=.e9b52617-74e0-4c53-b883-d1438fcd3ffe@github.com>
Message-ID: <bb1zWr-0oln8_HoeN3UqHNmIbL6QUu85X8xj1Bkz_oU=.9f04b268-2120-46b0-afc5-3972ae0bf293@github.com>

On Wed, 21 Feb 2024 15:05:28 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> Consider code like:
> 
> private int test(Box b) {
>     return switch (b) {
>         case Box(Integer i) -> 0;
>         case Box(Object o) when check(o) -> 1;
>         case Box(Object o) -> 2;
>     };
> }
> 
> public record Box(Object o) {}
> 
> 
> Note the nested `Object o` both accept `null`.
> 
> javac will compile this using two nested switches, like:
> 
> 
> int $restartIndex = 0;
> return switch (b, $restartIndex) { //will start matching as $restartIndex
>      case Box $b -> {
>          int $nestedRestartIndex = 0;
>          yield switch ($b.o(), $nestedRestartIndex) {  //will start matching as $nestedRestartIndex
>              case Integer i -> 0;
>              case null, Object o -> {
>                  if (!check(o)) {
>                      $nestedRestartIndex = 2;
>                      continue-nested-switch; //goto to the start of the nested switch again, with the updated $nestedRestartIndex
>                  }
>                  yield 1;
>              }
>              default -> {
>                   $restartIndex = 1;
>                   continue-main-switch; //goto to begining of the main switch again, with the updated $restartIndex
>              }
>         };
>     case Box(Object o) -> 2;
> }
> 
> 
> javac uses the restart index to implement (especially) guards - if the guard returns true, the matching (the whole switch) is restarted on the next case. javac tries to merge multiple cases with patterns with the same prefix into the same case, to reduce unnecessary matching.
> 
> There's a problem with the restarts, and that is that for `case null`, the restart index is ignored. I.e. even though the nested switch in `case null, Object o` sets the `$nestedRestartIndex` to 2, the switch will jump to `null` again after being restarted. This is because for the `null` selector, `SwitchBootstraps.typeSwitch` always returns `-1`.
> 
> The solution proposed here is to avoid factoring the nullable patterns into nested switches with any other patterns, as we cannot keep the semantics for the nested switch in such a case.

This pull request has now been integrated.

Changeset: 93a2e773
Author:    Jan Lahoda <jlahoda at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/93a2e773a508ef7960214e20c2df5e8456f2e8c2
Stats:     84 lines in 2 files changed: 82 ins; 0 del; 2 mod

8326129: Java Record Pattern Match leads to infinite loop

Reviewed-by: vromero

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

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

From abimpoudis at openjdk.org  Fri Feb 23 13:52:06 2024
From: abimpoudis at openjdk.org (Aggelos Biboudis)
Date: Fri, 23 Feb 2024 13:52:06 GMT
Subject: RFR: 8326404: Assertion error when trying to compile switch with
 fallthrough with pattern
Message-ID: <TDLuY-fw0oPT_HwQeMtBNn61l-cxlSKTlbmPQB78xMQ=.a716585a-23cd-4fbf-b990-a142e2bc431a@github.com>

The assertion error that was raised in the bug report is a result of local variables not being defined in the case of switches that mix type patterns and record patterns with fall-through. e.g., a print after the `TransPatterns` phase:


private static int run(Object o) {
  int i = 0;
  /*synthetic*/ Object selector2$temp = <*nullchk*>(o);
  /*synthetic*/ int index$3 = 0;
  switch (java.lang.runtime.SwitchBootstraps.typeSwitch(selector2$temp, index$3)) {
    case 0:
      String s;
      if (!(let s = (String)selector2$temp; in true)) {
        index$3 = 1;
        continue;
      }
      i++;
    case 1:
      {
      /*synthetic*/ Object selector4$temp = $b$O.a(); // $b$O appears undefined here 
      ...
      }
    ...
  }
}


The code for unrolling a case label into local variable declaration statements appears in `handleSwitch` here: https://github.com/openjdk/jdk/pull/17981/files#diff-e50bbfa8783f3bc8f5542452740b78f3167bee19be7365a87da2298c6333cca6L593-L606

While`patchCompletingNormallyCases` takes care of statement block propagation, for code that completes normally, unfortunately this code is called late (after the optimization that merges common type tests e.g., `case R(...): .... case R(...): ....`). 

The fix bails out of this optimization in the presence of fall-through. For example in the `run3_break1` included, the optimization is triggered. In the rest, not.

Additionally, this patch elides the unnecessary binding generation of unnamed pattern variables from the binding context.

Thanks @lahodaj for contributing this solution ?

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

Commit messages:
 - 8326404: Assertion error when trying to compile switch with fallthrough with pattern

Changes: https://git.openjdk.org/jdk/pull/17981/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17981&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8326404
  Stats: 171 lines in 2 files changed: 165 ins; 2 del; 4 mod
  Patch: https://git.openjdk.org/jdk/pull/17981.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17981/head:pull/17981

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

From maurizio.cimadamore at oracle.com  Fri Feb 23 14:25:08 2024
From: maurizio.cimadamore at oracle.com (Maurizio Cimadamore)
Date: Fri, 23 Feb 2024 14:25:08 +0000
Subject: ? extend T[] is not considered an array
In-Reply-To: <CAKDaPBc2ZnGWpuy2WTFZHe7H2ZHqr0+OUj=WAwtwMqWZuv2F7A@mail.gmail.com>
References: <CAKDaPBc2ZnGWpuy2WTFZHe7H2ZHqr0+OUj=WAwtwMqWZuv2F7A@mail.gmail.com>
Message-ID: <6f57b85c-b458-4866-84ed-8cac0c123e6a@oracle.com>

Hi,
as currently specified, the type of the expression used in array access 
must be an array type - see JLS 15.10.3

> The type of the array reference expression must be an array type (call 
> it T|[]|, an array whose components are of type T), or a compile-time 
> error occurs.
>
There is nothing in the JLS to suggest that an array type is anything 
other than some type T followed by array brackets. E.g. in JLS 10.1:

> An array type is written as the name of an element type followed by 
> some number of empty pairs of square brackets |[]|. The number of 
> bracket pairs indicates the depth of array nesting.
>
So, javac is behaving as specified in the JLS. Note that wildcards are a 
distraction here. The wildcard generates a captured type - that is a 
type variable whose upper bound is an array type.

The following program:

```
class Foo<X extends Object[]> {
 ??? void test(X x) {? Object o = x[0]; }
}
```

Exhibits the same behavior - e.g. it fails to compile, because "x" is 
not an array.

So, the question you are asking is: why can't we assume that a 
type-variable whose upper bound is an array type is also an array type?

This is discussed here:

https://bugs.openjdk.org/browse/JDK-8013843

My reading is that it's doable, but it's work to make sure that nothing 
else gets affected. E.g. if we treat as array anything that has an array 
supertype, then the "null type" might get tangled in the mix (e.g. 
null[0]). Of course this is not a reason for not doing it - but some 
care is required. For-each loops might be affected as well.

Cheers
Maurizio

On 13/01/2024 12:38, Attila Kelemen wrote:
> Hi,
>
> I have not found anything in JLS specifically mentioning this. So, I'm 
> not sure if it is intentional, but the following code does not compile 
> (in any versions of Java I have tried):
>
> ```
> interface ForEachable<T> {
> ? void forEach(Consumer<? super T> consumer);
> }
>
> List<String> wrongMethod(ForEachable<? extends String[]> arrays) {
> ? var result = new ArrayList<String>();
> ? arrays.forEach(array -> result.add(array[0]));
> ? return result;
> }
> ```
>
> or in an even simpler example:
>
> ```
> String first(Supplier<? extends String[]> supplier) {
> ? return supplier.get()[0];
> }
> ```
>
> The compiler complains about `array[0]` that `array` is not an array. 
> While I get that the compiler cannot assume that there is no subtype 
> of `String[]`, but even if there was one, I would expect it to be an 
> array,?and be indexable.
>
> An obvious workaround is to assign `array` to a new local variable, 
> but it is awkward to do.
>
> Is this behavior a bug, or something required by the JLS?
>
> Thanks,
> Attila
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/compiler-dev/attachments/20240223/896d8a0e/attachment.htm>

From jjg at openjdk.org  Fri Feb 23 22:27:43 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 23 Feb 2024 22:27:43 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v43]
In-Reply-To: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
Message-ID: <gwFu9c4-Y_zksoJ1Tu4eJ-rJm0DEf2EYCZj2OVVIrUE=.9e9533b9-751e-4dfd-890e-4dc48c3399ea@github.com>

> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
> 
> Notable features:
> 
> * support for `///` documentation comments in `JavaTokenizer`
> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
> * updates to `DocCommentParser` to treat `///` comments as Markdown
> * updates to the standard doclet to render Markdown comments in HTML

Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:

  Refactor most of TestMarkdown.java into separate tests, grouped by functionality

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/16388/files
  - new: https://git.openjdk.org/jdk/pull/16388/files/d460ee33..398f93fc

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=42
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=16388&range=41-42

  Stats: 2001 lines in 9 files changed: 1143 ins; 857 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/16388.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388

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

From acobbs at openjdk.org  Sat Feb 24 00:29:11 2024
From: acobbs at openjdk.org (Archie Cobbs)
Date: Sat, 24 Feb 2024 00:29:11 GMT
Subject: RFR: 8324736: Invalid end positions for EMPTY_STATEMENT [v2]
In-Reply-To: <GhY14ltWGsqQdbxBD-dANqyBGJuBYNoIljUtwkkxJKU=.bf646a22-c02d-4bcc-bf48-b952bd47bf97@github.com>
References: <GhY14ltWGsqQdbxBD-dANqyBGJuBYNoIljUtwkkxJKU=.bf646a22-c02d-4bcc-bf48-b952bd47bf97@github.com>
Message-ID: <_SVXTU-6FrRb22P-dMVT4ohUBm_UUOzviExP75V57tU=.2665e11a-1f1f-49c2-98a6-4d0c69baacc3@github.com>

> In the fix for [JDK-8305671](https://bugs.openjdk.org/browse/JDK-8305671), an `EMPTY_STATEMENT` representing a lone semicolon was being created with the wrong source code position. The bug was that the starting position needed to be captured prior to advancing to the next token, not after.

Archie Cobbs 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 two additional commits since the last revision:

 - Merge branch 'master' into JDK-8324736
 - Fix bug where source positions got reversed.

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17595/files
  - new: https://git.openjdk.org/jdk/pull/17595/files/234cfe99..b09afc89

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17595&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17595&range=00-01

  Stats: 61953 lines in 2369 files changed: 28092 ins; 15613 del; 18248 mod
  Patch: https://git.openjdk.org/jdk/pull/17595.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17595/head:pull/17595

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

From vromero at openjdk.org  Sat Feb 24 01:19:56 2024
From: vromero at openjdk.org (Vicente Romero)
Date: Sat, 24 Feb 2024 01:19:56 GMT
Subject: RFR: 8324736: Invalid end positions for EMPTY_STATEMENT [v2]
In-Reply-To: <_SVXTU-6FrRb22P-dMVT4ohUBm_UUOzviExP75V57tU=.2665e11a-1f1f-49c2-98a6-4d0c69baacc3@github.com>
References: <GhY14ltWGsqQdbxBD-dANqyBGJuBYNoIljUtwkkxJKU=.bf646a22-c02d-4bcc-bf48-b952bd47bf97@github.com>
 <_SVXTU-6FrRb22P-dMVT4ohUBm_UUOzviExP75V57tU=.2665e11a-1f1f-49c2-98a6-4d0c69baacc3@github.com>
Message-ID: <yrMbdK40UGNETP6Kax6uQot3lr7mmF49FHyQTodD0sg=.20d5a2b4-d152-454e-b18f-b8a1debbd84a@github.com>

On Sat, 24 Feb 2024 00:29:11 GMT, Archie Cobbs <acobbs at openjdk.org> wrote:

>> In the fix for [JDK-8305671](https://bugs.openjdk.org/browse/JDK-8305671), an `EMPTY_STATEMENT` representing a lone semicolon was being created with the wrong source code position. The bug was that the starting position needed to be captured prior to advancing to the next token, not after.
>
> Archie Cobbs 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 two additional commits since the last revision:
> 
>  - Merge branch 'master' into JDK-8324736
>  - Fix bug where source positions got reversed.

lgtm

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17595#pullrequestreview-1899149660

From davidalayachew at gmail.com  Sat Feb 24 06:52:55 2024
From: davidalayachew at gmail.com (David Alayachew)
Date: Sat, 24 Feb 2024 01:52:55 -0500
Subject: For JEP 330/458,
 is there anyway to separate output of compilation vs run?
Message-ID: <CAA9v-_NvZhHn6SFp0Ex1GwdKXFyctpQaHJht1j4gY4hfk-J21g@mail.gmail.com>

Hello Compiler/Amber Dev Team,

For JEP 330 and 458 (Running Single and Multi file source code programs),
is there any way to separate the output of compilation from the output of
the run?

And as a side question, how would one go about executing single/multi file
source code programs programmatically?

Thank you for your time and help!
David Alayachew
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/compiler-dev/attachments/20240224/afc148f5/attachment.htm>

From attila.kelemen85 at gmail.com  Sat Feb 24 23:02:35 2024
From: attila.kelemen85 at gmail.com (Attila Kelemen)
Date: Sun, 25 Feb 2024 00:02:35 +0100
Subject: ? extend T[] is not considered an array
In-Reply-To: <6f57b85c-b458-4866-84ed-8cac0c123e6a@oracle.com>
References: <CAKDaPBc2ZnGWpuy2WTFZHe7H2ZHqr0+OUj=WAwtwMqWZuv2F7A@mail.gmail.com>
 <6f57b85c-b458-4866-84ed-8cac0c123e6a@oracle.com>
Message-ID: <CAKDaPBftLFkGGkvC6Cw+zU=gu4OS1WmVK1HPAmOnEMBc=tEGCw@mail.gmail.com>

Thanks, I have reread the spec more carefully, and you are right: A strict
interpretation of the spec does require this behavior (and who could fault
the compiler to strictly follow the spec). Though I'm guessing this
behavior was not the intent of the JLS just happened to be so due to this
not being a possibility before Java 5 (since Java - as far as I know -
nowhere requires upcasting besides disambiguating method overloads, and I
can see no benefit to mandate it here as well).

Also, thanks for the link to the bug report, at least I know that this is
not an unknown issue. Though since the first issue on this was opened in
2007 (JDK-6557960) I won't hold my breath for this to be fixed :)

Attila

Maurizio Cimadamore <maurizio.cimadamore at oracle.com> ezt ?rta (id?pont:
2024. febr. 23., P, 15:25):

> Hi,
> as currently specified, the type of the expression used in array access
> must be an array type - see JLS 15.10.3
>
> The type of the array reference expression must be an array type (call it
> T[], an array whose components are of type T), or a compile-time error
> occurs.
>
> There is nothing in the JLS to suggest that an array type is anything
> other than some type T followed by array brackets. E.g. in JLS 10.1:
>
> An array type is written as the name of an element type followed by some
> number of empty pairs of square brackets []. The number of bracket pairs
> indicates the depth of array nesting.
>
> So, javac is behaving as specified in the JLS. Note that wildcards are a
> distraction here. The wildcard generates a captured type - that is a type
> variable whose upper bound is an array type.
>
> The following program:
>
> ```
> class Foo<X extends Object[]> {
>     void test(X x) {  Object o = x[0]; }
> }
> ```
>
> Exhibits the same behavior - e.g. it fails to compile, because "x" is not
> an array.
>
> So, the question you are asking is: why can't we assume that a
> type-variable whose upper bound is an array type is also an array type?
>
> This is discussed here:
>
> https://bugs.openjdk.org/browse/JDK-8013843
>
> My reading is that it's doable, but it's work to make sure that nothing
> else gets affected. E.g. if we treat as array anything that has an array
> supertype, then the "null type" might get tangled in the mix (e.g.
> null[0]). Of course this is not a reason for not doing it - but some care
> is required. For-each loops might be affected as well.
>
> Cheers
> Maurizio
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/compiler-dev/attachments/20240225/a81a2cff/attachment-0001.htm>

From nekocaffeine at qq.com  Sun Feb 25 02:37:48 2024
From: nekocaffeine at qq.com (=?ISO-8859-1?B?TmVrb0NhZmZlaW5l?=)
Date: Sun, 25 Feb 2024 10:37:48 +0800
Subject: An implemented multi-threaded javac
Message-ID: <tencent_16F20C2BDE8C85090207732613701CC3A506@qq.com>

Hi everyone,

This is not a question about multi-threaded javac; this is a notice.

This implementation has already been bootstrapped, and it's not a patch but rather implemented through AOP.

You can find it here: https://github.com/NekoCaffeine/amadeus.maho/tree/master/src/amadeus.maho/amadeus/maho/lang/javac/multithreaded

I hope this implementation saves time for those who want to attempt this feat.

Disclaimer: I make no promises about this; I only use this implementation for my own production environment.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/compiler-dev/attachments/20240225/01486ccc/attachment.htm>

From syan at openjdk.org  Sun Feb 25 16:10:00 2024
From: syan at openjdk.org (SendaoYan)
Date: Sun, 25 Feb 2024 16:10:00 GMT
Subject: RFR: 8326616: tools/javac/patterns/Exhaustiveness.java intermittently
 Timeout signalled after 480 seconds
Message-ID: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>

The testcase tools/javac/patterns/Exhaustiveness.java intermittently timeout after [8325215](https://bugs.openjdk.org/browse/JDK-8325215).

I change the timeout value from 120(default value) to 300 locally, and set timeoutFactor to 20, then run this testcase 1000 times, use the concurrecy 16(the half of the nproc).
The test result show that, 90% of the test run finish in 20 seconds, but 15 times test exaust more than 5000 seconds.
So, maybe be we should change the timeout value from 120(default value) to 6000.

Mine test command:

export test=test/langtools/tools/javac/patterns/Exhaustiveness.java
nproc=`nproc` ; dir="tmp-jtreg-"`basename $test .java` ; rm -rf $dir ; mkdir -p $dir ; time seq 1000 | xargs -i -n 1 -P `expr $nproc / 2` bash -c "jtreg -ea -esa -timeoutFactor:20 -v:fail,error,time,nopass -nr -w $dir/index-{} $test &> $dir/{}.log ; grep 'Test results: passed: 1' -L $dir/{}.log"


The command statistic the time elapsed testcase run:

for i in `seq 1000` ; do grep "elapsed time" index-$i/tools/javac/patterns/Exhaustiveness.jtr | tail -n 1 ; done | awk -F ':' '{print $NF}' | sort -n > time-statistics.log


[time-statistics.log](https://github.com/openjdk/jdk/files/14396886/time-statistics.log)


The CPU and memory information:

[root at iZbp1fauxu0pkmhplfguv6Z ~]# lscpu 
Architecture:        x86_64
CPU op-mode(s):      32-bit, 64-bit
Byte Order:          Little Endian
CPU(s):              32
On-line CPU(s) list: 0-31
Thread(s) per core:  2
Core(s) per socket:  16
Socket(s):           1
NUMA node(s):        1
Vendor ID:           GenuineIntel
BIOS Vendor ID:      Alibaba Cloud
CPU family:          6
Model:               106
Model name:          Intel(R) Xeon(R) Platinum 8369B CPU @ 2.70GHz
BIOS Model name:     pc-i440fx-2.1
Stepping:            6
CPU MHz:             3500.041
BogoMIPS:            5399.99
Hypervisor vendor:   KVM
Virtualization type: full
L1d cache:           48K
L1i cache:           32K
L2 cache:            1280K
L3 cache:            49152K
NUMA node0 CPU(s):   0-31
Flags:               fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ss ht syscall nx pdpe1gb rdtscp lm constant_tsc rep_good nopl nonstop_tsc cpuid aperfmperf tsc_known_freq pni pclmulqdq monitor ssse3 fma cx16 pcid sse4_1 sse4_2 x2apic movbe popcnt aes xsave avx f16c rdrand hypervisor lahf_lm abm 3dnowprefetch cpuid_fault invpcid_single ibrs_enhanced fsgsbase tsc_adjust bmi1 avx2 smep bmi2 erms invpcid avx512f avx512dq rdseed adx smap avx512ifma clflushopt clwb avx512cd sha_ni avx512bw avx512vl xsaveopt xsavec xgetbv1 xsaves wbnoinvd arat avx512vbmi pku ospke avx512_vbmi2 gfni vaes vpclmulqdq avx512_vnni avx512_bitalg avx512_vpopcntdq rdpid fsrm arch_capabilities
[root at iZbp1fauxu0pkmhplfguv6Z ~]# free -h
              total        used        free      shared  buff/cache   available
Mem:           60Gi       2.8Gi        37Gi        21Mi        20Gi        57Gi
Swap:            0B          0B          0B

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

Commit messages:
 - 8326616: tools/javac/patterns/Exhaustiveness.java intermittently Timeout signalled after 480 seconds

Changes: https://git.openjdk.org/jdk/pull/17998/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=17998&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8326616
  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/17998.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/17998/head:pull/17998

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

From davidalayachew at gmail.com  Sun Feb 25 20:53:17 2024
From: davidalayachew at gmail.com (David Alayachew)
Date: Sun, 25 Feb 2024 15:53:17 -0500
Subject: For JEP 330/458, is there anyway to separate output of
 compilation vs run?
In-Reply-To: <CAA9v-_NvZhHn6SFp0Ex1GwdKXFyctpQaHJht1j4gY4hfk-J21g@mail.gmail.com>
References: <CAA9v-_NvZhHn6SFp0Ex1GwdKXFyctpQaHJht1j4gY4hfk-J21g@mail.gmail.com>
Message-ID: <CAA9v-_O5J==C7eRpe_Q+QXv-aNcMCEXysdrr7d9BnWgtQ-=2CA@mail.gmail.com>

I think I answered half of my question.

It apoears that the way to do anything programmatically in Java is via
ProcessBuilder (in the worst case), and then a handful of tools (jar,
jlink, jpackage, etc.) have dedicated modules in the standard library
provided via a ToolPprpvider that allow you to get a slightly more
ergonomic grasp of the tool. Once you have that, executing the tasks
programmatically is not hard.

However, I don't see how to separate the compile text from the runtime
text. Is that just something I miss out on by otpting into this feature? If
so, I accept that, but would appreciate some confirmation so that I know
that this is a dead end.



On Sat, Feb 24, 2024, 1:52?AM David Alayachew <davidalayachew at gmail.com>
wrote:

> Hello Compiler/Amber Dev Team,
>
> For JEP 330 and 458 (Running Single and Multi file source code programs),
> is there any way to separate the output of compilation from the output of
> the run?
>
> And as a side question, how would one go about executing single/multi file
> source code programs programmatically?
>
> Thank you for your time and help!
> David Alayachew
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/compiler-dev/attachments/20240225/426461b7/attachment.htm>

From dholmes at openjdk.org  Sun Feb 25 22:15:53 2024
From: dholmes at openjdk.org (David Holmes)
Date: Sun, 25 Feb 2024 22:15:53 GMT
Subject: RFR: 8326616: tools/javac/patterns/Exhaustiveness.java
 intermittently Timeout signalled after 480 seconds
In-Reply-To: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
References: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
Message-ID: <Sqh1o8JnfVugsl8x7nZqkK3_-ipUC4T8dVnbbSXFz6Q=.23599269-80d7-4c75-9432-6973d9d0fffa@github.com>

On Sun, 25 Feb 2024 16:02:59 GMT, SendaoYan <syan at openjdk.org> wrote:

> 15 times test exaust more than 5000 seconds.

That needs investigation, not just an increase in the timeout value.

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

PR Comment: https://git.openjdk.org/jdk/pull/17998#issuecomment-1963078687

From syan at openjdk.org  Mon Feb 26 01:43:52 2024
From: syan at openjdk.org (SendaoYan)
Date: Mon, 26 Feb 2024 01:43:52 GMT
Subject: RFR: 8326616: tools/javac/patterns/Exhaustiveness.java
 intermittently Timeout signalled after 480 seconds
In-Reply-To: <Sqh1o8JnfVugsl8x7nZqkK3_-ipUC4T8dVnbbSXFz6Q=.23599269-80d7-4c75-9432-6973d9d0fffa@github.com>
References: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
 <Sqh1o8JnfVugsl8x7nZqkK3_-ipUC4T8dVnbbSXFz6Q=.23599269-80d7-4c75-9432-6973d9d0fffa@github.com>
Message-ID: <S1wwfloHudBZvn9RtDat9oDBIA4Pm0Q11wjBwIEPm2Y=.5595629e-9740-4885-a074-f8eb6d5fda75@github.com>

On Sun, 25 Feb 2024 22:13:09 GMT, David Holmes <dholmes at openjdk.org> wrote:

> > 15 times test exaust more than 5000 seconds.
> 
> That needs investigation, not just an increase in the timeout value.

Before the intermittently timeout failure been investigated and resolved, should we problem list this testcase.

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

PR Comment: https://git.openjdk.org/jdk/pull/17998#issuecomment-1963173666

From asotona at openjdk.org  Mon Feb 26 11:08:58 2024
From: asotona at openjdk.org (Adam Sotona)
Date: Mon, 26 Feb 2024 11:08:58 GMT
Subject: RFR: 8323707: Adjust Classfile API's type arg model to better
 represent the embodied type [v3]
In-Reply-To: <NAB5piZWVQzqTDA-ge3wz3OsPq4l7qOQAqlVGz9bLq0=.d7708369-2acb-4dc4-869d-78ffc8219601@github.com>
References: <MHOvwnWcnocbfiiIdkzyqB6qdt-f2HwiaTurds0p3Pg=.cda1d910-6ef4-4577-a539-10a959adcd1f@github.com>
 <NAB5piZWVQzqTDA-ge3wz3OsPq4l7qOQAqlVGz9bLq0=.d7708369-2acb-4dc4-869d-78ffc8219601@github.com>
Message-ID: <3xSbNSq-ZXfUrHAbrv6JVM1j4ms61LNamHJaC5Mv6aM=.26ef39cb-51b3-4b59-afec-e3413d6ad94d@github.com>

On Thu, 22 Feb 2024 05:38:19 GMT, Chen Liang <liach at openjdk.org> wrote:

>> API changes as discussed on the mailing list: https://mail.openjdk.org/pipermail/classfile-api-dev/2023-November/000419.html
>> 
>> Additional questions:
>> 1. Whether to rename `WildcardIndicator.DEFAULT` to `NONE`
>
> Chen Liang has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 11 commits:
> 
>  - Rename no wildcard indicator, improve docs slightly
>  - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
>  - Merge branch 'master' into fix/typearg-model
>  - redundant line
>  - Fix a test in langtools, copyright year
>  - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
>  - Implementation cleanup, test update
>  - Merge branch 'master' into fix/typearg-model
>  - Formatting
>  - Nuke signatureString and fix test fialure from bad cast
>  - ... and 1 more: https://git.openjdk.org/jdk/compare/0bcece99...62d25642

I would consider it for 2nd preview.
Please go ahead and propose the CSR.

test/jdk/jdk/classfile/SignaturesTest.java line 188:

> 186:         var arrayListSig = sig.superclassSignature(); // ArrayList
> 187:         var arrayListTypeArg = (TypeArg.Bounded) arrayListSig.typeArgs().getFirst(); // Outer<String>.Inner<Long>
> 188:         assertEquals(TypeArg.Bounded.WildcardIndicator.DEFAULT, arrayListTypeArg.wildcardIndicator());

Suggestion:

        assertEquals(TypeArg.Bounded.WildcardIndicator.NONE, arrayListTypeArg.wildcardIndicator());

test/langtools/tools/javap/classfile/6888367/T6888367.java line 320:

> 318:                     case EXTENDS -> "W{e," + print(b.boundType()) + "}";
> 319:                     case SUPER -> "W{s," + print(b.boundType()) + "}";
> 320:                     case DEFAULT -> print(b.boundType());

Suggestion:

                    case NONE -> print(b.boundType());

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

PR Review: https://git.openjdk.org/jdk/pull/16517#pullrequestreview-1900572367
PR Review Comment: https://git.openjdk.org/jdk/pull/16517#discussion_r1502422372
PR Review Comment: https://git.openjdk.org/jdk/pull/16517#discussion_r1502423113

From liach at openjdk.org  Mon Feb 26 17:48:53 2024
From: liach at openjdk.org (Chen Liang)
Date: Mon, 26 Feb 2024 17:48:53 GMT
Subject: RFR: 8323707: Adjust Classfile API's type arg model to better
 represent the embodied type [v4]
In-Reply-To: <MHOvwnWcnocbfiiIdkzyqB6qdt-f2HwiaTurds0p3Pg=.cda1d910-6ef4-4577-a539-10a959adcd1f@github.com>
References: <MHOvwnWcnocbfiiIdkzyqB6qdt-f2HwiaTurds0p3Pg=.cda1d910-6ef4-4577-a539-10a959adcd1f@github.com>
Message-ID: <1obW1-l1wFpTjbAlnhXqTlgr8i89LStvH8SmhqhniC0=.bf0763f6-bfb3-459b-aed1-a23835226615@github.com>

> API changes as discussed on the mailing list: https://mail.openjdk.org/pipermail/classfile-api-dev/2023-November/000419.html
> 
> Additional questions:
> 1. Whether to rename `WildcardIndicator.DEFAULT` to `NONE`

Chen Liang has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 13 commits:

 - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
 - Missed renaming in tests, thanks to Adam Sotona
   
   Co-authored-by: Adam Sotona <10807609+asotona at users.noreply.github.com>
 - Rename no wildcard indicator, improve docs slightly
 - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
 - Merge branch 'master' into fix/typearg-model
 - redundant line
 - Fix a test in langtools, copyright year
 - Merge branch 'master' of https://github.com/openjdk/jdk into fix/typearg-model
 - Implementation cleanup, test update
 - Merge branch 'master' into fix/typearg-model
 - ... and 3 more: https://git.openjdk.org/jdk/compare/f62b5789...839efabd

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

Changes: https://git.openjdk.org/jdk/pull/16517/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16517&range=03
  Stats: 132 lines in 6 files changed: 49 ins; 32 del; 51 mod
  Patch: https://git.openjdk.org/jdk/pull/16517.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/16517/head:pull/16517

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

From dholmes at openjdk.org  Tue Feb 27 03:06:42 2024
From: dholmes at openjdk.org (David Holmes)
Date: Tue, 27 Feb 2024 03:06:42 GMT
Subject: RFR: 8326616: tools/javac/patterns/Exhaustiveness.java
 intermittently Timeout signalled after 480 seconds
In-Reply-To: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
References: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
Message-ID: <k0QQbN_LTCs5BSQOoal0cFutGH7yLjrL39epEb2N89g=.ce650f4d-8e08-4984-b998-a770d988de91@github.com>

On Sun, 25 Feb 2024 16:02:59 GMT, SendaoYan <syan at openjdk.org> wrote:

> The testcase tools/javac/patterns/Exhaustiveness.java intermittently timeout after [8325215](https://bugs.openjdk.org/browse/JDK-8325215).
> 
> I change the timeout value from 120(default value) to 300 locally, and set timeoutFactor to 20, then run this testcase 1000 times, use the concurrecy 16(the half of the nproc).
> The test result show that, 90% of the test run finish in 20 seconds, but 15 times test exaust more than 5000 seconds.
> So, maybe be we should change the timeout value from 120(default value) to 6000.
> 
> Mine test command:
> 
> export test=test/langtools/tools/javac/patterns/Exhaustiveness.java
> nproc=`nproc` ; dir="tmp-jtreg-"`basename $test .java` ; rm -rf $dir ; mkdir -p $dir ; time seq 1000 | xargs -i -n 1 -P `expr $nproc / 2` bash -c "jtreg -ea -esa -timeoutFactor:20 -v:fail,error,time,nopass -nr -w $dir/index-{} $test &> $dir/{}.log ; grep 'Test results: passed: 1' -L $dir/{}.log"
> 
> 
> The command statistic the time elapsed testcase run:
> 
> for i in `seq 1000` ; do grep "elapsed time" index-$i/tools/javac/patterns/Exhaustiveness.jtr | tail -n 1 ; done | awk -F ':' '{print $NF}' | sort -n > time-statistics.log
> 
> 
> [time-statistics.log](https://github.com/openjdk/jdk/files/14396886/time-statistics.log)
> 
> 
> The CPU and memory information:
> 
> [root at iZbp1fauxu0pkmhplfguv6Z ~]# lscpu 
> Architecture:        x86_64
> CPU op-mode(s):      32-bit, 64-bit
> Byte Order:          Little Endian
> CPU(s):              32
> On-line CPU(s) list: 0-31
> Thread(s) per core:  2
> Core(s) per socket:  16
> Socket(s):           1
> NUMA node(s):        1
> Vendor ID:           GenuineIntel
> BIOS Vendor ID:      Alibaba Cloud
> CPU family:          6
> Model:               106
> Model name:          Intel(R) Xeon(R) Platinum 8369B CPU @ 2.70GHz
> BIOS Model name:     pc-i440fx-2.1
> Stepping:            6
> CPU MHz:             3500.041
> BogoMIPS:            5399.99
> Hypervisor vendor:   KVM
> Virtualization type: full
> L1d cache:           48K
> L1i cache:           32K
> L2 cache:            1280K
> L3 cache:            49152K
> NUMA node0 CPU(s):   0-31
> Flags:               fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ss ht syscall nx pdpe1gb rdtscp lm constant_tsc rep_good nopl nonstop_tsc cpuid aperfmperf tsc_known_freq pni pclmulqdq monitor ssse3 fma cx16 pcid sse4_1 sse4_2 x2apic movbe popcnt aes xsave avx f16c rdrand hypervisor lahf_lm abm 3dnowprefetch cpuid_fault invpcid_single ibrs_enhanced fsgsbase tsc_adjust bmi1 avx2 smep bmi2 erms invpcid avx512f avx512dq rds...

Yes please ProblemList this.

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

PR Comment: https://git.openjdk.org/jdk/pull/17998#issuecomment-1965703573

From syan at openjdk.org  Tue Feb 27 07:23:52 2024
From: syan at openjdk.org (SendaoYan)
Date: Tue, 27 Feb 2024 07:23:52 GMT
Subject: RFR: 8326726: Problem list Exhaustiveness.java due to 8326616 [v2]
In-Reply-To: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
References: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
Message-ID: <7J4AtzLPYHrxYmOFPiVobHzBwjIrzdm4NWzaPYlKg8A=.cb36ba25-c1b1-4f9b-81e7-b5e9927d09e9@github.com>

> The testcase tools/javac/patterns/Exhaustiveness.java intermittently timeout after [8325215](https://bugs.openjdk.org/browse/JDK-8325215).
> 
> I change the timeout value from 120(default value) to 300 locally, and set timeoutFactor to 20, then run this testcase 1000 times, use the concurrecy 16(the half of the nproc).
> The test result show that, 90% of the test run finish in 20 seconds, but 15 times test exaust more than 5000 seconds.
> So, maybe be we should change the timeout value from 120(default value) to 6000.
> 
> Mine test command:
> 
> export test=test/langtools/tools/javac/patterns/Exhaustiveness.java
> nproc=`nproc` ; dir="tmp-jtreg-"`basename $test .java` ; rm -rf $dir ; mkdir -p $dir ; time seq 1000 | xargs -i -n 1 -P `expr $nproc / 2` bash -c "jtreg -ea -esa -timeoutFactor:20 -v:fail,error,time,nopass -nr -w $dir/index-{} $test &> $dir/{}.log ; grep 'Test results: passed: 1' -L $dir/{}.log"
> 
> 
> The command statistic the time elapsed testcase run:
> 
> for i in `seq 1000` ; do grep "elapsed time" index-$i/tools/javac/patterns/Exhaustiveness.jtr | tail -n 1 ; done | awk -F ':' '{print $NF}' | sort -n > time-statistics.log
> 
> 
> [time-statistics.log](https://github.com/openjdk/jdk/files/14396886/time-statistics.log)
> 
> 
> The CPU and memory information:
> 
> [root at iZbp1fauxu0pkmhplfguv6Z ~]# lscpu 
> Architecture:        x86_64
> CPU op-mode(s):      32-bit, 64-bit
> Byte Order:          Little Endian
> CPU(s):              32
> On-line CPU(s) list: 0-31
> Thread(s) per core:  2
> Core(s) per socket:  16
> Socket(s):           1
> NUMA node(s):        1
> Vendor ID:           GenuineIntel
> BIOS Vendor ID:      Alibaba Cloud
> CPU family:          6
> Model:               106
> Model name:          Intel(R) Xeon(R) Platinum 8369B CPU @ 2.70GHz
> BIOS Model name:     pc-i440fx-2.1
> Stepping:            6
> CPU MHz:             3500.041
> BogoMIPS:            5399.99
> Hypervisor vendor:   KVM
> Virtualization type: full
> L1d cache:           48K
> L1i cache:           32K
> L2 cache:            1280K
> L3 cache:            49152K
> NUMA node0 CPU(s):   0-31
> Flags:               fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ss ht syscall nx pdpe1gb rdtscp lm constant_tsc rep_good nopl nonstop_tsc cpuid aperfmperf tsc_known_freq pni pclmulqdq monitor ssse3 fma cx16 pcid sse4_1 sse4_2 x2apic movbe popcnt aes xsave avx f16c rdrand hypervisor lahf_lm abm 3dnowprefetch cpuid_fault invpcid_single ibrs_enhanced fsgsbase tsc_adjust bmi1 avx2 smep bmi2 erms invpcid avx512f avx512dq rds...

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

 - 8326726: Problem list Exhaustiveness.java due to 8326616
   
   Signed-off-by: sendaoYan <yansendao.ysd at alibaba-inc.com>
 - 8326726: Problem list Exhaustiveness.java due to 8326616
   
   Signed-off-by: sendaoYan <yansendao.ysd at alibaba-inc.com>

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/17998/files
  - new: https://git.openjdk.org/jdk/pull/17998/files/8d4d2754..f4caab17

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=17998&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=17998&range=00-01

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

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

From syan at openjdk.org  Tue Feb 27 07:25:43 2024
From: syan at openjdk.org (SendaoYan)
Date: Tue, 27 Feb 2024 07:25:43 GMT
Subject: RFR: 8326726: Problem list Exhaustiveness.java due to 8326616
In-Reply-To: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
References: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
Message-ID: <g_6IVuqibjwDpd0gTcRJt20fggWBzbr_g-ZSA41CiQA=.41e067f6-eb8e-4173-b1b3-d394b6e720a8@github.com>

On Sun, 25 Feb 2024 16:02:59 GMT, SendaoYan <syan at openjdk.org> wrote:

> The testcase tools/javac/patterns/Exhaustiveness.java intermittently timeout after [8325215](https://bugs.openjdk.org/browse/JDK-8325215).
> 
> I change the timeout value from 120(default value) to 300 locally, and set timeoutFactor to 20, then run this testcase 1000 times, use the concurrecy 16(the half of the nproc).
> The test result show that, 90% of the test run finish in 20 seconds, but 15 times test exaust more than 5000 seconds.
> So, maybe be we should change the timeout value from 120(default value) to 6000.
> 
> Mine test command:
> 
> export test=test/langtools/tools/javac/patterns/Exhaustiveness.java
> nproc=`nproc` ; dir="tmp-jtreg-"`basename $test .java` ; rm -rf $dir ; mkdir -p $dir ; time seq 1000 | xargs -i -n 1 -P `expr $nproc / 2` bash -c "jtreg -ea -esa -timeoutFactor:20 -v:fail,error,time,nopass -nr -w $dir/index-{} $test &> $dir/{}.log ; grep 'Test results: passed: 1' -L $dir/{}.log"
> 
> 
> The command statistic the time elapsed testcase run:
> 
> for i in `seq 1000` ; do grep "elapsed time" index-$i/tools/javac/patterns/Exhaustiveness.jtr | tail -n 1 ; done | awk -F ':' '{print $NF}' | sort -n > time-statistics.log
> 
> 
> [time-statistics.log](https://github.com/openjdk/jdk/files/14396886/time-statistics.log)
> 
> 
> The CPU and memory information:
> 
> [root at iZbp1fauxu0pkmhplfguv6Z ~]# lscpu 
> Architecture:        x86_64
> CPU op-mode(s):      32-bit, 64-bit
> Byte Order:          Little Endian
> CPU(s):              32
> On-line CPU(s) list: 0-31
> Thread(s) per core:  2
> Core(s) per socket:  16
> Socket(s):           1
> NUMA node(s):        1
> Vendor ID:           GenuineIntel
> BIOS Vendor ID:      Alibaba Cloud
> CPU family:          6
> Model:               106
> Model name:          Intel(R) Xeon(R) Platinum 8369B CPU @ 2.70GHz
> BIOS Model name:     pc-i440fx-2.1
> Stepping:            6
> CPU MHz:             3500.041
> BogoMIPS:            5399.99
> Hypervisor vendor:   KVM
> Virtualization type: full
> L1d cache:           48K
> L1i cache:           32K
> L2 cache:            1280K
> L3 cache:            49152K
> NUMA node0 CPU(s):   0-31
> Flags:               fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ss ht syscall nx pdpe1gb rdtscp lm constant_tsc rep_good nopl nonstop_tsc cpuid aperfmperf tsc_known_freq pni pclmulqdq monitor ssse3 fma cx16 pcid sse4_1 sse4_2 x2apic movbe popcnt aes xsave avx f16c rdrand hypervisor lahf_lm abm 3dnowprefetch cpuid_fault invpcid_single ibrs_enhanced fsgsbase tsc_adjust bmi1 avx2 smep bmi2 erms invpcid avx512f avx512dq rds...

The testcase tools/javac/patterns/Exhaustiveness.java intermittently timeout after 8325215.

I run this testcase 1000 times, 15 times test take more than 5000 seconds, and about 50 times test take more than 1500 seconds. That needs further investigation. Before the intermittently timeout failure been investigated and resolved, should we problem list this testcase as a temporary solution.

The intermittently timeout failure was caught both in x86-64 and aarch64 platform. So the label should be generic-all

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

PR Comment: https://git.openjdk.org/jdk/pull/17998#issuecomment-1965933359

From jlahoda at openjdk.org  Tue Feb 27 12:18:52 2024
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Tue, 27 Feb 2024 12:18:52 GMT
Subject: RFR: 8326726: Problem list Exhaustiveness.java due to 8326616 [v2]
In-Reply-To: <7J4AtzLPYHrxYmOFPiVobHzBwjIrzdm4NWzaPYlKg8A=.cb36ba25-c1b1-4f9b-81e7-b5e9927d09e9@github.com>
References: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
 <7J4AtzLPYHrxYmOFPiVobHzBwjIrzdm4NWzaPYlKg8A=.cb36ba25-c1b1-4f9b-81e7-b5e9927d09e9@github.com>
Message-ID: <Z2F-Cqpue7JNe2XFeNRQaT5OTmn4lOLM8xKdOzWRlF0=.51685d68-53fc-45d6-b73c-6147957c6525@github.com>

On Tue, 27 Feb 2024 07:23:52 GMT, SendaoYan <syan at openjdk.org> wrote:

>> The testcase tools/javac/patterns/Exhaustiveness.java intermittently timeout after [8325215](https://bugs.openjdk.org/browse/JDK-8325215).
>> 
>> I change the timeout value from 120(default value) to 300 locally, and set timeoutFactor to 20, then run this testcase 1000 times, use the concurrecy 16(the half of the nproc).
>> The test result show that, 90% of the test run finish in 20 seconds, but 15 times test exaust more than 5000 seconds.
>> So, maybe be we should change the timeout value from 120(default value) to 6000.
>> 
>> Mine test command:
>> 
>> export test=test/langtools/tools/javac/patterns/Exhaustiveness.java
>> nproc=`nproc` ; dir="tmp-jtreg-"`basename $test .java` ; rm -rf $dir ; mkdir -p $dir ; time seq 1000 | xargs -i -n 1 -P `expr $nproc / 2` bash -c "jtreg -ea -esa -timeoutFactor:20 -v:fail,error,time,nopass -nr -w $dir/index-{} $test &> $dir/{}.log ; grep 'Test results: passed: 1' -L $dir/{}.log"
>> 
>> 
>> The command statistic the time elapsed testcase run:
>> 
>> for i in `seq 1000` ; do grep "elapsed time" index-$i/tools/javac/patterns/Exhaustiveness.jtr | tail -n 1 ; done | awk -F ':' '{print $NF}' | sort -n > time-statistics.log
>> 
>> 
>> [time-statistics.log](https://github.com/openjdk/jdk/files/14396886/time-statistics.log)
>> 
>> 
>> The CPU and memory information:
>> 
>> [root at iZbp1fauxu0pkmhplfguv6Z ~]# lscpu 
>> Architecture:        x86_64
>> CPU op-mode(s):      32-bit, 64-bit
>> Byte Order:          Little Endian
>> CPU(s):              32
>> On-line CPU(s) list: 0-31
>> Thread(s) per core:  2
>> Core(s) per socket:  16
>> Socket(s):           1
>> NUMA node(s):        1
>> Vendor ID:           GenuineIntel
>> BIOS Vendor ID:      Alibaba Cloud
>> CPU family:          6
>> Model:               106
>> Model name:          Intel(R) Xeon(R) Platinum 8369B CPU @ 2.70GHz
>> BIOS Model name:     pc-i440fx-2.1
>> Stepping:            6
>> CPU MHz:             3500.041
>> BogoMIPS:            5399.99
>> Hypervisor vendor:   KVM
>> Virtualization type: full
>> L1d cache:           48K
>> L1i cache:           32K
>> L2 cache:            1280K
>> L3 cache:            49152K
>> NUMA node0 CPU(s):   0-31
>> Flags:               fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ss ht syscall nx pdpe1gb rdtscp lm constant_tsc rep_good nopl nonstop_tsc cpuid aperfmperf tsc_known_freq pni pclmulqdq monitor ssse3 fma cx16 pcid sse4_1 sse4_2 x2apic movbe popcnt aes xsave avx f16c rdrand hypervisor lahf_lm abm 3dnowprefetch cpuid_fault invp...
>
> SendaoYan has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - 8326726: Problem list Exhaustiveness.java due to 8326616
>    
>    Signed-off-by: sendaoYan <yansendao.ysd at alibaba-inc.com>
>  - 8326726: Problem list Exhaustiveness.java due to 8326616
>    
>    Signed-off-by: sendaoYan <yansendao.ysd at alibaba-inc.com>

Looks reasonable. Thanks!

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

Marked as reviewed by jlahoda (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/17998#pullrequestreview-1903339821

From jjg at openjdk.org  Tue Feb 27 22:21:54 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 27 Feb 2024 22:21:54 GMT
Subject: RFR: 8326726: Problem list Exhaustiveness.java due to 8326616 [v2]
In-Reply-To: <Z2F-Cqpue7JNe2XFeNRQaT5OTmn4lOLM8xKdOzWRlF0=.51685d68-53fc-45d6-b73c-6147957c6525@github.com>
References: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
 <7J4AtzLPYHrxYmOFPiVobHzBwjIrzdm4NWzaPYlKg8A=.cb36ba25-c1b1-4f9b-81e7-b5e9927d09e9@github.com>
 <Z2F-Cqpue7JNe2XFeNRQaT5OTmn4lOLM8xKdOzWRlF0=.51685d68-53fc-45d6-b73c-6147957c6525@github.com>
Message-ID: <NZZB55nJAeOq3Ib7DBpauQ45LumH3389t_TYQt3HQXw=.45d7acff-9041-4fab-a5d5-41f6141e11af@github.com>

On Tue, 27 Feb 2024 12:16:00 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

>> SendaoYan has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - 8326726: Problem list Exhaustiveness.java due to 8326616
>>    
>>    Signed-off-by: sendaoYan <yansendao.ysd at alibaba-inc.com>
>>  - 8326726: Problem list Exhaustiveness.java due to 8326616
>>    
>>    Signed-off-by: sendaoYan <yansendao.ysd at alibaba-inc.com>
>
> Looks reasonable. Thanks!

Based on @lahodaj approval, I will sponsor this

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

PR Comment: https://git.openjdk.org/jdk/pull/17998#issuecomment-1967736747

From syan at openjdk.org  Tue Feb 27 22:21:55 2024
From: syan at openjdk.org (SendaoYan)
Date: Tue, 27 Feb 2024 22:21:55 GMT
Subject: Integrated: 8326726: Problem list Exhaustiveness.java due to 8326616
In-Reply-To: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
References: <9tC0IsdXrrHs8LcDOC1v4FXanyrG2_eSHFFZ3JuuHLk=.99a49188-4172-4e45-8212-38596717dffa@github.com>
Message-ID: <xIf4iCh2RE_QMCRqdl8VsZcnsmGh-958JwKs-mkI264=.7ea6bc33-8a9d-4627-9908-a2a632416459@github.com>

On Sun, 25 Feb 2024 16:02:59 GMT, SendaoYan <syan at openjdk.org> wrote:

> The testcase tools/javac/patterns/Exhaustiveness.java intermittently timeout after [8325215](https://bugs.openjdk.org/browse/JDK-8325215).
> 
> I change the timeout value from 120(default value) to 300 locally, and set timeoutFactor to 20, then run this testcase 1000 times, use the concurrecy 16(the half of the nproc).
> The test result show that, 90% of the test run finish in 20 seconds, but 15 times test exaust more than 5000 seconds.
> So, maybe be we should change the timeout value from 120(default value) to 6000.
> 
> Mine test command:
> 
> export test=test/langtools/tools/javac/patterns/Exhaustiveness.java
> nproc=`nproc` ; dir="tmp-jtreg-"`basename $test .java` ; rm -rf $dir ; mkdir -p $dir ; time seq 1000 | xargs -i -n 1 -P `expr $nproc / 2` bash -c "jtreg -ea -esa -timeoutFactor:20 -v:fail,error,time,nopass -nr -w $dir/index-{} $test &> $dir/{}.log ; grep 'Test results: passed: 1' -L $dir/{}.log"
> 
> 
> The command statistic the time elapsed testcase run:
> 
> for i in `seq 1000` ; do grep "elapsed time" index-$i/tools/javac/patterns/Exhaustiveness.jtr | tail -n 1 ; done | awk -F ':' '{print $NF}' | sort -n > time-statistics.log
> 
> 
> [time-statistics.log](https://github.com/openjdk/jdk/files/14396886/time-statistics.log)
> 
> 
> The CPU and memory information:
> 
> [root at iZbp1fauxu0pkmhplfguv6Z ~]# lscpu 
> Architecture:        x86_64
> CPU op-mode(s):      32-bit, 64-bit
> Byte Order:          Little Endian
> CPU(s):              32
> On-line CPU(s) list: 0-31
> Thread(s) per core:  2
> Core(s) per socket:  16
> Socket(s):           1
> NUMA node(s):        1
> Vendor ID:           GenuineIntel
> BIOS Vendor ID:      Alibaba Cloud
> CPU family:          6
> Model:               106
> Model name:          Intel(R) Xeon(R) Platinum 8369B CPU @ 2.70GHz
> BIOS Model name:     pc-i440fx-2.1
> Stepping:            6
> CPU MHz:             3500.041
> BogoMIPS:            5399.99
> Hypervisor vendor:   KVM
> Virtualization type: full
> L1d cache:           48K
> L1i cache:           32K
> L2 cache:            1280K
> L3 cache:            49152K
> NUMA node0 CPU(s):   0-31
> Flags:               fpu vme de pse tsc msr pae mce cx8 apic sep mtrr pge mca cmov pat pse36 clflush mmx fxsr sse sse2 ss ht syscall nx pdpe1gb rdtscp lm constant_tsc rep_good nopl nonstop_tsc cpuid aperfmperf tsc_known_freq pni pclmulqdq monitor ssse3 fma cx16 pcid sse4_1 sse4_2 x2apic movbe popcnt aes xsave avx f16c rdrand hypervisor lahf_lm abm 3dnowprefetch cpuid_fault invpcid_single ibrs_enhanced fsgsbase tsc_adjust bmi1 avx2 smep bmi2 erms invpcid avx512f avx512dq rds...

This pull request has now been integrated.

Changeset: 349df0a0
Author:    SendaoYan <syan at openjdk.org>
Committer: Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/349df0a0e550599cc4a9cde8bef00e138671b472
Stats:     1 line in 1 file changed: 1 ins; 0 del; 0 mod

8326726: Problem list Exhaustiveness.java due to 8326616

Reviewed-by: jlahoda

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

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

From ihse at openjdk.org  Wed Feb 28 11:32:07 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Wed, 28 Feb 2024 11:32:07 GMT
Subject: RFR: 8326947: Minimize MakeBase.gmk
Message-ID: <Zacq5On-Rnkhi-uUfL_TDbHbzDtqxe-SQ-eyL7673l8=.c40c1bc0-e490-471b-be98-a553cc51efcf@github.com>

This is part of a general "spring cleaning" of the build system, addressing old code that has bit-rotted, been subject to lava flow, or just had bad or smelly code that we've never gotten around to fix.

This particular patch tries to make MakeBase truly minimal; only including the core parts of the build system that all makefiles will need. This is now limited to essential functionality for named parameter functions, variable dependency, tool execution, logging and fixpath functionality. MakeBase still includes Utils.gmk and FileUtils.gmk, and thus "provides" this functionality as well. Separating these out as well will be the subject of a future patch.

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

Commit messages:
 - Whitespace fix
 - MakeBase.gmk should not include MakeIO.gmk anymore
 - MakeBase.gmk should not include CopyFiles.gmk anymore
 - Reorder BaseUtils.gmk to make more sense
 - Move some more functionality to BaseUtils.gmk
 - Create BaseUtils.gmk with the most basic stuff
 - Move all file stuff from Utils.gmk to FileUtils.gmk
 - Document the purpose of MakeBase
 - Move SOURCE_REVISION_TRACKER to where it is used.
 - Move timers to InitSupport where they are used
 - ... and 3 more: https://git.openjdk.org/jdk/compare/1ab6bd43...3c86bcfe

Changes: https://git.openjdk.org/jdk/pull/18041/files
 Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18041&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8326947
  Stats: 1099 lines in 43 files changed: 607 ins; 480 del; 12 mod
  Patch: https://git.openjdk.org/jdk/pull/18041.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18041/head:pull/18041

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

From ihse at openjdk.org  Wed Feb 28 11:32:07 2024
From: ihse at openjdk.org (Magnus Ihse Bursie)
Date: Wed, 28 Feb 2024 11:32:07 GMT
Subject: RFR: 8326947: Minimize MakeBase.gmk
In-Reply-To: <Zacq5On-Rnkhi-uUfL_TDbHbzDtqxe-SQ-eyL7673l8=.c40c1bc0-e490-471b-be98-a553cc51efcf@github.com>
References: <Zacq5On-Rnkhi-uUfL_TDbHbzDtqxe-SQ-eyL7673l8=.c40c1bc0-e490-471b-be98-a553cc51efcf@github.com>
Message-ID: <XrkJxvP9huixhz-3aO3N_KXMZ4tIO2pEFFb8tqzZsr4=.9e8478a6-31f3-439e-80b7-9a28907aae8f@github.com>

On Wed, 28 Feb 2024 11:24:06 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

> This is part of a general "spring cleaning" of the build system, addressing old code that has bit-rotted, been subject to lava flow, or just had bad or smelly code that we've never gotten around to fix.
> 
> This particular patch tries to make MakeBase truly minimal; only including the core parts of the build system that all makefiles will need. This is now limited to essential functionality for named parameter functions, variable dependency, tool execution, logging and fixpath functionality. MakeBase still includes Utils.gmk and FileUtils.gmk, and thus "provides" this functionality as well. Separating these out as well will be the subject of a future patch.

I have verified using `COMPARE_BUILD` on windows-x64, linux-x64, linux-aarch64, macosx-x64 and macosx-aarch64 that there are no differences in the resulting build.

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

PR Comment: https://git.openjdk.org/jdk/pull/18041#issuecomment-1968778732

From hannesw at openjdk.org  Wed Feb 28 14:49:06 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 28 Feb 2024 14:49:06 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v43]
In-Reply-To: <gwFu9c4-Y_zksoJ1Tu4eJ-rJm0DEf2EYCZj2OVVIrUE=.9e9533b9-751e-4dfd-890e-4dc48c3399ea@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <gwFu9c4-Y_zksoJ1Tu4eJ-rJm0DEf2EYCZj2OVVIrUE=.9e9533b9-751e-4dfd-890e-4dc48c3399ea@github.com>
Message-ID: <cX4hEqIEUFIhx-HUjtmy5yS_-vThVYQLI7fSzsrA7Rg=.5eebc6f6-bea6-477d-a900-069afb732ab5@github.com>

On Fri, 23 Feb 2024 22:27:43 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Refactor most of TestMarkdown.java into separate tests, grouped by functionality

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1380:

> 1378: 
> 1379:         var useMarkdown = trees.stream().anyMatch(t -> t.getKind() == Kind.MARKDOWN);
> 1380:         var markdownHandler = useMarkdown ? new MarkdownHandler(element) : null;

The `MarkdownHandler` and `HeadingNodeRenderer` classes must become aware of the current `TagletWriter.Context`.  That's because headings and other block tags should only be generated if `TagletWriter.Context.isFirstSentence` is `false`.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1506084275

From hannesw at openjdk.org  Wed Feb 28 15:28:04 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 28 Feb 2024 15:28:04 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v43]
In-Reply-To: <gwFu9c4-Y_zksoJ1Tu4eJ-rJm0DEf2EYCZj2OVVIrUE=.9e9533b9-751e-4dfd-890e-4dc48c3399ea@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <gwFu9c4-Y_zksoJ1Tu4eJ-rJm0DEf2EYCZj2OVVIrUE=.9e9533b9-751e-4dfd-890e-4dc48c3399ea@github.com>
Message-ID: <-Nw3xUoSRDHXjRzleG1SaaZjtRcGWAS9Oi9pdhX_GfQ=.63b2610a-f733-4421-a17b-21dd26accd51@github.com>

On Fri, 23 Feb 2024 22:27:43 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Refactor most of TestMarkdown.java into separate tests, grouped by functionality

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1733:

> 1731:             return false;
> 1732:         }
> 1733: 

The two methods below and some other methods in this class have too much indentation.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1506145051

From hannesw at openjdk.org  Wed Feb 28 15:58:02 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Wed, 28 Feb 2024 15:58:02 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v43]
In-Reply-To: <gwFu9c4-Y_zksoJ1Tu4eJ-rJm0DEf2EYCZj2OVVIrUE=.9e9533b9-751e-4dfd-890e-4dc48c3399ea@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <gwFu9c4-Y_zksoJ1Tu4eJ-rJm0DEf2EYCZj2OVVIrUE=.9e9533b9-751e-4dfd-890e-4dc48c3399ea@github.com>
Message-ID: <x_vvLqu7UsQHMlQCynTzD0ddhHvg2glkHXblCujUCrQ=.62b4b088-e12c-45fc-b974-bd83812d0c9e@github.com>

On Fri, 23 Feb 2024 22:27:43 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a patch to add support for Markdown syntax in documentation comments, as described in the associated JEP.
>> 
>> Notable features:
>> 
>> * support for `///` documentation comments in `JavaTokenizer`
>> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` library
>> * updates to `DocCommentParser` to treat `///` comments as Markdown
>> * updates to the standard doclet to render Markdown comments in HTML
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Refactor most of TestMarkdown.java into separate tests, grouped by functionality

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1601:

> 1599:                         : eKind != ElementKind.OTHER ? 1   // module, package, class, interface
> 1600:                         : 0; // doc file
> 1601:                 return "h" + Math.min(heading.getLevel() + offset, 6);

I really like that we adapt the heading level to the current context, but I notice that the code kind of expects `h1` headings to be used everywhere, and "punishes" use of contextually correct headings by generating smaller headings. Maybe it would be more educational to only adjust the level if it needs adjusting?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1506190847

From jjg at openjdk.org  Wed Feb 28 17:15:07 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 28 Feb 2024 17:15:07 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v43]
In-Reply-To: <x_vvLqu7UsQHMlQCynTzD0ddhHvg2glkHXblCujUCrQ=.62b4b088-e12c-45fc-b974-bd83812d0c9e@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <gwFu9c4-Y_zksoJ1Tu4eJ-rJm0DEf2EYCZj2OVVIrUE=.9e9533b9-751e-4dfd-890e-4dc48c3399ea@github.com>
 <x_vvLqu7UsQHMlQCynTzD0ddhHvg2glkHXblCujUCrQ=.62b4b088-e12c-45fc-b974-bd83812d0c9e@github.com>
Message-ID: <k4yPloMAtTmkzn54pzlVhTpBRq6dVGJxmFg1YVgAQVk=.5089ccc6-c675-4933-a8e8-633d6162984d@github.com>

On Wed, 28 Feb 2024 15:54:38 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

>> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Refactor most of TestMarkdown.java into separate tests, grouped by functionality
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1601:
> 
>> 1599:                         : eKind != ElementKind.OTHER ? 1   // module, package, class, interface
>> 1600:                         : 0; // doc file
>> 1601:                 return "h" + Math.min(heading.getLevel() + offset, 6);
> 
> I really like that we adapt the heading level to the current context, but I notice that the code kind of expects `h1` headings to be used everywhere, and "punishes" use of contextually correct headings by generating smaller headings. Maybe it would be more educational to only adjust the level if it needs adjusting?

Setext headings only come in "level 1" and "level 2" flavors.
And, at the time the renderer sees the AST, the difference between ATX and setext headings is erased. They're just "headings".

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1506307115

From hannesw at openjdk.org  Thu Feb 29 11:43:04 2024
From: hannesw at openjdk.org (Hannes =?UTF-8?B?V2FsbG7DtmZlcg==?=)
Date: Thu, 29 Feb 2024 11:43:04 GMT
Subject: RFR: JDK-8298405: Support Markdown in Documentation Comments [v43]
In-Reply-To: <k4yPloMAtTmkzn54pzlVhTpBRq6dVGJxmFg1YVgAQVk=.5089ccc6-c675-4933-a8e8-633d6162984d@github.com>
References: <G_kdxk2HIXWT_S_THP0ZqOvYMNMmx-nmje2psbsVc38=.1af4b86f-02a0-4d5d-9435-a674af4701ee@github.com>
 <gwFu9c4-Y_zksoJ1Tu4eJ-rJm0DEf2EYCZj2OVVIrUE=.9e9533b9-751e-4dfd-890e-4dc48c3399ea@github.com>
 <x_vvLqu7UsQHMlQCynTzD0ddhHvg2glkHXblCujUCrQ=.62b4b088-e12c-45fc-b974-bd83812d0c9e@github.com>
 <k4yPloMAtTmkzn54pzlVhTpBRq6dVGJxmFg1YVgAQVk=.5089ccc6-c675-4933-a8e8-633d6162984d@github.com>
Message-ID: <GBCHPcPnrmMHP5Lv6OmpYTZYNv1mUDoSa_0LL0RNbyg=.1bdb3a33-ed23-470a-8157-a2c142a65712@github.com>

On Wed, 28 Feb 2024 17:12:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 1601:
>> 
>>> 1599:                         : eKind != ElementKind.OTHER ? 1   // module, package, class, interface
>>> 1600:                         : 0; // doc file
>>> 1601:                 return "h" + Math.min(heading.getLevel() + offset, 6);
>> 
>> I really like that we adapt the heading level to the current context, but I notice that the code kind of expects `h1` headings to be used everywhere, and "punishes" use of contextually correct headings by generating smaller headings. Maybe it would be more educational to only adjust the level if it needs adjusting?
>
> Setext headings only come in "level 1" and "level 2" flavors.
> And, at the time the renderer sees the AST, the difference between ATX and setext headings is erased. They're just "headings".
> 
> I also think it is better to have a simple rule than an "adaptive" rule.  If you start doing a more complex rule, you have to consider the effect on subheadings as well.

I suspected it was about the limited range of Setext headings. Yesterday my proposal was intentionally vague, but thinking about this again I think we should actually do the simplest and least intrusive thing possible:

    // minLevel is 4 for members, 2 for page-level elements, 1 for doc files
    "h" + Math.max(heading.getLevel(), minLevel);

This arguably generates the correct heading for most simple use cases. What it doesn't do is to translate whole hierarchies of headings, but I would argue that few people people need this and those who do should figure out the rules and use the correct ATX headings.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1507439797