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 JDK API docs are not affected by these
changes.
Some stats:
| Class | Before | After |
|------|--------|------|
| TagletWriter | 420 lines | 294 lines |
| TagletWriterImpl | 985 lines | 272 lines |
... so, even if `TagletWriter` and `TagletWriterImpl` have not gone away
completely, they have at least been significantly reduced.
-------------
Commit messages:
- use default methods for Taglet.in... methods
- de-duplicate support for creating tag lists
- clean up naming and use of doclet-global values
- clean up link generation, moving TagletWriterImpl.linkSeeReferenceOutput to
HtmlLinkTaglet
- fix minor comment warning
- remove redundant visit-tag methods in HtmlDocletWriter.commentTagsToContent
- merge [Html]CodeTaglet and [Html]LiteralTaglet
- JDK-8309566: Migrate away from TagletWriter and TagletWriterImpl
Changes: https://git.openjdk.org/jdk/pull/14793/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=14793&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8309566
Stats: 4052 lines in 48 files changed: 2149 ins; 1618 del; 285 mod
Patch: https://git.openjdk.org/jdk/pull/14793.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/14793/head:pull/14793
PR: https://git.openjdk.org/jdk/pull/14793
