On Wed, 2 Aug 2023 13:20:53 GMT, Pavel Rappo <pra...@openjdk.org> wrote:
>> Please review a medium size update that is the last in the series of recent
>> updates to refactor and simplify builders and writers.
>>
>> Having cleared away some of the earlier obfuscation, it becomes clear that
>> all subtypes of `HtmlDocletWriter` generate pages for the overall
>> documentation, and so a new abstract method `buildPage` is introduced to
>> make that more obvious. This resulted in renaming some existing `build`
>> methods and/or removing some static `generate` methods, though some of the
>> more complex ones still remain.
>>
>> In addition, all writers are now generally created by the `WriterFactory`
>> class, providing an extension point should it ever be needed to subtype
>> these classes. The methods on `WriterFactory` return the appropriate
>> supertype (`HtmlDocletWriter` or `AbstractMemberWriter`) thus enforcing the
>> use of the standard abstract methods that are now available.
>>
>> There is also some cleanup to some of the member writers, including
>> introducing more abstract methods to define common behavior, simplifying
>> some method signatures, removing unused code, and providing documentation
>> comments.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SummaryListWriter.java
> line 50:
>
>> 48: * such as deprecated elements, preview elements, and so on.
>> 49: *
>> 50: * @param <B> a builder, to build the specific summary information to be
>> written
>
> Rewrite the sentence for clarity.
Propose the following:
/**
* Base class for generating a summary page that lists elements with a common
characteristic,
* such as deprecated elements, preview elements, and so on.
*
* Note: the use of "Summary" in this context is distinct from the use of
"summary" in the
* context of {@link AbstractMemberWriter#buildSummary(Content)}.
*
* @param <B> a builder, to determine the elements to be included in the summary
*/
```
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/15114#discussion_r1282402406
