From jlahoda at openjdk.org  Fri Sep 19 17:53:17 2025
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Fri, 19 Sep 2025 17:53:17 GMT
Subject: RFR: 7904080: APIDiff does not detect javadoc (and changes to javadoc)
 for methods with varargs
Message-ID: <uvgtc0X9nsvvqv75pevSlLE8nbUtznkUJdeB9A9WUVE=.1d5a6073-8de8-4c29-bf1c-929cb192a2ed@github.com>

The keys in the HTML Javadoc for methods with varargs use `...`, but the signatures generated by API Diff use `[]`, so API Diff cannot find the appropriate javadoc in the HTML for vararg methods, which leads to a failure to show the differences in the javadoc for such methods.

There are multiple possible ways to fix that, but the proposal herein is to try to normalize the keys to use `[]` while reading the HTML.

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

Commit messages:
 - 7904080: APIDiff does not detect javadoc (and changes to javadoc) for methods with varargs

Changes: https://git.openjdk.org/apidiff/pull/31/files
  Webrev: https://webrevs.openjdk.org/?repo=apidiff&pr=31&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7904080
  Stats: 10 lines in 2 files changed: 8 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/apidiff/pull/31.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/31/head:pull/31

PR: https://git.openjdk.org/apidiff/pull/31

From jlahoda at openjdk.org  Mon Sep 22 15:47:49 2025
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Mon, 22 Sep 2025 15:47:49 GMT
Subject: RFR: 7904082: The UI for API Diff could be improved
Message-ID: <XN4ewbE0nF6tDuW9xCQMwuIU3_JYr6FgTCubLDQoq9Y=.f2f73037-e1eb-4ce6-bda8-85e5c73c048d@github.com>

This PR intends to improve the result of API diff in a few ways:
- in the list of updated elements, using green for elements that were added (instead of elements that are unchanged), and red for removed elements. At least in cases two variants of an API are compared.
- making added/removed elements more prominent by also coloring the signature lines
- hiding unchanged elements by default.

An example diff that is produced before this patch:
https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/before/
after this patch:
https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/after/

Please let me know what you think. I'll see if I can reasonably add some tests for this functionality.

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

Commit messages:
 - Cleanup.
 - Fixes.
 - Prototype of dynamic hiding of unchanged elements.
 - More prominent coloring of added/removed elements.
 - Changing stylesheet
 - Hide unchanged.

Changes: https://git.openjdk.org/apidiff/pull/32/files
  Webrev: https://webrevs.openjdk.org/?repo=apidiff&pr=32&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7904082
  Stats: 249 lines in 4 files changed: 161 ins; 35 del; 53 mod
  Patch: https://git.openjdk.org/apidiff/pull/32.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/32/head:pull/32

PR: https://git.openjdk.org/apidiff/pull/32

From cstein at openjdk.org  Tue Sep 23 12:16:21 2025
From: cstein at openjdk.org (Christian Stein)
Date: Tue, 23 Sep 2025 12:16:21 GMT
Subject: RFR: 7904080: APIDiff does not detect javadoc (and changes to
 javadoc) for methods with varargs
In-Reply-To: <uvgtc0X9nsvvqv75pevSlLE8nbUtznkUJdeB9A9WUVE=.1d5a6073-8de8-4c29-bf1c-929cb192a2ed@github.com>
References: <uvgtc0X9nsvvqv75pevSlLE8nbUtznkUJdeB9A9WUVE=.1d5a6073-8de8-4c29-bf1c-929cb192a2ed@github.com>
Message-ID: <Et9EvPRYpgtEqcfYHgJV5sUADS_RdtlQOA66kCNnCVw=.1a94de69-07f4-4e10-9173-e182ea417e62@github.com>

On Fri, 19 Sep 2025 17:46:57 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> The keys in the HTML Javadoc for methods with varargs use `...`, but the signatures generated by API Diff use `[]`, so API Diff cannot find the appropriate javadoc in the HTML for vararg methods, which leads to a failure to show the differences in the javadoc for such methods.
> 
> There are multiple possible ways to fix that, but the proposal herein is to try to normalize the keys to use `[]` while reading the HTML.

Marked as reviewed by cstein (Reviewer).

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

PR Review: https://git.openjdk.org/apidiff/pull/31#pullrequestreview-3257694638

From iris at openjdk.org  Tue Sep 23 16:14:27 2025
From: iris at openjdk.org (Iris Clark)
Date: Tue, 23 Sep 2025 16:14:27 GMT
Subject: RFR: 7904080: APIDiff does not detect javadoc (and changes to
 javadoc) for methods with varargs
