From jjg at openjdk.org  Tue Oct  1 17:41:18 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 17:41:18 GMT
Subject: RFR: 7903852: apidiff: IllegalArgumentException for RECORD_COMPONENT
Message-ID: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>

Please review a small fix for an IllegalArgumentException.

The exception is "correct"; the error is at the call site which should not be calling the method that throws the exception.
Record components, like type parameters, do not have distinct A:PI descriptions that can be compared.

Separately, we need better back-end tests for `HtmlReporter`.

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

Commit messages:
 - 7903852: apidiff: IllegalArgumentException for RECORD_COMPONENT

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

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

From jjg at openjdk.org  Tue Oct  1 17:45:15 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 17:45:15 GMT
Subject: RFR: 7903851: apidiff: typo in comment for HtmlDiffBuilderTest
Message-ID: <lQ0ZW0CANqPSttNqXfs4Czo0wf9r3V5JufRfq7NNaJU=.86191157-1a02-481b-86bc-d69f8c3aa43d@github.com>

Please review a fix for a trivial typo in a comment in a test

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

Commit messages:
 - CODETOOLS-7903851: apidiff: typo in comment for HtmlDiffBuilderTest

Changes: https://git.openjdk.org/apidiff/pull/21/files
  Webrev: https://webrevs.openjdk.org/?repo=apidiff&pr=21&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903851
  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/apidiff/pull/21.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/21/head:pull/21

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

From prappo at openjdk.org  Tue Oct  1 17:55:47 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Tue, 1 Oct 2024 17:55:47 GMT
Subject: RFR: 7903851: apidiff: typo in comment for HtmlDiffBuilderTest
In-Reply-To: <lQ0ZW0CANqPSttNqXfs4Czo0wf9r3V5JufRfq7NNaJU=.86191157-1a02-481b-86bc-d69f8c3aa43d@github.com>
References: <lQ0ZW0CANqPSttNqXfs4Czo0wf9r3V5JufRfq7NNaJU=.86191157-1a02-481b-86bc-d69f8c3aa43d@github.com>
Message-ID: <dD2yXzEQcxpcjdLhxHEeIfRix9kVj1B1jK8usHF6v40=.5dc7e260-dae5-4c16-847d-1c99038b9e39@github.com>

On Tue, 1 Oct 2024 17:39:58 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a fix for a trivial typo in a comment in a test

Marked as reviewed by prappo (no project role).

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

PR Review: https://git.openjdk.org/apidiff/pull/21#pullrequestreview-2341028502

From prappo at openjdk.org  Tue Oct  1 18:15:49 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Tue, 1 Oct 2024 18:15:49 GMT
Subject: RFR: 7903852: apidiff: IllegalArgumentException for
 RECORD_COMPONENT
In-Reply-To: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
References: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
Message-ID: <nM6VLlP4NBF0q4h22LV4_FOpXAG-nqSZEUW3zkQeIzE=.955952f7-8561-496b-a6e3-00856408e6b0@github.com>

On Tue, 1 Oct 2024 17:36:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small fix for an IllegalArgumentException.
> 
> The exception is "correct"; the error is at the call site which should not be calling the method that throws the exception.
> Record components, like type parameters, do not have distinct A:PI descriptions that can be compared.
> 
> Separately, we need better back-end tests for `HtmlReporter`.

Does this PR simply improves the exception message?

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

PR Comment: https://git.openjdk.org/apidiff/pull/20#issuecomment-2386662151

From jjg at openjdk.org  Tue Oct  1 18:18:48 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 18:18:48 GMT
Subject: RFR: 7903852: apidiff: IllegalArgumentException for
 RECORD_COMPONENT
In-Reply-To: <nM6VLlP4NBF0q4h22LV4_FOpXAG-nqSZEUW3zkQeIzE=.955952f7-8561-496b-a6e3-00856408e6b0@github.com>
References: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
 <nM6VLlP4NBF0q4h22LV4_FOpXAG-nqSZEUW3zkQeIzE=.955952f7-8561-496b-a6e3-00856408e6b0@github.com>
Message-ID: <HkzoBbmmxB3gs_X9Yx_lg9dlkqWDEXz84gsFstbc0CU=.1b2bda28-ba21-4ef2-89d2-5fbaf4d382dc@github.com>

On Tue, 1 Oct 2024 18:13:45 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Does this PR simply improves the exception message?

No. In `RecordComponentComparator` it no longer calls the method that throws the exception.

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

PR Comment: https://git.openjdk.org/apidiff/pull/20#issuecomment-2386667470

From iris at openjdk.org  Tue Oct  1 18:23:48 2024
From: iris at openjdk.org (Iris Clark)
Date: Tue, 1 Oct 2024 18:23:48 GMT
Subject: RFR: 7903851: apidiff: typo in comment for HtmlDiffBuilderTest
In-Reply-To: <lQ0ZW0CANqPSttNqXfs4Czo0wf9r3V5JufRfq7NNaJU=.86191157-1a02-481b-86bc-d69f8c3aa43d@github.com>
References: <lQ0ZW0CANqPSttNqXfs4Czo0wf9r3V5JufRfq7NNaJU=.86191157-1a02-481b-86bc-d69f8c3aa43d@github.com>
Message-ID: <I6H1UJ1_S5smkBpiGATiR9YSwLGUfoyGn_Q2NEKBwoc=.c3db511b-6192-43f2-b694-eafae626f59f@github.com>

On Tue, 1 Oct 2024 17:39:58 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a fix for a trivial typo in a comment in a test

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/apidiff/pull/21#pullrequestreview-2341096205

From iris at openjdk.org  Tue Oct  1 18:24:51 2024
From: iris at openjdk.org (Iris Clark)
Date: Tue, 1 Oct 2024 18:24:51 GMT
Subject: RFR: 7903837: apidiff: build.sh issues on Windows [v4]
In-Reply-To: <s6s9Vi9xduGNaMCPPE2ksvpPQ2xy8qDfTL2hBVOBvtQ=.013379ce-7856-4407-b59c-47bcd06f01de@github.com>
References: <p10rhB88Coerc6z01jV02JW82CO6JowwfG2bxZ9TXnc=.35a09780-82a5-464d-9cf5-e35d6e496a65@github.com>
 <s6s9Vi9xduGNaMCPPE2ksvpPQ2xy8qDfTL2hBVOBvtQ=.013379ce-7856-4407-b59c-47bcd06f01de@github.com>
Message-ID: <HcwXcrVQwUtuyXCbBdIqmTo_bif6K15UVQJlB6v-QdI=.6a1ca5a0-c7e6-44e5-a55b-de42c0c6bd1c@github.com>

On Mon, 30 Sep 2024 22:10:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review some `build.sh` and `Makefile` changes to address issues building on Windows.
>> 
>> The primary Windows issue was missing use of `mixed_path` when passing some filenames into `make`.
>> There is some additional cleanup (for all platforms) to normalize the `DEPS_DIR` and add missing items to the `sanity` and `check_build_vars` targets.
>> 
>> This has been tested on macOS. Can someone with access to a Windows machine test it on Windows, please?
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   add EQUINOX_JAR, per suggestion in review

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/apidiff/pull/12#pullrequestreview-2341097472

From prappo at openjdk.org  Tue Oct  1 18:28:49 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Tue, 1 Oct 2024 18:28:49 GMT
Subject: RFR: 7903852: apidiff: IllegalArgumentException for
 RECORD_COMPONENT
In-Reply-To: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
References: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
Message-ID: <6ObpSNdSbhQjnteaGOhvNkExesH4_cDtrVmP_Fp6c9g=.b62ac65b-ef45-4e47-87b7-c5cdffead0a9@github.com>

On Tue, 1 Oct 2024 17:36:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small fix for an IllegalArgumentException.
> 
> The exception is "correct"; the error is at the call site which should not be calling the method that throws the exception.
> Record components, like type parameters, do not have distinct A:PI descriptions that can be compared.
> 
> Separately, we need better back-end tests for `HtmlReporter`.

Marked as reviewed by prappo (no project role).

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

PR Review: https://git.openjdk.org/apidiff/pull/20#pullrequestreview-2341098989

From iris at openjdk.org  Tue Oct  1 18:28:50 2024
From: iris at openjdk.org (Iris Clark)
Date: Tue, 1 Oct 2024 18:28:50 GMT
Subject: RFR: 7903852: apidiff: IllegalArgumentException for
 RECORD_COMPONENT
In-Reply-To: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
References: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
Message-ID: <b4P0uis31l1s6r4GZ_3NuXpCFmnWS1ayc2jqTuwh6Ro=.53155afb-721b-45a8-84a3-f8e82efa311a@github.com>

On Tue, 1 Oct 2024 17:36:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small fix for an IllegalArgumentException.
> 
> The exception is "correct"; the error is at the call site which should not be calling the method that throws the exception.
> Record components, like type parameters, do not have distinct A:PI descriptions that can be compared.
> 
> Separately, we need better back-end tests for `HtmlReporter`.

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/apidiff/pull/20#pullrequestreview-2341102862

From prappo at openjdk.org  Tue Oct  1 18:28:50 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Tue, 1 Oct 2024 18:28:50 GMT
Subject: RFR: 7903852: apidiff: IllegalArgumentException for
 RECORD_COMPONENT
In-Reply-To: <HkzoBbmmxB3gs_X9Yx_lg9dlkqWDEXz84gsFstbc0CU=.1b2bda28-ba21-4ef2-89d2-5fbaf4d382dc@github.com>
References: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
 <nM6VLlP4NBF0q4h22LV4_FOpXAG-nqSZEUW3zkQeIzE=.955952f7-8561-496b-a6e3-00856408e6b0@github.com>
 <HkzoBbmmxB3gs_X9Yx_lg9dlkqWDEXz84gsFstbc0CU=.1b2bda28-ba21-4ef2-89d2-5fbaf4d382dc@github.com>
Message-ID: <IsGypI3n1PfZID6hkZB8JIJaZxsKJu5H3V53n2yMRyI=.f66f6970-c8a3-4bb3-a56c-c1ff66d0466e@github.com>

On Tue, 1 Oct 2024 18:16:42 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> > Does this PR simply improves the exception message?
> 
> No. In `RecordComponentComparator` it no longer calls the method that throws the exception. There's actually no change in the exception message; the edits in the visitor are somewhat cosmetic, to improve the stack trace (!!) and to provide a place for a more specific explanatory comment.

Right, I see the problematic method has been removed:

        allEqual &= compareDocComments(rcPos, rcMap);
     -> allEqual &= compareApiDescriptions(rcPos, rcMap);

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

