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

[Kumar Srinivasan]

Hi Jon,


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


Hi Kumar,

It's hard to use preview features in javac/javadoc because of the bootstrap N-1 problem,
but yes, DocCommentInfo could be a record; also Utils.Pair is only used in option decoding
for `-linkoffline` and could/should be moved there.


Ah yes, I thought Records was already released in 14, mea culpa.

I'd also like the review the use of 3 separate maps to get doc comment info from elements:
there's one down in com.sun.source world, one in CommentUtils and another in Utils.


I agree, this needs to be looked at, it was quite a task to get rid of the old DocComment structures.
I think consolidating Utils and CommentUtils should be doable, since it will be local to the doclet.

Kumar


-- Jon


On 6/9/20 1:43 PM, Kumar Srinivasan wrote:
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%7Ce03e0a8bfc004e521dce08d80cbf2bc2%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637273362501031348&sdata=bxiVmJaJThE5L7GrWBPr46ZCxl%2FM%2FDL%2BLwpH89BuP9o%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%7Ce03e0a8bfc004e521dce08d80cbf2bc2%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637273362501031348&sdata=HaemaqjfScZxsv4VporsuTy7vJUx0epsa%2BrxbNpxsfg%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%7Ce03e0a8bfc004e521dce08d80cbf2bc2%7Cb39138ca3cee4b4aa4d6cd83d9dd62f0%7C0%7C0%7C637273362501041343&sdata=kiio1sauTn6OgC6LorzuaTpFp1IpvD4z276B1sJP7Vc%3D&reserved=0>


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