Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8253733

Cleanup internal taglet API

    XMLWordPrintable

    Details

    • Type: Enhancement
    • Status: Resolved
    • Priority: P3
    • Resolution: Fixed
    • Affects Version/s: 16
    • Fix Version/s: 16
    • Component/s: tools
    • Labels:

      Description

      TagletWriter is notable for having a couple of static methods that take a TagletWriter as a final parameter. These methods could be improved by making them instance methods and removing the then-unnecessary parameter.

      The two methods are `genTagOutput` (for block tags) and `getInlineTagOutput` (for inline tags.) The naming could be more consistent.

      In addition, the overall code, and some internal comments, suggest that the original intent was to bypass the Taglet[Writer] API for standard tags, although that has been less common for recent tags. It would be better to generally refocus the code to better leverage these APIs, and move functionality out of `HtmlDocletWriter` where possible. See comments in TW.getInlineTagOutput about `//This is a custom inline tag` which is no longer true. That feeds back into methods on TagletManager.

      Also TagletManager returns inline tags as a list, and does linear lookup to find the taglet for a tag. It would be more sensible to use a Map.

      As a general policy, it would be good to better align the public and internal Taglet interfaces. That is not convenient/easy at this time. There are two problems:
          The return type: the public API uses String; the internal API uses Content
          The public API only provides access to the DocletEnvironment which is an abstraction of the tool's state, and contains no access to the current doclet state, including (for example) info about the current page. Somewhat related, we cannot "tunnel" extra info to the taglet via a subtype of DocletEnvironment because of the cast to DocEnvImpl in Workarounds, which can/should be the subject of a separate cleanup.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              jjg Jonathan Gibbons
              Reporter:
              jjg Jonathan Gibbons
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: