On Wed, 12 Jul 2023 23:05:48 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
>> Please review a medium-substantial cleanup of the internal `Taglet` world.
>>
>> The initial motivation was to move tag-specific functionality from
>> `TagletWriter[Impl]` to HTML-specific new subtypes of the individual
>> `Taglet` classes, so that taglets are now better represented by a
>> format-neutral base type and an HTML-specific subtype. The new subtypes are
>> collected in a new `formats.html.taglets` package, and for the most part,
>> they are accessed via their `Taglet` API.
>>
>> A secondary motivation is to clean up handling of inline tags. Not all
>> inline tags had corresponding taglets: most notably, `{@link}` was not
>> modeled by a taglet. Introducing `[Html]LinkTaglet` allowed more code to
>> move from `TagletWriterImpl` to `HtmlLinkTaglet` ... and `HtmlSeeTaglet` and
>> `HtmlSnippetTablet` now delegate to `HtmlLinkTaglet` to generate links.
>> Also, in `HtmlDocletWriter` a notable visitor, in `commentTags toContent`
>> had explicit `visit...` methods that effectively duplicated the
>> functionality of `defaultAction`, so those methods can be and have been
>> deleted.
>>
>> Taglets used to be stateless, even though they are generally created once
>> per doclet. (That was fixed, now, they _are_ created just once per doclet.)
>> They now contain the standard long-lived members, like `configuration`,
>> `utils`, `messages`, etc for the convenience of subtypes.
>> `TagletWriterImpl.Context` has always been effectively format-neutral and
>> has been moved up to `Taglet.Context`.
>>
>> It had been hoped to replace the `TagletWriter` parameter to
>> `Taglet::getInlineTagOutput` and `Taglet::getAllBlockTagOutput` with
>> `Taglet.Context` perhaps calling with a HTML-subtype instance. But there is
>> still enough useful functionality on `TagletWriter` that that is not
>> practical at this time.
>>
>> Taglets vary greatly in size, from small/trivial to large/complex. While it
>> might seem unnecessary to use top-level classes for the small case, it seems
>> better to go with a consistent uniform design rather than try and reduce any
>> perceived overhead, perhaps by selectively using nested classes, as is often
>> the case elsewhere in `jdk.javadoc` and `jdk.compiler`. Grouping the new
>> `HTML...Taglet` classes in a new `formats.html.taglets` package seems like a
>> good compromise.
>>
>> **Note**: this is just "cleanup" and refactoring. There is no intentional
>> change to any functionality, nor any added or removed. If code appears to
>> have been "deleted" it has either been moved elsewhere, or was effectively
>> unused anyway. No test...
>
> Jonathan Gibbons has updated the pull request incrementally with one
> additional commit since the last revision:
>
> Address review feedback
Even better; thanks.
-------------
Marked as reviewed by prappo (Reviewer).
PR Review: https://git.openjdk.org/jdk/pull/14793#pullrequestreview-1527350977