PR Comment: https://git.openjdk.org/apidiff/pull/20#issuecomment-2386677730

From jjg at openjdk.org  Tue Oct  1 18:28:50 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 18:28:50 GMT
Subject: RFR: 7903852: apidiff: IllegalArgumentException for
 RECORD_COMPONENT
In-Reply-To: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
References: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
Message-ID: <-SvCKcLLf1jVPQGQ7Fvet4KzB1Irll6rIgELws-e1Hs=.add2aabd-b163-49d5-baec-0cb6c1b15b3e@github.com>

On Tue, 1 Oct 2024 17:36:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small fix for an IllegalArgumentException.
> 
> The exception is "correct"; the error is at the call site which should not be calling the method that throws the exception.
> Record components, like type parameters, do not have distinct A:PI descriptions that can be compared.
> 
> Separately, we need better back-end tests for `HtmlReporter`.

Yes.
Record components are like type parameters in that neither have standalone doc comments, and so neither have corresponding generated API descriptions either.  I wanted to add comments to draw out that similarity.

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

PR Comment: https://git.openjdk.org/apidiff/pull/20#issuecomment-2386684958

From jjg at openjdk.org  Tue Oct  1 18:34:51 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 18:34:51 GMT
Subject: Integrated: 7903852: apidiff: IllegalArgumentException for
 RECORD_COMPONENT
In-Reply-To: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
References: <8MM4fjTZ2_AgK7ukCguP2kocwaclSX8JgTS5tcf45IE=.00c9d897-66e3-4c58-95ed-6f8b0c29cf35@github.com>
Message-ID: <_PagccUlc5arH6eCXUa80N9Xzacn35IdXdpCnteyJ_c=.1768e814-7d25-4654-aff2-2b2e4aa73b22@github.com>

On Tue, 1 Oct 2024 17:36:46 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small fix for an IllegalArgumentException.
> 
> The exception is "correct"; the error is at the call site which should not be calling the method that throws the exception.
> Record components, like type parameters, do not have distinct A:PI descriptions that can be compared.
> 
> Separately, we need better back-end tests for `HtmlReporter`.

This pull request has now been integrated.

Changeset: 18841014
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/18841014b895d0e242f9bb72e1fb9a3787a8655f
Stats:     15 lines in 3 files changed: 13 ins; 0 del; 2 mod

7903852: apidiff: IllegalArgumentException for RECORD_COMPONENT

Reviewed-by: prappo, iris

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

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

From jjg at openjdk.org  Tue Oct  1 18:35:51 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 18:35:51 GMT
Subject: Integrated: 7903851: apidiff: typo in comment for HtmlDiffBuilderTest
In-Reply-To: <lQ0ZW0CANqPSttNqXfs4Czo0wf9r3V5JufRfq7NNaJU=.86191157-1a02-481b-86bc-d69f8c3aa43d@github.com>
References: <lQ0ZW0CANqPSttNqXfs4Czo0wf9r3V5JufRfq7NNaJU=.86191157-1a02-481b-86bc-d69f8c3aa43d@github.com>
Message-ID: <gUqwTDCmYLXJ75bO1zyv1-Q7KxX4NM93y4DL8btmDfI=.18bf2943-080c-4088-9055-60dc9fd0a1c0@github.com>

On Tue, 1 Oct 2024 17:39:58 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a fix for a trivial typo in a comment in a test

This pull request has now been integrated.

Changeset: 89744737
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/89744737327a7456a771834f3e4a3790d41177c5
Stats:     1 line in 1 file changed: 0 ins; 0 del; 1 mod

7903851: apidiff: typo in comment for HtmlDiffBuilderTest

Reviewed-by: prappo, iris

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

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

From jjg at openjdk.org  Tue Oct  1 18:37:49 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 18:37:49 GMT
Subject: Integrated: 7903837: apidiff: build.sh issues on Windows
In-Reply-To: <p10rhB88Coerc6z01jV02JW82CO6JowwfG2bxZ9TXnc=.35a09780-82a5-464d-9cf5-e35d6e496a65@github.com>
References: <p10rhB88Coerc6z01jV02JW82CO6JowwfG2bxZ9TXnc=.35a09780-82a5-464d-9cf5-e35d6e496a65@github.com>
Message-ID: <tMuHk1OBeMhDZAQsGy-M-NyiPMSXd5HaP-QwMpEcUSM=.be907e8e-dbe8-4b75-b81f-817ceee8a76f@github.com>

On Wed, 25 Sep 2024 17:51:53 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review some `build.sh` and `Makefile` changes to address issues building on Windows.
> 
> The primary Windows issue was missing use of `mixed_path` when passing some filenames into `make`.
> There is some additional cleanup (for all platforms) to normalize the `DEPS_DIR` and add missing items to the `sanity` and `check_build_vars` targets.
> 
> This has been tested on macOS. Can someone with access to a Windows machine test it on Windows, please?

This pull request has now been integrated.

Changeset: ac5e9e78
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/ac5e9e785f9b254aed608f0ac50442ede9cf57d5
Stats:     42 lines in 5 files changed: 20 ins; 3 del; 19 mod

7903837: apidiff: build.sh issues on Windows

Reviewed-by: iris

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

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

From jjg at openjdk.org  Tue Oct  1 18:40:57 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 18:40:57 GMT
Subject: Integrated: 7903839: apidiff: Add a "make docs" target for the primary
 internal API
Message-ID: <CwXGWUrAeg_h0xzipTnkFABpZk3eFpKYk5Q0EQITXIc=.eae58e4c-6ead-4365-85fb-2c646963a500@github.com>

Please review a small Makefile update to expose a friendly "make docs" target to generate API documentation for the internal API.

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

Commit messages:
 - CODETOOLS-7903839: apidiff: Add a "make docs" target for the primary internal API

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

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

From iris at openjdk.org  Tue Oct  1 18:40:57 2024
From: iris at openjdk.org (Iris Clark)
Date: Tue, 1 Oct 2024 18:40:57 GMT
Subject: Integrated: 7903839: apidiff: Add a "make docs" target for the
 primary internal API
In-Reply-To: <CwXGWUrAeg_h0xzipTnkFABpZk3eFpKYk5Q0EQITXIc=.eae58e4c-6ead-4365-85fb-2c646963a500@github.com>
References: <CwXGWUrAeg_h0xzipTnkFABpZk3eFpKYk5Q0EQITXIc=.eae58e4c-6ead-4365-85fb-2c646963a500@github.com>
Message-ID: <qPPZg3DHNJqPZU7b-t4KxtaAF4yqENx0nKZIlvvJxBY=.ff7b23c3-dc87-47e0-9d98-668ab1c40880@github.com>

On Wed, 25 Sep 2024 21:34:18 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small Makefile update to expose a friendly "make docs" target to generate API documentation for the internal API.

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/apidiff/pull/14#pullrequestreview-2334449814

From jjg at openjdk.org  Tue Oct  1 18:40:58 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 18:40:58 GMT
Subject: Integrated: 7903839: apidiff: Add a "make docs" target for the
 primary internal API
In-Reply-To: <CwXGWUrAeg_h0xzipTnkFABpZk3eFpKYk5Q0EQITXIc=.eae58e4c-6ead-4365-85fb-2c646963a500@github.com>
References: <CwXGWUrAeg_h0xzipTnkFABpZk3eFpKYk5Q0EQITXIc=.eae58e4c-6ead-4365-85fb-2c646963a500@github.com>
Message-ID: <ErrlkbM7KfwafJ95VQxnofZAMlTnyrW68hFL5Zk9wWw=.ae3826e6-1cbe-4bd9-959f-ce82241284a5@github.com>

On Wed, 25 Sep 2024 21:34:18 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small Makefile update to expose a friendly "make docs" target to generate API documentation for the internal API.

This is a draft request until we can merge with https://github.com/openjdk/apidiff/pull/12 to fix some build issues on Windows.

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

PR Comment: https://git.openjdk.org/apidiff/pull/14#issuecomment-2375306726

From jjg at openjdk.org  Tue Oct  1 18:40:58 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 18:40:58 GMT
Subject: Integrated: 7903839: apidiff: Add a "make docs" target for the primary
 internal API
In-Reply-To: <CwXGWUrAeg_h0xzipTnkFABpZk3eFpKYk5Q0EQITXIc=.eae58e4c-6ead-4365-85fb-2c646963a500@github.com>
References: <CwXGWUrAeg_h0xzipTnkFABpZk3eFpKYk5Q0EQITXIc=.eae58e4c-6ead-4365-85fb-2c646963a500@github.com>
Message-ID: <GOnXvv3IsnH-Zr29q4MNnjdUpagY04dQwRk7js_QP1w=.8d33912a-1661-4fed-8604-9031d0056d06@github.com>

On Wed, 25 Sep 2024 21:34:18 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small Makefile update to expose a friendly "make docs" target to generate API documentation for the internal API.

This pull request has now been integrated.

Changeset: 18800d3c
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/18800d3c15a70e67c6e0e3595ca83f9f6cd37d7f
Stats:     4 lines in 2 files changed: 2 ins; 0 del; 2 mod

7903839: apidiff: Add a "make docs" target for the primary internal API

Reviewed-by: iris

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

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

From iris at openjdk.org  Tue Oct  1 20:38:49 2024
From: iris at openjdk.org (Iris Clark)
Date: Tue, 1 Oct 2024 20:38:49 GMT
Subject: RFR: 7903840: apidiff: optionally show expansion of `--jdk-build`
In-Reply-To: <CQVFY1VpqKR_uYrNFRRzt4dco0Iq8qE_hGgiEMcJAj8=.66a4e9c2-fee3-410f-9870-c5d3f3a82597@github.com>
References: <CQVFY1VpqKR_uYrNFRRzt4dco0Iq8qE_hGgiEMcJAj8=.66a4e9c2-fee3-410f-9870-c5d3f3a82597@github.com>
Message-ID: <TfuJhASTQpEpO3uSaigLHntxiQBIqrzoUqcH5NE75vY=.f5089b43-6d80-4a42-a82c-ff2454fa329b@github.com>

On Mon, 30 Sep 2024 21:25:27 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small-ish PR to add support for `--verbose options` which outputs details about the upfront option handling.

Remember to update copyright year on modified files.

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

Marked as reviewed by iris (Reviewer).

PR Review: https://git.openjdk.org/apidiff/pull/19#pullrequestreview-2341408348

From jjg at openjdk.org  Tue Oct  1 22:07:59 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 22:07:59 GMT
Subject: RFR: 7903840: apidiff: optionally show expansion of `--jdk-build`
 [v2]
