On Sat, 9 Jul 2022 01:55:32 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
> Please review a moderately simple fix to clean up (as in _remove_!) > `CommentHelper.getText` and friends/overloads. > > This is moderately simple, because most of the heavy lifting was done in > [JDK-8288699](https://bugs.openjdk.org/browse/JDK-8288624), to clean up > `commentTagsToContent`. > > The uses of `CommentHelper.getText` can generally be replaced by either > `commentTagsToContent` or just `DocTree.toString()`. > > Two bugs were uncovered as a result of the cleanup. These are described in > detail in a comment with screenshots in the [bug > report](https://bugs.openjdk.org/browse/JDK-8288624?focusedCommentId=14508488&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14508488) > > > Fixing the `see-list-long` bug was a direct reason to cleanup > `commentTagsToContent`. The fix here could maybe be further improved by > writing a simple visitor or (preferably) a pattern-switch when that is a > standard feature of the language. > > Fixing the other bug was mostly an accidental side-effect of just using > `commentTagsToContent` instead of `CommentHelper.getText`, since the tags now > get interpreted instead of ignored. However, one tweak was necessary. > The doc comments for serialization info end up in `serialized-form.html` and > not in the primary file for the enclosing type. > This means they should not undergo the standard `redirectRelativeLinks` > treatment. Links using `{@link...}` are not affected, but links using > explicit `<a href="relative-link">...</a>` are affected. Ideally, we should > not be using such relative links in the JDK API documentation, but there are > too many to change/fix as part of this work. The fix, for now, is to add a > new overload to `commentTagsToContent` that provides the ability to disable > the call to `redirectRelativeLinks` when needed ... that is, when generating > `serialized-form.html`. > > Initially, the goal was just a cleanup fix with no change to tests. The work > has been tested by comparing generated docs before and after this work. There > are a number of instances of differences in the generated docs, but all are > instances of the bugs described above ... either the `see-list-long` bug, or > the change that inline doc comment tags are now interpretedin places where > they were previously ignored. All existing tests continue to work without > modification; new tests have been added for the fixes for the bugs that were > discovered in the course of this work. This pull request has now been integrated. Changeset: 572c14ef Author: Jonathan Gibbons <j...@openjdk.org> URL: https://git.openjdk.org/jdk/commit/572c14efc67860e75edaa50608b4c61aec5997da Stats: 406 lines in 12 files changed: 209 ins; 169 del; 28 mod 8288624: Cleanup CommentHelper.getText0 Reviewed-by: hannesw ------------- PR: https://git.openjdk.org/jdk/pull/9438
