RFR: JDK-8312201: Cleanup common behavior in "page writers" and "member writers"

[Pavel Rappo]

On Thu, 27 Jul 2023 01:44:36 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> Please review a medium change that is a follow-up to recent work to cleanup the builders and writers in the doclet.
> 
> This change is primarily focussed on cleaning up the code to generate summary tables for each kind of member. The bulk of the code is moved from `ClassWriter` to `AbstractMemberWriter`, with just a top-level loop remaining in `ClassWriter` to iterate over the different kinds of members. In addition, there is some cleanup in `WriterFactory`, renaming the factory methods and ensuring that those that are declared are used.
> 
> One result of the cleanup is that each member writer now defines and provides two methods, `buildSummary` and `buildDetails` that each create content to go on the page of the enclosing type.
> 
> This work uncovered two issues which are _not_ addressed here, and which may be addressed in future work.
> 
> 1. There is a discrepancy between the lists of `VMT.Kind` used in `AbstractMemberWriter` (for the complete lists used to generate pages and the lists of `VMT.Kind` defined in `VMT.Kind` itself, which are indirectly used to generate entries in the sub-navbar for the pages of type elements.  Those lists (defined as `Set`s, indirectly rely on the order in which the `VMT.Kind` members are declared, although the order itself is not specified.
> 
> 2. There is an inconsistency in the subtypes of `HtmlDocletWriter`, which all generate pages, as to how those classes are invoked. It is about 50/50 whether the classes declare a `build()` method to be called from outside, or whether the classes declare a `static void generate()` method to be used instead.
> 
> --
> 
> The initial commit contains two changes to tests, copied from PR #15046.  These changes will go away once that PR is approved, integrated and merged with this work.

Mismatching bug id and the test changes suggest an unclean split between this PR and https://git.openjdk.org/jdk/pull/15046

The tests should belong to the latter PR.

test/langtools/jdk/javadoc/doclet/testAnnotationTypes/TestAnnotationTypes.java line 27:

> 25:  * @test
> 26:  * @bug      4973609 8015249 8025633 8026567 6469561 8071982 8162363 8182765 8223364
> 27:              8242056 8261976 8223358 8313204

Ditto for the bug id.

test/langtools/jdk/javadoc/doclet/testOverriddenMethods/TestOverrideMethods.java line 26:

> 24: /*
> 25:  * @test
> 26:  * @bug 8157000 8192850 8182765 8223607 8261976 8281376 8313204

That bug id differs from that of this PR; typo?

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

PR Review: https://git.openjdk.org/jdk/pull/15049#pullrequestreview-1549640132
PR Review Comment: https://git.openjdk.org/jdk/pull/15049#discussion_r1276153457
PR Review Comment: https://git.openjdk.org/jdk/pull/15049#discussion_r1276152573