In-Reply-To: <CQVFY1VpqKR_uYrNFRRzt4dco0Iq8qE_hGgiEMcJAj8=.66a4e9c2-fee3-410f-9870-c5d3f3a82597@github.com>
References: <CQVFY1VpqKR_uYrNFRRzt4dco0Iq8qE_hGgiEMcJAj8=.66a4e9c2-fee3-410f-9870-c5d3f3a82597@github.com>
Message-ID: <0v6GOdVQqs1q3nK7_etXtURKPL14zzEzsjzY5zy8CGM=.7f1c2d1e-e2ee-432e-974f-4ddcfedee0cb@github.com>

> Please review a small-ish PR to add support for `--verbose options` which outputs details about the upfront option handling.

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

 - fix copyright years
 - merge with upstream/master
 - fix test compilation failure, and fix some IDE suggestions
 - CODETOOLS-7903840: apidiff: optionally show expansion of `--jdk-build`

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

Changes: https://git.openjdk.org/apidiff/pull/19/files
  Webrev: https://webrevs.openjdk.org/?repo=apidiff&pr=19&range=01
  Stats: 125 lines in 6 files changed: 99 ins; 1 del; 25 mod
  Patch: https://git.openjdk.org/apidiff/pull/19.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/19/head:pull/19

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

From jjg at openjdk.org  Tue Oct  1 22:07:59 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 1 Oct 2024 22:07:59 GMT
Subject: Integrated: 7903840: apidiff: optionally show expansion of
 `--jdk-build`
In-Reply-To: <CQVFY1VpqKR_uYrNFRRzt4dco0Iq8qE_hGgiEMcJAj8=.66a4e9c2-fee3-410f-9870-c5d3f3a82597@github.com>
References: <CQVFY1VpqKR_uYrNFRRzt4dco0Iq8qE_hGgiEMcJAj8=.66a4e9c2-fee3-410f-9870-c5d3f3a82597@github.com>
Message-ID: <faT-_IL0feuiQYYFx9at8o2gXswJere8udKCZuiv1LA=.b0b62c1e-128d-4cda-87f4-acccf0580e51@github.com>

On Mon, 30 Sep 2024 21:25:27 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small-ish PR to add support for `--verbose options` which outputs details about the upfront option handling.

This pull request has now been integrated.

Changeset: 04f70c7a
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/04f70c7ad165bde55d7667226801aa106b9205ad
Stats:     125 lines in 6 files changed: 99 ins; 1 del; 25 mod

7903840: apidiff: optionally show expansion of `--jdk-build`

Reviewed-by: iris

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

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

From jjg at openjdk.org  Wed Oct  2 03:45:15 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 2 Oct 2024 03:45:15 GMT
Subject: RFR: 7903856: apidiff: 7903837 breaks some builds
Message-ID: <RFqe8bA8SYkWdGUBgLd6FjDapunwzM44UHI2ARWIKcI=.feae41d2-2425-471d-af2d-4419b87fb70d@github.com>

Please review a small but important fix for an issue handling EQUINOX_JAR in some build environments.

The underlying issue is that EQUINOX_JAR may or may not be required, depending on the configuration for DAISYDIFF.

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

Commit messages:
 - CODETOOLS-7903856: apidiff: 7903837 breaks some builds

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

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

From iris at openjdk.org  Wed Oct  2 03:45:15 2024
From: iris at openjdk.org (Iris Clark)
Date: Wed, 2 Oct 2024 03:45:15 GMT
Subject: RFR: 7903856: apidiff: 7903837 breaks some builds
In-Reply-To: <RFqe8bA8SYkWdGUBgLd6FjDapunwzM44UHI2ARWIKcI=.feae41d2-2425-471d-af2d-4419b87fb70d@github.com>
References: <RFqe8bA8SYkWdGUBgLd6FjDapunwzM44UHI2ARWIKcI=.feae41d2-2425-471d-af2d-4419b87fb70d@github.com>
Message-ID: <YEfPgIolif3wKF9GfaRlKeIR-wunK4gm54WZd9SqZbE=.fc773618-1088-4780-9a1d-5ce24da984a2@github.com>

On Wed, 2 Oct 2024 03:39:06 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small but important fix for an issue handling EQUINOX_JAR in some build environments.
> 
> The underlying issue is that EQUINOX_JAR may or may not be required, depending on the configuration for DAISYDIFF.

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/apidiff/pull/22#pullrequestreview-2341853164

From cstein at openjdk.org  Wed Oct  2 07:01:48 2024
From: cstein at openjdk.org (Christian Stein)
Date: Wed, 2 Oct 2024 07:01:48 GMT
Subject: RFR: 7903856: apidiff: 7903837 breaks some builds
In-Reply-To: <RFqe8bA8SYkWdGUBgLd6FjDapunwzM44UHI2ARWIKcI=.feae41d2-2425-471d-af2d-4419b87fb70d@github.com>
References: <RFqe8bA8SYkWdGUBgLd6FjDapunwzM44UHI2ARWIKcI=.feae41d2-2425-471d-af2d-4419b87fb70d@github.com>
Message-ID: <2t0K76Bj-HqV3qmyvzsn7LiifVZQLuWR2gTErIuM95s=.8c19ff0c-fdb1-467a-a0b6-b27d994de523@github.com>

On Wed, 2 Oct 2024 03:39:06 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small but important fix for an issue handling EQUINOX_JAR in some build environments.
> 
> The underlying issue is that EQUINOX_JAR may or may not be required, depending on the configuration for DAISYDIFF.

Works on Windows

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

Marked as reviewed by cstein (Committer).

PR Review: https://git.openjdk.org/apidiff/pull/22#pullrequestreview-2342015897

From cstein at openjdk.org  Wed Oct  2 08:09:56 2024
From: cstein at openjdk.org (Christian Stein)
Date: Wed, 2 Oct 2024 08:09:56 GMT
Subject: RFR: 7903857: apidiff: Include test run in GitHub Actions workflow
Message-ID: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>

Please review this change to actually run ApiDiff's self-tests on all three major platforms.

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

Commit messages:
 - CODETOOLS-7903857: apidiff: Include test run in GitHub Actions workflow

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

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

From cstein at openjdk.org  Wed Oct  2 09:06:20 2024
From: cstein at openjdk.org (Christian Stein)
Date: Wed, 2 Oct 2024 09:06:20 GMT
Subject: RFR: 7903857: apidiff: Include test run in GitHub Actions workflow
 [v2]
In-Reply-To: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>
References: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>
Message-ID: <3_q24XsDxPe-agrmvaugeRhU6IH483QeSPVCxyQooHg=.bcb1c786-c8fd-44ae-b230-2e15751701a2@github.com>

> Please review this change to actually run ApiDiff's self-tests on all three major platforms.

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

  Remove `set -o pipefail` from test run

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

Changes:
  - all: https://git.openjdk.org/apidiff/pull/23/files
  - new: https://git.openjdk.org/apidiff/pull/23/files/49fd0e55..f68c3e3c

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

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

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

From cstein at openjdk.org  Wed Oct  2 09:28:08 2024
From: cstein at openjdk.org (Christian Stein)
Date: Wed, 2 Oct 2024 09:28:08 GMT
Subject: RFR: 7903857: apidiff: Include test run in GitHub Actions workflow
 [v3]
In-Reply-To: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>
References: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>
Message-ID: <PY271KbVfiG6gpRrkanAYIN5NmZrj39bE_ZOezK6tJs=.5a52d332-40ec-4ea0-85cf-be510b8f9cb8@github.com>

> Please review this change to actually run ApiDiff's self-tests on all three major platforms.

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

  Find `wget[.exe]` on Windows

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

Changes:
  - all: https://git.openjdk.org/apidiff/pull/23/files
  - new: https://git.openjdk.org/apidiff/pull/23/files/f68c3e3c..50ba912a

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

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

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

From cstein at openjdk.org  Wed Oct  2 09:41:24 2024
From: cstein at openjdk.org (Christian Stein)
Date: Wed, 2 Oct 2024 09:41:24 GMT
Subject: RFR: 7903857: apidiff: Include test run in GitHub Actions workflow
 [v4]
In-Reply-To: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>
References: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>
Message-ID: <Zqdzw8IMELbHVftZRyT1d_jNc0-V5hJ7RAP8TvWnThY=.a4f8f3b5-49f9-4901-8c6c-e587c53d68db@github.com>

> Please review this change to actually run ApiDiff's self-tests on all three major platforms.

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

  Try other MSYS2 installation path

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

Changes:
  - all: https://git.openjdk.org/apidiff/pull/23/files
  - new: https://git.openjdk.org/apidiff/pull/23/files/50ba912a..db262374

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

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

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

From prappo at openjdk.org  Wed Oct  2 11:17:47 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 2 Oct 2024 11:17:47 GMT
Subject: RFR: 7903857: apidiff: Include test run in GitHub Actions workflow
 [v4]
In-Reply-To: <Zqdzw8IMELbHVftZRyT1d_jNc0-V5hJ7RAP8TvWnThY=.a4f8f3b5-49f9-4901-8c6c-e587c53d68db@github.com>
References: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>
 <Zqdzw8IMELbHVftZRyT1d_jNc0-V5hJ7RAP8TvWnThY=.a4f8f3b5-49f9-4901-8c6c-e587c53d68db@github.com>
Message-ID: <utijoZZA3MPk7G4IKcQxcG-bXjW-puWhpYGPyoM77l8=.2755606a-9381-46a2-90f9-c137f29ad614@github.com>

On Wed, 2 Oct 2024 09:41:24 GMT, Christian Stein <cstein at openjdk.org> wrote:

>> Please review this change to actually run ApiDiff's self-tests on all three major platforms.
>
> Christian Stein has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Try other MSYS2 installation path

How did you verify that the updated workflow works?

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

PR Comment: https://git.openjdk.org/apidiff/pull/23#issuecomment-2388390663

From prappo at openjdk.org  Wed Oct  2 11:53:57 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Wed, 2 Oct 2024 11:53:57 GMT
Subject: RFR: 7903856: apidiff: 7903837 breaks some builds
In-Reply-To: <RFqe8bA8SYkWdGUBgLd6FjDapunwzM44UHI2ARWIKcI=.feae41d2-2425-471d-af2d-4419b87fb70d@github.com>
References: <RFqe8bA8SYkWdGUBgLd6FjDapunwzM44UHI2ARWIKcI=.feae41d2-2425-471d-af2d-4419b87fb70d@github.com>
Message-ID: <xGpSTDiQt2TYVUwo7Fj6kOjpprBLmOCFwVYmNVqbcgU=.dfb0540d-b1a3-484f-b0fc-b937b75ad5de@github.com>

