On Fri, 7 Jul 2023 00:14:43 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 tests are modified, and the JD... This pull request has now been integrated. Changeset: e51472e9 Author: Jonathan Gibbons <j...@openjdk.org> URL: https://git.openjdk.org/jdk/commit/e51472e9a857451451d6df37588bd67f63bc2032 Stats: 9396 lines in 71 files changed: 4539 ins; 4737 del; 120 mod 8309566: Migrate away from TagletWriter and TagletWriterImpl 8311974: Clean up Utils.getBlockTags Reviewed-by: prappo ------------- PR: https://git.openjdk.org/jdk/pull/14793