In-Reply-To: <uvgtc0X9nsvvqv75pevSlLE8nbUtznkUJdeB9A9WUVE=.1d5a6073-8de8-4c29-bf1c-929cb192a2ed@github.com>
References: <uvgtc0X9nsvvqv75pevSlLE8nbUtznkUJdeB9A9WUVE=.1d5a6073-8de8-4c29-bf1c-929cb192a2ed@github.com>
Message-ID: <g05sFI5kVAtWQeKzADRXy-O08BwuitOje-5NIpha-8s=.ceddb0d3-e8d6-45e5-b830-312a27a7ac02@github.com>

On Fri, 19 Sep 2025 17:46:57 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> The keys in the HTML Javadoc for methods with varargs use `...`, but the signatures generated by API Diff use `[]`, so API Diff cannot find the appropriate javadoc in the HTML for vararg methods, which leads to a failure to show the differences in the javadoc for such methods.
> 
> There are multiple possible ways to fix that, but the proposal herein is to try to normalize the keys to use `[]` while reading the HTML.

Thanks for fixing this!

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

Marked as reviewed by iris (Reviewer).

PR Review: https://git.openjdk.org/apidiff/pull/31#pullrequestreview-3258741955

From iris at openjdk.org  Tue Sep 23 17:52:51 2025
From: iris at openjdk.org (Iris Clark)
Date: Tue, 23 Sep 2025 17:52:51 GMT
Subject: RFR: 7904082: The UI for API Diff could be improved
In-Reply-To: <XN4ewbE0nF6tDuW9xCQMwuIU3_JYr6FgTCubLDQoq9Y=.f2f73037-e1eb-4ce6-bda8-85e5c73c048d@github.com>
References: <XN4ewbE0nF6tDuW9xCQMwuIU3_JYr6FgTCubLDQoq9Y=.f2f73037-e1eb-4ce6-bda8-85e5c73c048d@github.com>
Message-ID: <HdtyY1jCIZm4mkARYJme1lstBm40JKAPBsIBq5dgA8k=.51308b2f-7472-4480-bad7-cd734f06cb2c@github.com>

On Mon, 22 Sep 2025 15:41:29 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> This PR intends to improve the result of API diff in a few ways:
> - in the list of updated elements, using green for elements that were added (instead of elements that are unchanged), and red for removed elements. At least in cases two variants of an API are compared.
> - making added/removed elements more prominent by also coloring the signature lines
> - hiding unchanged elements by default.
> 
> An example diff that is produced before this patch:
> https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/before/
> after this patch:
> https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/after/
> 
> Please let me know what you think. I'll see if I can reasonably add some tests for this functionality.

Thanks for working on apidiff!