On Wed, 2 Oct 2024 03:39:06 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small but important fix for an issue handling EQUINOX_JAR in some build environments.
> 
> The underlying issue is that EQUINOX_JAR may or may not be required, depending on the configuration for DAISYDIFF.

Marked as reviewed by prappo (no project role).

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

PR Review: https://git.openjdk.org/apidiff/pull/22#pullrequestreview-2342698368

From jjg at openjdk.org  Wed Oct  2 14:10:49 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 2 Oct 2024 14:10:49 GMT
Subject: Integrated: 7903856: apidiff: 7903837 breaks some builds
In-Reply-To: <RFqe8bA8SYkWdGUBgLd6FjDapunwzM44UHI2ARWIKcI=.feae41d2-2425-471d-af2d-4419b87fb70d@github.com>
References: <RFqe8bA8SYkWdGUBgLd6FjDapunwzM44UHI2ARWIKcI=.feae41d2-2425-471d-af2d-4419b87fb70d@github.com>
Message-ID: <6qgOtmBMBC86Gq-1MInMeLzRWa5LDF3D-lvhcba3NL8=.641763be-8274-4def-9d1f-27e9e40d79e4@github.com>

On Wed, 2 Oct 2024 03:39:06 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small but important fix for an issue handling EQUINOX_JAR in some build environments.
> 
> The underlying issue is that EQUINOX_JAR may or may not be required, depending on the configuration for DAISYDIFF.

This pull request has now been integrated.

Changeset: db3c4747
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/db3c4747c30991397ec5b0df9fff7fa79f279102
Stats:     10 lines in 2 files changed: 5 ins; 0 del; 5 mod

7903856: apidiff: 7903837 breaks some builds

Reviewed-by: iris, cstein, prappo

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

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

From cstein at openjdk.org  Wed Oct  2 14:30:54 2024
From: cstein at openjdk.org (Christian Stein)
Date: Wed, 2 Oct 2024 14:30:54 GMT
Subject: RFR: 7903857: apidiff: Include test run in GitHub Actions workflow
 [v4]
In-Reply-To: <utijoZZA3MPk7G4IKcQxcG-bXjW-puWhpYGPyoM77l8=.2755606a-9381-46a2-90f9-c137f29ad614@github.com>
References: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>
 <Zqdzw8IMELbHVftZRyT1d_jNc0-V5hJ7RAP8TvWnThY=.a4f8f3b5-49f9-4901-8c6c-e587c53d68db@github.com>
 <utijoZZA3MPk7G4IKcQxcG-bXjW-puWhpYGPyoM77l8=.2755606a-9381-46a2-90f9-c137f29ad614@github.com>
Message-ID: <_zAZztntXLv6e3GSQ17Fy0YCr2vKn9GLCdPdkc1MyYU=.0b2153d7-e4c7-43ce-bc66-41f1637a1b96@github.com>

On Wed, 2 Oct 2024 11:15:01 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> How did you verify that the updated workflow works?

They did not! See latest failed runs at https://github.com/sormuras/apidiff/actions/workflows/test.yml

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

PR Comment: https://git.openjdk.org/apidiff/pull/23#issuecomment-2388794850

From jjg at openjdk.org  Wed Oct  2 22:27:14 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Wed, 2 Oct 2024 22:27:14 GMT
Subject: RFR: 7903859: add more details to the top-level README.md file
Message-ID: <UJRFlOYZj1q8bZIsrzeJLS9DyZu0O677LCgAG7-h2-U=.51341a3e-d7a8-4a79-8b9a-b2a04a9d92c7@github.com>

Please review a docs update, mostly correcting or adding details to the top-level README.md, but also taking this opportunity to add some details into the "man" page.

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

Commit messages:
 - CODETOOLS-7903859: add more details to the top-level README.md file

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

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

From iris at openjdk.org  Wed Oct  2 23:57:46 2024
From: iris at openjdk.org (Iris Clark)
Date: Wed, 2 Oct 2024 23:57:46 GMT
Subject: RFR: 7903859: add more details to the top-level README.md file
In-Reply-To: <UJRFlOYZj1q8bZIsrzeJLS9DyZu0O677LCgAG7-h2-U=.51341a3e-d7a8-4a79-8b9a-b2a04a9d92c7@github.com>
References: <UJRFlOYZj1q8bZIsrzeJLS9DyZu0O677LCgAG7-h2-U=.51341a3e-d7a8-4a79-8b9a-b2a04a9d92c7@github.com>
Message-ID: <ZHWzRd6EX0S11nC9wrE9REPP510LAggKgVi0lB4_EA0=.58d3422c-cfed-464b-8977-a98ebd553422@github.com>

On Wed, 2 Oct 2024 22:21:57 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a docs update, mostly correcting or adding details to the top-level README.md, but also taking this opportunity to add some details into the "man" page.

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/apidiff/pull/24#pullrequestreview-2344362392

From jjg at openjdk.org  Thu Oct  3 00:03:54 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 3 Oct 2024 00:03:54 GMT
Subject: Integrated: 7903859: add more details to the top-level README.md file
In-Reply-To: <UJRFlOYZj1q8bZIsrzeJLS9DyZu0O677LCgAG7-h2-U=.51341a3e-d7a8-4a79-8b9a-b2a04a9d92c7@github.com>
References: <UJRFlOYZj1q8bZIsrzeJLS9DyZu0O677LCgAG7-h2-U=.51341a3e-d7a8-4a79-8b9a-b2a04a9d92c7@github.com>
Message-ID: <PLSZQO_PLYvGYBuEpJ66vJwgh0xMKhJ4AB7y-2HpsFA=.d095251e-44cb-4073-bffe-886414f6e6f7@github.com>

On Wed, 2 Oct 2024 22:21:57 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a docs update, mostly correcting or adding details to the top-level README.md, but also taking this opportunity to add some details into the "man" page.

This pull request has now been integrated.

Changeset: 83e4d301
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/83e4d3014017ab730a5a7333a555423a0f676824
Stats:     71 lines in 2 files changed: 64 ins; 0 del; 7 mod

7903859: add more details to the top-level README.md file

Reviewed-by: iris

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

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

From cstein at openjdk.org  Thu Oct 10 10:11:26 2024
From: cstein at openjdk.org (Christian Stein)
Date: Thu, 10 Oct 2024 10:11:26 GMT
Subject: Withdrawn: 7903857: apidiff: Include test run in GitHub Actions
 workflow
In-Reply-To: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>
References: <M8MyFAI-gfzG7dk4gczHO8ajhxZkk98uDQrnW2vYHl8=.6ac79452-83ef-4e46-b7dd-3a149de01e4b@github.com>
Message-ID: <-bjfLyb4ZpOZkI41BMquJfFJyN_aSmYaG9-5xhGxH9Q=.2a1f3c8c-ece4-4a4f-ad62-42a724556b9b@github.com>

On Wed, 2 Oct 2024 08:04:50 GMT, Christian Stein <cstein at openjdk.org> wrote:

> Please review this change to actually run ApiDiff's self-tests on all three major platforms.

This pull request has been closed without being integrated.

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

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

From cstein at openjdk.org  Thu Oct 10 10:14:53 2024
From: cstein at openjdk.org (Christian Stein)
Date: Thu, 10 Oct 2024 10:14:53 GMT
Subject: RFR: 7903857: Include test run in GitHub Actions workflow
Message-ID: <XTqyg_RCLkIEIzIopcZK1p-lC1Cc5cJSmRMrexJMgBs=.5deb21b7-6e50-4c93-9d66-38c004ee9793@github.com>

Please review this change to run APIDiff's self-tests for each pull request.

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

Commit messages:
 - 7903857: Include test run in GitHub Actions workflow

Changes: https://git.openjdk.org/apidiff/pull/25/files
  Webrev: https://webrevs.openjdk.org/?repo=apidiff&pr=25&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903857
  Stats: 14 lines in 1 file changed: 4 ins; 4 del; 6 mod
  Patch: https://git.openjdk.org/apidiff/pull/25.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/25/head:pull/25

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

From cstein at openjdk.org  Thu Oct 10 10:19:55 2024
From: cstein at openjdk.org (Christian Stein)
Date: Thu, 10 Oct 2024 10:19:55 GMT
Subject: RFR: 7903857: Include test run in GitHub Actions workflow [v2]
In-Reply-To: <XTqyg_RCLkIEIzIopcZK1p-lC1Cc5cJSmRMrexJMgBs=.5deb21b7-6e50-4c93-9d66-38c004ee9793@github.com>
References: <XTqyg_RCLkIEIzIopcZK1p-lC1Cc5cJSmRMrexJMgBs=.5deb21b7-6e50-4c93-9d66-38c004ee9793@github.com>
Message-ID: <F8G8tsMzbsmjK1FOvXSCNcK20-mFasDW5g82y_dPrak=.5b583246-fbec-4866-89ab-f5195dd57097@github.com>

> Please review this change to run APIDiff's self-tests for each pull request.

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

  Fix `/bin/sh: 2: set: Illegal option -o pipefail` error

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

Changes:
  - all: https://git.openjdk.org/apidiff/pull/25/files
  - new: https://git.openjdk.org/apidiff/pull/25/files/f5ca7476..55a4f039

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

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

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

From prappo at openjdk.org  Thu Oct 10 10:19:55 2024
From: prappo at openjdk.org (Pavel Rappo)
Date: Thu, 10 Oct 2024 10:19:55 GMT
Subject: RFR: 7903857: Include test run in GitHub Actions workflow [v2]
In-Reply-To: <F8G8tsMzbsmjK1FOvXSCNcK20-mFasDW5g82y_dPrak=.5b583246-fbec-4866-89ab-f5195dd57097@github.com>
References: <XTqyg_RCLkIEIzIopcZK1p-lC1Cc5cJSmRMrexJMgBs=.5deb21b7-6e50-4c93-9d66-38c004ee9793@github.com>
 <F8G8tsMzbsmjK1FOvXSCNcK20-mFasDW5g82y_dPrak=.5b583246-fbec-4866-89ab-f5195dd57097@github.com>
Message-ID: <JIx9Fk6lqa18gLGPfQgp9Zj_d2Uv6hquinDdGMELssk=.69af46a3-b5a8-47ba-9517-fc548f0eea70@github.com>

On Thu, 10 Oct 2024 10:17:16 GMT, Christian Stein <cstein at openjdk.org> wrote:

>> Please review this change to run APIDiff's self-tests for each pull request.
>
> Christian Stein has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix `/bin/sh: 2: set: Illegal option -o pipefail` error

Marked as reviewed by prappo (no project role).

.github/workflows/test.yml line 22:

> 20:         with:
> 21:           distribution: 'oracle'
> 22:           java-version: 17

It would be nice to move to JDK 21 soon.

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

PR Review: https://git.openjdk.org/apidiff/pull/25#pullrequestreview-2359769346
PR Review Comment: https://git.openjdk.org/apidiff/pull/25#discussion_r1795141087

From cstein at openjdk.org  Thu Oct 10 10:23:23 2024
From: cstein at openjdk.org (Christian Stein)
Date: Thu, 10 Oct 2024 10:23:23 GMT
Subject: RFR: 7903857: Include test run in GitHub Actions workflow [v2]
In-Reply-To: <JIx9Fk6lqa18gLGPfQgp9Zj_d2Uv6hquinDdGMELssk=.69af46a3-b5a8-47ba-9517-fc548f0eea70@github.com>
References: <XTqyg_RCLkIEIzIopcZK1p-lC1Cc5cJSmRMrexJMgBs=.5deb21b7-6e50-4c93-9d66-38c004ee9793@github.com>
 <F8G8tsMzbsmjK1FOvXSCNcK20-mFasDW5g82y_dPrak=.5b583246-fbec-4866-89ab-f5195dd57097@github.com>
 <JIx9Fk6lqa18gLGPfQgp9Zj_d2Uv6hquinDdGMELssk=.69af46a3-b5a8-47ba-9517-fc548f0eea70@github.com>
Message-ID: <N8mvW_GFQEjOrbF9uNrcaL06hWi8mETTN0cPKNm-GYE=.1351b3cb-c625-4228-b0e6-2288290c0d33@github.com>

On Thu, 10 Oct 2024 10:16:50 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Christian Stein has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fix `/bin/sh: 2: set: Illegal option -o pipefail` error
>
> .github/workflows/test.yml line 22:
> 
>> 20:         with:
>> 21:           distribution: 'oracle'
>> 22:           java-version: 17
> 
> It would be nice to move to JDK 21 soon.

