RFR: 7904082: The UI for API Diff could be improved

[Jan Lahoda]

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