Can you also provide a an example of the "after" for the case when unchanged elements are included?  (That's what I'd need to use for the Platform JSR Annex 2 (e.g. https://cr.openjdk.org/~iris/se/25/latestSpec/apidiffs/index.html).). I think if you're changing the default, there's probably a corresponding change you'll need to make in src/share/doc/apidiff.md, which is also published here: https://openjdk.org/projects/code-tools/apidiff/apidiff.html.

In the list of updated elements, the background for the "!=" is now appears purple-y grey (formerly pinkish) and the "!=" character itself is red (unchanged, I think).  I think this combination isn't as easy to parse as the former,  Perhaps it needs more context to appreciate?

The change in SourceCodeAnalysis.SnippetWrapper which adds the background color for the notes "Only in baseline; not in: demo" and "Only in: demo; not in: demo" looks good.  (I noticed that there's a typo in report/html/resources/report.properties, line 126 "not i" should be "not in".)

I'm not sure I'm finding an example of coloring of the signature lines.  Let me know which elements I should be looking at for the comparison.

Thanks again for all of your work to improve apidiff!

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

PR Comment: https://git.openjdk.org/apidiff/pull/32#issuecomment-3324992007

From jlahoda at openjdk.org  Wed Sep 24 08:15:37 2025
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Wed, 24 Sep 2025 08:15:37 GMT
Subject: Integrated: 7904080: APIDiff does not detect javadoc (and changes to
 javadoc) for methods with varargs
In-Reply-To: <uvgtc0X9nsvvqv75pevSlLE8nbUtznkUJdeB9A9WUVE=.1d5a6073-8de8-4c29-bf1c-929cb192a2ed@github.com>
References: <uvgtc0X9nsvvqv75pevSlLE8nbUtznkUJdeB9A9WUVE=.1d5a6073-8de8-4c29-bf1c-929cb192a2ed@github.com>
Message-ID: <tI-AsXvjOlvn_7TnXNxIflwfYvu7EUOUpISKR8p5Q94=.cc2cfbde-d732-482d-9a34-6cc2d763dea4@github.com>

On Fri, 19 Sep 2025 17:46:57 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> The keys in the HTML Javadoc for methods with varargs use `...`, but the signatures generated by API Diff use `[]`, so API Diff cannot find the appropriate javadoc in the HTML for vararg methods, which leads to a failure to show the differences in the javadoc for such methods.
> 
> There are multiple possible ways to fix that, but the proposal herein is to try to normalize the keys to use `[]` while reading the HTML.

This pull request has now been integrated.

Changeset: 80d071c4
Author:    Jan Lahoda <jlahoda at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/80d071c4e21be20dfcf44e6de02e6832c776a13b
Stats:     10 lines in 2 files changed: 8 ins; 0 del; 2 mod

7904080: APIDiff does not detect javadoc (and changes to javadoc) for methods with varargs

Reviewed-by: cstein, iris

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

PR: https://git.openjdk.org/apidiff/pull/31

From jlahoda at openjdk.org  Wed Sep 24 11:40:21 2025
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Wed, 24 Sep 2025 11:40:21 GMT
Subject: RFR: 7904082: The UI for API Diff could be improved [v2]
In-Reply-To: <XN4ewbE0nF6tDuW9xCQMwuIU3_JYr6FgTCubLDQoq9Y=.f2f73037-e1eb-4ce6-bda8-85e5c73c048d@github.com>
References: <XN4ewbE0nF6tDuW9xCQMwuIU3_JYr6FgTCubLDQoq9Y=.f2f73037-e1eb-4ce6-bda8-85e5c73c048d@github.com>
Message-ID: <n6AFvv9vSZVhJTFXUJRyQgGJeQA0FuEPUjyhVlv1qcg=.f440d331-9ca5-4ae3-b225-fc80a3e4a930@github.com>

> This PR intends to improve the result of API diff in a few ways:
> - in the list of updated elements, using green for elements that were added (instead of elements that are unchanged), and red for removed elements. At least in cases two variants of an API are compared.
> - making added/removed elements more prominent by also coloring the signature lines
> - hiding unchanged elements by default.
> 
> An example diff that is produced before this patch:
> https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/before/
> after this patch:
> https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/after/
> 
> Please let me know what you think. I'll see if I can reasonably add some tests for this functionality.

Jan Lahoda 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 eight additional commits since the last revision:

 - Trying to update colors
 - Merge branch 'master' into ui-tweaks
 - Cleanup.
 - Fixes.
 - Prototype of dynamic hiding of unchanged elements.
 - More prominent coloring of added/removed elements.
 - Changing stylesheet
 - Hide unchanged.

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

Changes:
  - all: https://git.openjdk.org/apidiff/pull/32/files
  - new: https://git.openjdk.org/apidiff/pull/32/files/15e9e4a3..fcfba786

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

  Stats: 23 lines in 3 files changed: 8 ins; 0 del; 15 mod
  Patch: https://git.openjdk.org/apidiff/pull/32.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/32/head:pull/32

PR: https://git.openjdk.org/apidiff/pull/32

From jlahoda at openjdk.org  Wed Sep 24 11:53:56 2025
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Wed, 24 Sep 2025 11:53:56 GMT
Subject: RFR: 7904082: The UI for API Diff could be improved [v3]
In-Reply-To: <XN4ewbE0nF6tDuW9xCQMwuIU3_JYr6FgTCubLDQoq9Y=.f2f73037-e1eb-4ce6-bda8-85e5c73c048d@github.com>
References: <XN4ewbE0nF6tDuW9xCQMwuIU3_JYr6FgTCubLDQoq9Y=.f2f73037-e1eb-4ce6-bda8-85e5c73c048d@github.com>
Message-ID: <dk880hyBHLOFP2_zs9x1cCTMPIdCj2q28ir6fcLSt8U=.8a107457-46c4-4df5-9232-cb72a7fe4d1b@github.com>

> This PR intends to improve the result of API diff in a few ways:
> - in the list of updated elements, using green for elements that were added (instead of elements that are unchanged), and red for removed elements. At least in cases two variants of an API are compared.
> - making added/removed elements more prominent by also coloring the signature lines
> - hiding unchanged elements by default.
> 
> An example diff that is produced before this patch:
> https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/before/
> after this patch:
> https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/after/
> 
> Please let me know what you think. I'll see if I can reasonably add some tests for this functionality.

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

  Fixing typo.

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

Changes:
  - all: https://git.openjdk.org/apidiff/pull/32/files
  - new: https://git.openjdk.org/apidiff/pull/32/files/fcfba786..6c795e1e

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

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

PR: https://git.openjdk.org/apidiff/pull/32

From jlahoda at openjdk.org  Wed Sep 24 11:59:32 2025
From: jlahoda at openjdk.org (Jan Lahoda)
Date: Wed, 24 Sep 2025 11:59:32 GMT
Subject: RFR: 7904082: The UI for API Diff could be improved
In-Reply-To: <HdtyY1jCIZm4mkARYJme1lstBm40JKAPBsIBq5dgA8k=.51308b2f-7472-4480-bad7-cd734f06cb2c@github.com>
References: <XN4ewbE0nF6tDuW9xCQMwuIU3_JYr6FgTCubLDQoq9Y=.f2f73037-e1eb-4ce6-bda8-85e5c73c048d@github.com>
 <HdtyY1jCIZm4mkARYJme1lstBm40JKAPBsIBq5dgA8k=.51308b2f-7472-4480-bad7-cd734f06cb2c@github.com>
Message-ID: <YpZHaERWwHLl1e_ngDnc7y4HI96ZeSy3rnH7rXNqQaU=.2ee67f5d-95b0-4eb6-8625-1a4a3d37efc3@github.com>

On Tue, 23 Sep 2025 17:49:46 GMT, Iris Clark <iris at openjdk.org> wrote:

> Thanks for working on apidiff!

Thanks for looking at the PR!

> 
> Can you also provide a an example of the "after" for the case when unchanged elements are included? (That's what I'd need to use for the Platform JSR Annex 2 (e.g. https://cr.openjdk.org/~iris/se/25/latestSpec/apidiffs/index.html).). I think if you're changing the default, there's probably a corresponding change you'll need to make in src/share/doc/apidiff.md, which is also published here: https://openjdk.org/projects/code-tools/apidiff/apidiff.html.

The diffs produced after this PR hide the unchanged elements using JavaScript - i.e. the unchanged elements are still in the page, just hidden. And there's a checkbox in the upper right corner to show them "Show unchanged". The state of the checkbox is not persisted when one clicks on links, which is not very nice, but my inclination was that it would be rare for people to look at stuff that didn't change.

Not sure if that's acceptable for the platform annex, if not I can add a command line option to either always show the unchanged elements, or to show them by default.

(The current value of the "Show unchanged" checkbox is unchecked, so JavaScript will by default hide the unchanged elements. But, as the hiding is done by JavaScript, if JavaScript is disabled, the unchanged elements are shown, which I think might be helpful, as without JavaScript, we can't control the state.)

> 
> In the list of updated elements, the background for the "!=" is now appears purple-y grey (formerly pinkish) and the "!=" character itself is red (unchanged, I think). I think this combination isn't as easy to parse as the former, Perhaps it needs more context to appreciate?

I tried this:
- the background colors are green for added, red for removed, light gray for changed, and white for unchanged.
- the foreground color is black

(And I made the green and red slightly darker.)

Not sure if that looks good, I've changed the original diff with these colors:
https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/after.01/
and also produced a JDK25 to master diff:
https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/25-master/after.01/
and the JDK 25 to master before this PR:
https://cr.openjdk.org/~jlahoda/CODETOOLS-7904082/25-master/before/

Does this look better?

> 
> The change in SourceCodeAnalysis.SnippetWrapper which adds the background color for the notes "Only in baseline; not in: demo" and "Only in: demo; not in: demo" looks good. (I noticed that there's a typo in report/html/resources/report.properties, line 126 "not i" should be "not in".)

(I've fixed the typo, but the examples above were generated before fixing that, sorry. Thanks for finding that!)

> 
> I'm not sure I'm finding an example of coloring of the signature lines. Let me know which elements I should be looking at for the comparison.

What I meant was the colors in the "Only in ..." lines, sorry for being imprecise. I can try to extend the color to other lines as well in desired.

> 
> Thanks again for all of your work to improve apidiff!

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

PR Comment: https://git.openjdk.org/apidiff/pull/32#issuecomment-3328054815