Upgrading to use Java 21 will be done in a separate effort: as it might affect [building and testing](https://github.com/openjdk/apidiff/tree/master/make#building-apidiff).

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

PR Review Comment: https://git.openjdk.org/apidiff/pull/25#discussion_r1795146287

From jpai at openjdk.org  Thu Oct 10 10:29:25 2024
From: jpai at openjdk.org (Jaikiran Pai)
Date: Thu, 10 Oct 2024 10:29:25 GMT
Subject: RFR: 7903857: Include test run in GitHub Actions workflow [v2]
In-Reply-To: <F8G8tsMzbsmjK1FOvXSCNcK20-mFasDW5g82y_dPrak=.5b583246-fbec-4866-89ab-f5195dd57097@github.com>
References: <XTqyg_RCLkIEIzIopcZK1p-lC1Cc5cJSmRMrexJMgBs=.5deb21b7-6e50-4c93-9d66-38c004ee9793@github.com>
 <F8G8tsMzbsmjK1FOvXSCNcK20-mFasDW5g82y_dPrak=.5b583246-fbec-4866-89ab-f5195dd57097@github.com>
Message-ID: <saXT8HSJLoOns12s_BiIcqPuh84NzAuLecZhPFSb_M8=.feacf246-6f7b-4f3a-9e19-c1908c4ebafa@github.com>

On Thu, 10 Oct 2024 10:19:55 GMT, Christian Stein <cstein at openjdk.org> wrote:

>> Please review this change to run APIDiff's self-tests for each pull request.
>
> Christian Stein has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix `/bin/sh: 2: set: Illegal option -o pipefail` error

test/junit/JUnitTests.gmk line 44:

> 42: 	$(MKDIR) -p $(@:%.ok=%/work) $(@:%.ok=%/report)
> 43: 	cd $(@:%.ok=%/work) ; \
> 44: 	set -o pipefail ; \

Hello Christian, is this an intentional change on this line?

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

PR Review Comment: https://git.openjdk.org/apidiff/pull/25#discussion_r1795156986

From cstein at openjdk.org  Thu Oct 10 10:32:22 2024
From: cstein at openjdk.org (Christian Stein)
Date: Thu, 10 Oct 2024 10:32:22 GMT
Subject: RFR: 7903857: Include test run in GitHub Actions workflow [v2]
In-Reply-To: <saXT8HSJLoOns12s_BiIcqPuh84NzAuLecZhPFSb_M8=.feacf246-6f7b-4f3a-9e19-c1908c4ebafa@github.com>
References: <XTqyg_RCLkIEIzIopcZK1p-lC1Cc5cJSmRMrexJMgBs=.5deb21b7-6e50-4c93-9d66-38c004ee9793@github.com>
 <F8G8tsMzbsmjK1FOvXSCNcK20-mFasDW5g82y_dPrak=.5b583246-fbec-4866-89ab-f5195dd57097@github.com>
 <saXT8HSJLoOns12s_BiIcqPuh84NzAuLecZhPFSb_M8=.feacf246-6f7b-4f3a-9e19-c1908c4ebafa@github.com>
Message-ID: <JuE7axCgkjB8odSLSUuGIbW8x3tlPqm2PdyPrmCgSkg=.3e74c0de-0554-44a4-bfea-9c3669bc0a10@github.com>

On Thu, 10 Oct 2024 10:26:49 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> Christian Stein has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fix `/bin/sh: 2: set: Illegal option -o pipefail` error
>
> test/junit/JUnitTests.gmk line 44:
> 
>> 42: 	$(MKDIR) -p $(@:%.ok=%/work) $(@:%.ok=%/report)
>> 43: 	cd $(@:%.ok=%/work) ; \
>> 44: 	set -o pipefail ; \
> 
> Hello Christian, is this an intentional change on this line?

Yes. That `set` leads to:

...
/bin/sh: 2: set: Illegal option -o pipefail
make: *** [../test/junit/JUnitTests.gmk:43: /.../apidiff/build/test/JUnitTests.ok] Error 2
Error: Process completed with exit code 2.

in https://github.com/sormuras/apidiff/actions/runs/11271903419/job/31345716315#step:5:61

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

PR Review Comment: https://git.openjdk.org/apidiff/pull/25#discussion_r1795161355

From jpai at openjdk.org  Thu Oct 10 10:37:24 2024
From: jpai at openjdk.org (Jaikiran Pai)
Date: Thu, 10 Oct 2024 10:37:24 GMT
Subject: RFR: 7903857: Include test run in GitHub Actions workflow [v2]
In-Reply-To: <F8G8tsMzbsmjK1FOvXSCNcK20-mFasDW5g82y_dPrak=.5b583246-fbec-4866-89ab-f5195dd57097@github.com>
References: <XTqyg_RCLkIEIzIopcZK1p-lC1Cc5cJSmRMrexJMgBs=.5deb21b7-6e50-4c93-9d66-38c004ee9793@github.com>
 <F8G8tsMzbsmjK1FOvXSCNcK20-mFasDW5g82y_dPrak=.5b583246-fbec-4866-89ab-f5195dd57097@github.com>
Message-ID: <cI4bRNjJXtdrNfgAx_aZ1iiTW0OTXeO0E0VZ5Rdxa_E=.4ee0cd07-cd6c-4db9-b625-0d39ae400ddf@github.com>

On Thu, 10 Oct 2024 10:19:55 GMT, Christian Stein <cstein at openjdk.org> wrote:

>> Please review this change to run APIDiff's self-tests for each pull request.
>
> Christian Stein has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix `/bin/sh: 2: set: Illegal option -o pipefail` error

Marked as reviewed by jpai (Reviewer).

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

PR Review: https://git.openjdk.org/apidiff/pull/25#pullrequestreview-2359818780

From cstein at openjdk.org  Thu Oct 10 11:18:22 2024
From: cstein at openjdk.org (Christian Stein)
Date: Thu, 10 Oct 2024 11:18:22 GMT
Subject: Integrated: 7903857: Include test run in GitHub Actions workflow
In-Reply-To: <XTqyg_RCLkIEIzIopcZK1p-lC1Cc5cJSmRMrexJMgBs=.5deb21b7-6e50-4c93-9d66-38c004ee9793@github.com>
References: <XTqyg_RCLkIEIzIopcZK1p-lC1Cc5cJSmRMrexJMgBs=.5deb21b7-6e50-4c93-9d66-38c004ee9793@github.com>
Message-ID: <sI-kBBBJ2_qsPtDgTFblsju32vnbxDP3risKXILQgn0=.cc05b820-129e-4935-aa18-6947d09ae9d3@github.com>

On Thu, 10 Oct 2024 10:10:57 GMT, Christian Stein <cstein at openjdk.org> wrote:

> Please review this change to run APIDiff's self-tests for each pull request.

This pull request has now been integrated.

Changeset: de5bb5ad
Author:    Christian Stein <cstein at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/de5bb5ad76a5b841d429e4f347b0fd8e6ee1483c
Stats:     15 lines in 2 files changed: 4 ins; 5 del; 6 mod

7903857: Include test run in GitHub Actions workflow

Reviewed-by: prappo, jpai

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

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

From aph at openjdk.org  Wed Oct 16 13:53:56 2024
From: aph at openjdk.org (Andrew Haley)
Date: Wed, 16 Oct 2024 13:53:56 GMT
Subject: RFR: 7903866: Add an example
Message-ID: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>

It's an example, for example. We need more.

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

Commit messages:
 - Add an example

Changes: https://git.openjdk.org/apidiff/pull/26/files
  Webrev: https://webrevs.openjdk.org/?repo=apidiff&pr=26&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903866
  Stats: 15 lines in 1 file changed: 15 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/apidiff/pull/26.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/26/head:pull/26

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

From jjg at openjdk.org  Thu Oct 17 18:57:48 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 17 Oct 2024 18:57:48 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc
In-Reply-To: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
Message-ID: <EDVvLZkwwJ7BfgO5hYZnTwVG_5qCQ9-MYrVGp6VOqU4=.ead4b8fc-0c13-4023-a0f6-b32ad0a77c73@github.com>

On Wed, 16 Oct 2024 13:48:51 GMT, Andrew Haley <aph at openjdk.org> wrote:

> It's an example, for example. We need more.

src/share/doc/apidiff.md line 509:

> 507:     --jdk-build=/local/baseline-jdk/build/linux-x86_64-server-fastdebug --jdk-docs docs \
> 508:     --api sv \
> 509:     --jdk-build=/local/updated-jdk/build/linux-x86_64-server-fastdebug --jdk-docs docs \

`--jdk-docs` is not an api-specific option, and need only be given once, after all the apis have been specified. And, it is only necessary if there are multiple `*docs*` directories in the `build/.../images` directory -- although it is not wrong to give it anyway, just in case.

Stylistically, I would put the first `--api` option on its own line, to better illustrate the similarity between the two different APIs, but that's a matter of personal style.

src/share/doc/apidiff.md line 511:

> 509:     --jdk-build=/local/updated-jdk/build/linux-x86_64-server-fastdebug --jdk-docs docs \
> 510:     -d out \
> 511:     --compare-api-descriptions true \

It is intended that `--compare-api-descriptions` should default to `true`, although it is not wrong to be explicit.  If you found it to be necessary, that would be worth investigating.

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

PR Review Comment: https://git.openjdk.org/apidiff/pull/26#discussion_r1805271951
PR Review Comment: https://git.openjdk.org/apidiff/pull/26#discussion_r1805274580

From jjg at openjdk.org  Fri Oct 18 20:42:52 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 18 Oct 2024 20:42:52 GMT
Subject: RFR: 7903870: add info about return codes (exit codes) to man page
Message-ID: <cBAg7I7BnvVgD-DrTuPgjQVcVue7afIMdII366j3quo=.64185789-8bd0-40ee-b82b-cb439668207f@github.com>

Please review a small update to the `man` page to document the exit codes for the tool.

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

Commit messages:
 - Merge remote-tracking branch 'upstream/master' into 7903870.exit-status-docs
 - CODETOOLS-7903870: add info about return codes (exit codes) to man page

Changes: https://git.openjdk.org/apidiff/pull/27/files
  Webrev: https://webrevs.openjdk.org/?repo=apidiff&pr=27&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903870
  Stats: 12 lines in 1 file changed: 12 ins; 0 del; 0 mod
  Patch: https://git.openjdk.org/apidiff/pull/27.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/27/head:pull/27

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

From iris at openjdk.org  Fri Oct 18 20:42:52 2024
From: iris at openjdk.org (Iris Clark)
Date: Fri, 18 Oct 2024 20:42:52 GMT
Subject: RFR: 7903870: add info about return codes (exit codes) to man page
In-Reply-To: <cBAg7I7BnvVgD-DrTuPgjQVcVue7afIMdII366j3quo=.64185789-8bd0-40ee-b82b-cb439668207f@github.com>
References: <cBAg7I7BnvVgD-DrTuPgjQVcVue7afIMdII366j3quo=.64185789-8bd0-40ee-b82b-cb439668207f@github.com>
Message-ID: <0NTDkvs3NqYNT74QcBOGTBLHkCIukixtE51QJSWqzCs=.76a2e0df-e42d-4e4d-b56e-4797e6257fc3@github.com>

On Fri, 18 Oct 2024 20:12:45 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small update to the `man` page to document the exit codes for the tool.

Marked as reviewed by iris (Reviewer).

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

PR Review: https://git.openjdk.org/apidiff/pull/27#pullrequestreview-2378916059

From jjg at openjdk.org  Fri Oct 18 20:45:45 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Fri, 18 Oct 2024 20:45:45 GMT
Subject: Integrated: 7903870: add info about return codes (exit codes) to man
 page
In-Reply-To: <cBAg7I7BnvVgD-DrTuPgjQVcVue7afIMdII366j3quo=.64185789-8bd0-40ee-b82b-cb439668207f@github.com>
References: <cBAg7I7BnvVgD-DrTuPgjQVcVue7afIMdII366j3quo=.64185789-8bd0-40ee-b82b-cb439668207f@github.com>
Message-ID: <Byl0237vq4eG8cE7mxulyFaxQhqWk4ZQ_gIG__6GFvk=.d3ae0e2c-e5bc-4093-be36-aaeb1fb95061@github.com>

On Fri, 18 Oct 2024 20:12:45 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a small update to the `man` page to document the exit codes for the tool.

This pull request has now been integrated.

Changeset: 01d14eec
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/01d14eec4a6db7f202d14ea69d2164550d923d70
Stats:     12 lines in 1 file changed: 12 ins; 0 del; 0 mod

7903870: add info about return codes (exit codes) to man page

Reviewed-by: iris

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

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

From aph at openjdk.org  Sun Oct 20 11:38:08 2024
From: aph at openjdk.org (Andrew Haley)
Date: Sun, 20 Oct 2024 11:38:08 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc
In-Reply-To: <EDVvLZkwwJ7BfgO5hYZnTwVG_5qCQ9-MYrVGp6VOqU4=.ead4b8fc-0c13-4023-a0f6-b32ad0a77c73@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
 <EDVvLZkwwJ7BfgO5hYZnTwVG_5qCQ9-MYrVGp6VOqU4=.ead4b8fc-0c13-4023-a0f6-b32ad0a77c73@github.com>
Message-ID: <7Il1RU33nmnB3eA7nNnqi8DGIc8b5x2iqhJOfksCsnQ=.662ca495-ddbf-49e9-a3ff-1e5df7a765d0@github.com>

On Thu, 17 Oct 2024 18:53:28 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> It's an example, for example. We need more.
>
> src/share/doc/apidiff.md line 509:
> 
>> 507:     --jdk-build=/local/baseline-jdk/build/linux-x86_64-server-fastdebug --jdk-docs docs \
>> 508:     --api sv \
>> 509:     --jdk-build=/local/updated-jdk/build/linux-x86_64-server-fastdebug --jdk-docs docs \
> 
> `--jdk-docs` is not an api-specific option, and need only be given once, separately from all the apis. It will apply to all the apis. And, it is only necessary if there are multiple `*docs*` directories in the `build/.../images` directory -- although it is not wrong to give it anyway, just in case.
> 
> Stylistically, I would put the first `--api` option on its own line, to better illustrate the similarity between the two different APIs, but that's a matter of personal style.
> 
> Stylistically, the use of `=` for some options but not others is curious.

I'm finding all of this very hard to follow, mostly because I have no idea how apidiff is supposed to work. I'm just floundering about in the dark, really.

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

PR Review Comment: https://git.openjdk.org/apidiff/pull/26#discussion_r1807782774

From aph at openjdk.org  Sun Oct 20 11:48:50 2024
From: aph at openjdk.org (Andrew Haley)
Date: Sun, 20 Oct 2024 11:48:50 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc [v2]
In-Reply-To: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
Message-ID: <1YAbynniUDt9P1LxhUzaUqO8uxA2GbyGwbs7-zlBqTU=.7947f2d5-258f-4687-b799-cce85f2e5902@github.com>

> It's an example, for example. We need more.

Andrew Haley has updated the pull request incrementally with one additional commit since the last revision:

  Add an example

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

Changes:
  - all: https://git.openjdk.org/apidiff/pull/26/files
  - new: https://git.openjdk.org/apidiff/pull/26/files/1cffc32a..74f197f9

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

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

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

From aph at openjdk.org  Sun Oct 20 11:48:50 2024
From: aph at openjdk.org (Andrew Haley)
Date: Sun, 20 Oct 2024 11:48:50 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc [v2]
In-Reply-To: <EDVvLZkwwJ7BfgO5hYZnTwVG_5qCQ9-MYrVGp6VOqU4=.ead4b8fc-0c13-4023-a0f6-b32ad0a77c73@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
 <EDVvLZkwwJ7BfgO5hYZnTwVG_5qCQ9-MYrVGp6VOqU4=.ead4b8fc-0c13-4023-a0f6-b32ad0a77c73@github.com>
Message-ID: <qJFL4AMS9CwhYuGN2rb9l0Ov0ofVZAJYFnRIvwPaeJc=.a8bb29af-f5ad-4f82-80d1-9895e65509eb@github.com>

On Thu, 17 Oct 2024 18:55:28 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> It is intended that `--compare-api-descriptions` should default to `true`, although it is not wrong to be explicit. If you found it to be necessary, that would be worth investigating.

I find it very hard to understand the ifs and buts in the description of this option, and @alanbateman used the option this way. Please advise me to leave it in or take it out.

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

PR Review Comment: https://git.openjdk.org/apidiff/pull/26#discussion_r1807789458

From aph at openjdk.org  Sun Oct 20 13:33:40 2024
From: aph at openjdk.org (Andrew Haley)
Date: Sun, 20 Oct 2024 13:33:40 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc [v3]
In-Reply-To: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
Message-ID: <RAF30PqGXHFA-zJ3Qc0okhdWNP2zgdjiwgpPKor7LxQ=.f54e144e-875c-4163-b2e7-f03e34ce0a56@github.com>

> It's an example, for example. We need more.

Andrew Haley has updated the pull request incrementally with one additional commit since the last revision:

  Add an example

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

Changes:
  - all: https://git.openjdk.org/apidiff/pull/26/files
  - new: https://git.openjdk.org/apidiff/pull/26/files/74f197f9..249c1bb7

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

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

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

From alanb at openjdk.org  Sun Oct 20 15:44:33 2024
From: alanb at openjdk.org (Alan Bateman)
Date: Sun, 20 Oct 2024 15:44:33 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc [v3]
In-Reply-To: <qJFL4AMS9CwhYuGN2rb9l0Ov0ofVZAJYFnRIvwPaeJc=.a8bb29af-f5ad-4f82-80d1-9895e65509eb@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
 <EDVvLZkwwJ7BfgO5hYZnTwVG_5qCQ9-MYrVGp6VOqU4=.ead4b8fc-0c13-4023-a0f6-b32ad0a77c73@github.com>
 <qJFL4AMS9CwhYuGN2rb9l0Ov0ofVZAJYFnRIvwPaeJc=.a8bb29af-f5ad-4f82-80d1-9895e65509eb@github.com>
Message-ID: <EivcjE3EH9S5uwGk2mNOHRv1sji3qz-L7f44qTlBGyQ=.f1fda779-c2ba-46df-b9a5-cf4dd45925be@github.com>

On Sun, 20 Oct 2024 11:43:04 GMT, Andrew Haley <aph at openjdk.org> wrote:

>> src/share/doc/apidiff.md line 511:
>> 
>>> 509:     --jdk-build=/local/updated-jdk/build/linux-x86_64-server-fastdebug --jdk-docs docs \
>>> 510:     -d out \
>>> 511:     --compare-api-descriptions true \
>> 
>> It is intended that `--compare-api-descriptions` should default to `true`, although it is not wrong to be explicit.  If you found it to be necessary, that would be worth investigating.
>
>> It is intended that `--compare-api-descriptions` should default to `true`, although it is not wrong to be explicit. If you found it to be necessary, that would be worth investigating.
> 
> I find it very hard to understand the ifs and buts in the description of this option, and @alanbateman used the option this way. Please advise me to leave it in or take it out.

I used it in the example I gave Andrew to be explicit, no other reason. In any case, I agree we need some recipes in the docs. If they include a path to a build then probably better to use a path to a release build as someone is unlikely to be using fast debug build for this kinda of thing.

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

PR Review Comment: https://git.openjdk.org/apidiff/pull/26#discussion_r1807875051

From jjg at openjdk.org  Mon Oct 21 03:53:31 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Mon, 21 Oct 2024 03:53:31 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc [v3]
In-Reply-To: <EivcjE3EH9S5uwGk2mNOHRv1sji3qz-L7f44qTlBGyQ=.f1fda779-c2ba-46df-b9a5-cf4dd45925be@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
 <EDVvLZkwwJ7BfgO5hYZnTwVG_5qCQ9-MYrVGp6VOqU4=.ead4b8fc-0c13-4023-a0f6-b32ad0a77c73@github.com>
 <qJFL4AMS9CwhYuGN2rb9l0Ov0ofVZAJYFnRIvwPaeJc=.a8bb29af-f5ad-4f82-80d1-9895e65509eb@github.com>
 <EivcjE3EH9S5uwGk2mNOHRv1sji3qz-L7f44qTlBGyQ=.f1fda779-c2ba-46df-b9a5-cf4dd45925be@github.com>
Message-ID: <Ive6uNBakJ9iu_F4RfqK7bgpAmjkNfpOgdn8-qc7wdo=.97902d0e-a735-43a4-b360-0adb69fd04fb@github.com>

On Sun, 20 Oct 2024 15:40:47 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>>> It is intended that `--compare-api-descriptions` should default to `true`, although it is not wrong to be explicit. If you found it to be necessary, that would be worth investigating.
>> 
>> I find it very hard to understand the ifs and buts in the description of this option, and @alanbateman used the option this way. Please advise me to leave it in or take it out.
>
> I used it in the example I gave Andrew to be explicit, no other reason. In any case, I agree we need some recipes in the docs. If they include a path to a build then probably better to use a path to a release build as someone is unlikely to be using fast debug build for this kinda of thing.

@AlanBateman @theRealAph 
I will look to create more examples.

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

PR Review Comment: https://git.openjdk.org/apidiff/pull/26#discussion_r1808067426

From aph at openjdk.org  Tue Oct 22 12:35:38 2024
From: aph at openjdk.org (Andrew Haley)
Date: Tue, 22 Oct 2024 12:35:38 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc [v3]
In-Reply-To: <EivcjE3EH9S5uwGk2mNOHRv1sji3qz-L7f44qTlBGyQ=.f1fda779-c2ba-46df-b9a5-cf4dd45925be@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
 <EDVvLZkwwJ7BfgO5hYZnTwVG_5qCQ9-MYrVGp6VOqU4=.ead4b8fc-0c13-4023-a0f6-b32ad0a77c73@github.com>
 <qJFL4AMS9CwhYuGN2rb9l0Ov0ofVZAJYFnRIvwPaeJc=.a8bb29af-f5ad-4f82-80d1-9895e65509eb@github.com>
 <EivcjE3EH9S5uwGk2mNOHRv1sji3qz-L7f44qTlBGyQ=.f1fda779-c2ba-46df-b9a5-cf4dd45925be@github.com>
Message-ID: <OiDTiCANmCyUAR87t5m7PYjcOptIFqSaubMUBhxbW_k=.b4a445ee-caa7-4072-a451-dbc89c7966d2@github.com>

On Sun, 20 Oct 2024 15:40:47 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>>> It is intended that `--compare-api-descriptions` should default to `true`, although it is not wrong to be explicit. If you found it to be necessary, that would be worth investigating.
>> 
>> I find it very hard to understand the ifs and buts in the description of this option, and @alanbateman used the option this way. Please advise me to leave it in or take it out.
>
> I used it in the example I gave Andrew to be explicit, no other reason. In any case, I agree we need some recipes in the docs. If they include a path to a build then probably better to use a path to a release build as someone is unlikely to be using fast debug build for this kinda of thing.

> @AlanBateman @theRealAph I will look to create more examples. 

Will you approve this one, please?

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

PR Review Comment: https://git.openjdk.org/apidiff/pull/26#discussion_r1810638629

From jjg at openjdk.org  Tue Oct 22 22:05:16 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 22 Oct 2024 22:05:16 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc [v3]
In-Reply-To: <RAF30PqGXHFA-zJ3Qc0okhdWNP2zgdjiwgpPKor7LxQ=.f54e144e-875c-4163-b2e7-f03e34ce0a56@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
 <RAF30PqGXHFA-zJ3Qc0okhdWNP2zgdjiwgpPKor7LxQ=.f54e144e-875c-4163-b2e7-f03e34ce0a56@github.com>
Message-ID: <_RVA6a2KYrobp094uIwAflPVpBTMjinKJB09qod5pTM=.2bf75d21-5156-46ea-bae7-e84e4cfa84f2@github.com>

On Sun, 20 Oct 2024 13:33:40 GMT, Andrew Haley <aph at openjdk.org> wrote:

>> It's an example, for example. We need more.
>
> Andrew Haley has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add an example

My intent is to develop a section in the doc containing real, verified examples (backed up by some form of test script.)  My thought is to start with the smallest command-line for testing 2 JDK builds, and to build up from there. I'd like to illustrate that the command line is not that complicated!  You should have seen it before the `--jdk-build` option was introduced.

That all being said, it will take a (short) while to develop that update, so I'll approve this example as either an interim measure or as part of what is to come.

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

Marked as reviewed by jjg (Reviewer).

PR Review: https://git.openjdk.org/apidiff/pull/26#pullrequestreview-2386473901

From aph at openjdk.org  Wed Oct 23 10:04:25 2024
From: aph at openjdk.org (Andrew Haley)
Date: Wed, 23 Oct 2024 10:04:25 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc [v3]
In-Reply-To: <_RVA6a2KYrobp094uIwAflPVpBTMjinKJB09qod5pTM=.2bf75d21-5156-46ea-bae7-e84e4cfa84f2@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
 <RAF30PqGXHFA-zJ3Qc0okhdWNP2zgdjiwgpPKor7LxQ=.f54e144e-875c-4163-b2e7-f03e34ce0a56@github.com>
 <_RVA6a2KYrobp094uIwAflPVpBTMjinKJB09qod5pTM=.2bf75d21-5156-46ea-bae7-e84e4cfa84f2@github.com>
Message-ID: <vsfpESfR70WL9cNJ31o1JxAumV4Uin5PGRREDHM2Lyw=.dece8cc1-0f58-419a-b8d1-c0c664936b11@github.com>

On Tue, 22 Oct 2024 22:02:54 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> My intent is to develop a section in the doc containing real, verified examples (backed up by some form of test script.) My thought is to start with the smallest command-line for testing 2 JDK builds, and to build up from there. I'd like to illustrate that the command line is not that complicated! You should have seen it before the `--jdk-build` option was introduced.
> 
> That all being said, it will take a (short) while to develop that update, so I'll approve this example as either an interim measure or as part of what is to come.

OK, thanks. Regardless of other sections in the docs with real, verified examples, it's still a really good idea to have a few simple examples at the end of the man page. Such examples help by effectively tying the long list of options to something more concrete.

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

PR Comment: https://git.openjdk.org/apidiff/pull/26#issuecomment-2431583384

From duke at openjdk.org  Wed Oct 23 10:04:26 2024
From: duke at openjdk.org (duke)
Date: Wed, 23 Oct 2024 10:04:26 GMT
Subject: RFR: 7903866: apidiff: add an example to the doc [v3]
In-Reply-To: <RAF30PqGXHFA-zJ3Qc0okhdWNP2zgdjiwgpPKor7LxQ=.f54e144e-875c-4163-b2e7-f03e34ce0a56@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
 <RAF30PqGXHFA-zJ3Qc0okhdWNP2zgdjiwgpPKor7LxQ=.f54e144e-875c-4163-b2e7-f03e34ce0a56@github.com>
Message-ID: <pUQ9MLI5pQKSTGE6gr6ENKwQQvR9LgrWohKzmxOEmmI=.c1f86a51-53f2-4ca1-8cc9-7cbde4235f29@github.com>

On Sun, 20 Oct 2024 13:33:40 GMT, Andrew Haley <aph at openjdk.org> wrote:

>> It's an example, for example. We need more.
>
> Andrew Haley has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Add an example

@theRealAph 
Your change (at version 249c1bb755dcb61ff4063d991e2b31a6bf8a9719) is now ready to be sponsored by a Committer.

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

PR Comment: https://git.openjdk.org/apidiff/pull/26#issuecomment-2431585484

From aph at openjdk.org  Wed Oct 23 14:22:21 2024
From: aph at openjdk.org (Andrew Haley)
Date: Wed, 23 Oct 2024 14:22:21 GMT
Subject: Integrated: 7903866: apidiff: add an example to the doc
In-Reply-To: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
References: <Qc3c7vFkA1-jTmE6hCZqFh_R_avlbI6BU1-wmKpOSWA=.3123b992-9178-4a75-b42f-ce2e95536dcf@github.com>
Message-ID: <PjCMQNyscdpJiNRnm0XU4KQi1ZZQvM0m3mbm4gp9Z9U=.9b79b9e7-8adf-498b-8596-a516aa63d63d@github.com>

On Wed, 16 Oct 2024 13:48:51 GMT, Andrew Haley <aph at openjdk.org> wrote:

> It's an example, for example. We need more.

This pull request has now been integrated.

Changeset: 3495601d
Author:    Andrew Haley <aph at openjdk.org>
Committer: Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/3495601dea2db46ce2605f3c1b6716669bd4181f
Stats:     17 lines in 1 file changed: 17 ins; 0 del; 0 mod

7903866: apidiff: add an example to the doc

Reviewed-by: jjg

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

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

From jjg at openjdk.org  Thu Oct 24 23:56:44 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Thu, 24 Oct 2024 23:56:44 GMT
Subject: RFR: 7903876: Improve the man page, with (more) examples
Message-ID: <_82ap3uYDc4O3Gt0BKaf4yK9NNusJauTDjpNKQxEbug=.df2c5e72-f068-4de2-b3a5-cfb401465d3a@github.com>

Please review an update to the main documentation page for the `apidiff` tool. The updates are primarily clarifications and examples, intended to reduce some of the recent confusion about using the tool.   As well as clarification and examples throughout the page, two more full examples are given at the end. These examples have been tested with scripts.  They are meant to be indicative of what one might use to create a diff report for a CSR submission. 

The generated HTML for the page can be seen here: https://cr.openjdk.org/~jjg/7903876/doc/apidiff.html

For the record, the scripts used to test the examples are as follows:


*** play/apidiff-examples/apidiff-1.sh
#!/bin/bash

JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff

PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
apidiff \
    --api jdk24 --jdk-build build/baseline \
    --api 8330183 --jdk-build build/macosx-aarch64-server-release  \
    --include java.compiler/** \
    --output-directory build/apidiff

*** play/apidiff-examples/apidiff-2.sh
#!/bin/bash

JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff

PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
apidiff \
    --api jdk24 --jdk-build build/baseline --label "The baseline for the changes"\
    --api 8330183 --jdk-build build/macosx-aarch64-server-release --label "Add SourceVersion.RELEASE_24" \
    --include java.compiler/** \
    --output-directory build/apidiff \
    --compare-api-descriptions true \
    --jdk-docs docs \
    --info-text top="This proposal is not yet final" \
    --title "Diffs for JDK-8330183 CSR" \
    --description "Generated by $USER at $(date -u)"

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

Commit messages:
 - CODETOOLS-7903876: Improve the man page, with (more) examples
 - Merge remote-tracking branch 'upstream/master' into 7903876.update-man-page
 - Merge remote-tracking branch 'upstream/master' into 7903870.exit-status-docs
 - CODETOOLS-7903870: add info about return codes (exit codes) to man page

Changes: https://git.openjdk.org/apidiff/pull/28/files
  Webrev: https://webrevs.openjdk.org/?repo=apidiff&pr=28&range=00
  Issue: https://bugs.openjdk.org/browse/CODETOOLS-7903876
  Stats: 199 lines in 3 files changed: 160 ins; 6 del; 33 mod
  Patch: https://git.openjdk.org/apidiff/pull/28.diff
  Fetch: git fetch https://git.openjdk.org/apidiff.git pull/28/head:pull/28

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

From iris at openjdk.org  Sun Oct 27 18:06:17 2024
From: iris at openjdk.org (Iris Clark)
Date: Sun, 27 Oct 2024 18:06:17 GMT
Subject: RFR: 7903876: Improve the man page, with (more) examples
In-Reply-To: <_82ap3uYDc4O3Gt0BKaf4yK9NNusJauTDjpNKQxEbug=.df2c5e72-f068-4de2-b3a5-cfb401465d3a@github.com>
References: <_82ap3uYDc4O3Gt0BKaf4yK9NNusJauTDjpNKQxEbug=.df2c5e72-f068-4de2-b3a5-cfb401465d3a@github.com>
Message-ID: <qZgKnmRRgxjtVCD3pKmIVhBTQywhtrqPqhN2cLpnSN4=.b820c385-0d1e-489e-ae08-b1cf66ec96b0@github.com>

On Thu, 24 Oct 2024 23:52:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review an update to the main documentation page for the `apidiff` tool. The updates are primarily clarifications and examples, intended to reduce some of the recent confusion about using the tool.   As well as clarification and examples throughout the page, two more full examples are given at the end. These examples have been tested with scripts.  They are meant to be indicative of what one might use to create a diff report for a CSR submission. 
> 
> The generated HTML for the page can be seen here: https://cr.openjdk.org/~jjg/7903876/doc/apidiff.html
> 
> For the record, the scripts used to test the examples are as follows:
> 
> 
> *** play/apidiff-examples/apidiff-1.sh
> #!/bin/bash
> 
> JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
> APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff
> 
> PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
> apidiff \
>     --api jdk24 --jdk-build build/baseline \
>     --api 8330183 --jdk-build build/macosx-aarch64-server-release  \
>     --include java.compiler/** \
>     --output-directory build/apidiff
> 
> *** play/apidiff-examples/apidiff-2.sh
> #!/bin/bash
> 
> JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
> APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff
> 
> PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
> apidiff \
>     --api jdk24 --jdk-build build/baseline --label "The baseline for the changes"\
>     --api 8330183 --jdk-build build/macosx-aarch64-server-release --label "Add SourceVersion.RELEASE_24" \
>     --include java.compiler/** \
>     --output-directory build/apidiff \
>     --compare-api-descriptions true \
>     --jdk-docs docs \
>     --info-text top="This proposal is not yet final" \
>     --title "Diffs for JDK-8330183 CSR" \
>     --description "Generated by $USER at $(date -u)"

Great man page expansion!  I like the additional examples (particularly the one for CSRs).  I'm sure there are several other common cases which could use examples.

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

Marked as reviewed by iris (Reviewer).

PR Review: https://git.openjdk.org/apidiff/pull/28#pullrequestreview-2397602583

From jjg at openjdk.org  Tue Oct 29 16:19:36 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 29 Oct 2024 16:19:36 GMT
Subject: RFR: 7903876: Improve the man page, with (more) examples [v2]
In-Reply-To: <_82ap3uYDc4O3Gt0BKaf4yK9NNusJauTDjpNKQxEbug=.df2c5e72-f068-4de2-b3a5-cfb401465d3a@github.com>
References: <_82ap3uYDc4O3Gt0BKaf4yK9NNusJauTDjpNKQxEbug=.df2c5e72-f068-4de2-b3a5-cfb401465d3a@github.com>
Message-ID: <yXC9arpnTGt4KwjN5m7k_dzzZzLIl-k9Q1EjMLdNeTA=.4cec8855-43a7-4fc1-a7d4-73a9ed258cc1@github.com>

> Please review an update to the main documentation page for the `apidiff` tool. The updates are primarily clarifications and examples, intended to reduce some of the recent confusion about using the tool.   As well as clarification and examples throughout the page, two more full examples are given at the end. These examples have been tested with scripts.  They are meant to be indicative of what one might use to create a diff report for a CSR submission. 
> 
> The generated HTML for the page can be seen here: https://cr.openjdk.org/~jjg/7903876/doc/apidiff.html
> 
> For the record, the scripts used to test the examples are as follows:
> 
> 
> *** play/apidiff-examples/apidiff-1.sh
> #!/bin/bash
> 
> JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
> APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff
> 
> PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
> apidiff \
>     --api jdk24 --jdk-build build/baseline \
>     --api 8330183 --jdk-build build/macosx-aarch64-server-release  \
>     --include java.compiler/** \
>     --output-directory build/apidiff
> 
> *** play/apidiff-examples/apidiff-2.sh
> #!/bin/bash
> 
> JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
> APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff
> 
> PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
> apidiff \
>     --api jdk24 --jdk-build build/baseline --label "The baseline for the changes"\
>     --api 8330183 --jdk-build build/macosx-aarch64-server-release --label "Add SourceVersion.RELEASE_24" \
>     --include java.compiler/** \
>     --output-directory build/apidiff \
>     --compare-api-descriptions true \
>     --jdk-docs docs \
>     --info-text top="This proposal is not yet final" \
>     --title "Diffs for JDK-8330183 CSR" \
>     --description "Generated by $USER at $(date -u)"

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

  add note about quoting patterns, and other clarifications

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

Changes:
  - all: https://git.openjdk.org/apidiff/pull/28/files
  - new: https://git.openjdk.org/apidiff/pull/28/files/22ccba28..3d316243

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

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

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

From jjg at openjdk.org  Tue Oct 29 18:51:23 2024
From: jjg at openjdk.org (Jonathan Gibbons)
Date: Tue, 29 Oct 2024 18:51:23 GMT
Subject: Integrated: 7903876: Improve the man page, with (more) examples
In-Reply-To: <_82ap3uYDc4O3Gt0BKaf4yK9NNusJauTDjpNKQxEbug=.df2c5e72-f068-4de2-b3a5-cfb401465d3a@github.com>
References: <_82ap3uYDc4O3Gt0BKaf4yK9NNusJauTDjpNKQxEbug=.df2c5e72-f068-4de2-b3a5-cfb401465d3a@github.com>
Message-ID: <fssuPCpKgMHduoEJAzCU-lb_JMFdWyTmbXFNZpf2q6s=.2aabbf38-bff4-4177-92f9-2c418bcac974@github.com>

On Thu, 24 Oct 2024 23:52:04 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review an update to the main documentation page for the `apidiff` tool. The updates are primarily clarifications and examples, intended to reduce some of the recent confusion about using the tool.   As well as clarification and examples throughout the page, two more full examples are given at the end. These examples have been tested with scripts.  They are meant to be indicative of what one might use to create a diff report for a CSR submission. 
> 
> The generated HTML for the page can be seen here: https://cr.openjdk.org/~jjg/7903876/doc/apidiff.html
> 
> For the record, the scripts used to test the examples are as follows:
> 
> 
> *** play/apidiff-examples/apidiff-1.sh
> #!/bin/bash
> 
> JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
> APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff
> 
> PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
> apidiff \
>     --api jdk24 --jdk-build build/baseline \
>     --api 8330183 --jdk-build build/macosx-aarch64-server-release  \
>     --include java.compiler/** \
>     --output-directory build/apidiff
> 
> *** play/apidiff-examples/apidiff-2.sh
> #!/bin/bash
> 
> JAVA_HOME=$HOME/OpenJDK/jdk/jdk.ref/build/macosx-aarch64-server-release/images/jdk
> APIDIFF_HOME=$HOME/OpenJDK/difftools/apidiff.ref/build/images/apidiff
> 
> PATH=$JAVA_HOME/bin:$APIDIFF_HOME/bin:$PATH
> apidiff \
>     --api jdk24 --jdk-build build/baseline --label "The baseline for the changes"\
>     --api 8330183 --jdk-build build/macosx-aarch64-server-release --label "Add SourceVersion.RELEASE_24" \
>     --include java.compiler/** \
>     --output-directory build/apidiff \
>     --compare-api-descriptions true \
>     --jdk-docs docs \
>     --info-text top="This proposal is not yet final" \
>     --title "Diffs for JDK-8330183 CSR" \
>     --description "Generated by $USER at $(date -u)"

This pull request has now been integrated.

Changeset: 1dbbcb5b
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/apidiff/commit/1dbbcb5b87f75edcbdf9caf7314c56bce1a110df
Stats:     202 lines in 3 files changed: 163 ins; 6 del; 33 mod

7903876: Improve the man page, with (more) examples

Reviewed-by: iris

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

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