On Tue, 11 Jul 2023 01:49:05 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:
>
> merge toolkit taglet code into formats.html taglet code
As a result of the merge, `TagletWriter` has also moved to the
`formats.html.taglets` package, and merged with `TagletWriterImpl` which no
longer exists.
I also cleaned up some related bit-decay, so that there are no imports in the
`toolkit` world for classes in the `formats.html` world.
-------------
PR Comment: https://git.openjdk.org/jdk/pull/14793#issuecomment-1629981691
PR Comment: https://git.openjdk.org/jdk/pull/14793#issuecomment-1629982724
