RFR: JDK-8242607 -Xdoclint doesn't report missing/unexpected comments

[Kumar Srinivasan]

Hi Jon,

Looks good.

Out of curiosity, is it worthwhile to replace DocCommentInfo with  Record ?

There may be other places where these Pair-like containers were introduced in the doclet and javadoc tool.

Kumar


On Jun 8, 2020, at 9:48 PM, Jonathan Gibbons <jonathan.gibbons at oracle.com<mailto:jonathan.gibbons at oracle.com>> wrote:


Please review a partial fix for this issue, which is about different doclint results
when invoking doclint from javac and javadoc.

The reason for the partial fix is explained here:
https://bugs.openjdk.java.net/browse/JDK-8242607?focusedCommentId=14344614&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14344614<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fbugs.openjdk.java.net%2Fbrowse%2FJDK-8242607%3FfocusedCommentId%3D14344614%26page%3Dcom.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel%23comment-14344614&data=02%7C01%7Ckusrinivasan%40vmware.com%7Ce4ec10b256564856b91308d80c30d33a%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637272751137162204&sdata=%2FrAljZaMR3oCwy2CX9CjgzIGRMmsgf6DpHRUjhmrM5o%3D&reserved=0>

Within the patch, the primary change is the restructuring of the if-statement at about line 2706
in Utils.java. Specifically, the call

        configuration.workArounds.runDocLint(path);

is moved outside of the test

        if (docCommentTree != null


which is the root cause of the error.

At the same time, the patch includes a minor cleanup to rename the `DocCommentDuo`
class to a slightly more abstract name `DocCommentInfo`. The old `DocCommentDuo`
inappropriately reflects some of the historical origins of the name. The change percolates
into some local variable names and member names as well.  I also tried to cleanup some
of the comments in this area, without changing functionality. The net result is a
perceived need for more cleanup, including functionality cleanup, in another changeset.

-- Jon


JBS: https://bugs.openjdk.java.net/browse/JDK-8242607<https://nam04.safelinks.protection.outlook.com/?url=https%3A%2F%2Fbugs.openjdk.java.net%2Fbrowse%2FJDK-8242607&data=02%7C01%7Ckusrinivasan%40vmware.com%7Ce4ec10b256564856b91308d80c30d33a%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637272751137162204&sdata=Ik7RRt7SlnoBDFp0eVjK0KmB2SEnWmQkhrffeR3ksiE%3D&reserved=0>
Webrev: http://cr.openjdk.java.net/~jjg/8242607/webrev.00/<https://nam04.safelinks.protection.outlook.com/?url=http:%2F%2Fcr.openjdk.java.net%2F~jjg%2F8242607%2Fwebrev.00%2F&data=02%7C01%7Ckusrinivasan%40vmware.com%7Ce4ec10b256564856b91308d80c30d33a%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637272751137172199&sdata=k9B9Vmir017EYYpJ%2BK%2B4LzQRXgjpm6fkKRwQrDr%2BYFA%3D&reserved=0>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200609/1df12fbc/attachment.htm>