# Improving the Taglet abstraction

This note is about adjusting/improving the interface between taglets and the
standard doclet, and specifically for those taglets used for block tags, like
`@param`, `@return`, etc.

Note: there are two kinds of taglets supported by the standard doclet: taglets
defined by the standard doclet itself, which use the full but internal `Content`
API to present their output, and user-defined taglets, which just use strings to
present their output. Except where noted otherwise, the following discussion
applies to both kinds.

Historically, the form of output to be generated by the taglet for a block tag
was undefined, although in practice, because the output from block tags has
always been presented in a definition list, the output of taglets has been
expected to be content that is suitable for inclusion in a `<dl>` node, with the
standard doclet providing the enclosing `<dl>` node. For better or worse, that
presumption eventually made it into the [Doc Comment Spec][dcs-user-tags].

[dcs-user-tags]: https://docs.oracle.com/en/java/javase/22/docs/api/jdk.javadoc/jdk/javadoc/doclet/StandardDoclet.html#user-defined-taglets

This "split" in the abstraction, with the standard doclet providing the `<dl>`
node and the taglets providing the `<dt>` anc `<dd>` nodes to be included in the
`<dl>` node is less than ideal, and inhibits any evolution in the presentation of
block tags.

It is proposed that we should adjust the interface here, such that we have
the opportunity to change how block tags are presented. For example, one
possibility would be to use a `<section>` containing a series of headings
and related flow content.

How can we make this happen, in a gradual and compatible way?

The change will (obviously) need changes within both the standard doclet and
existing taglets.

The standard doclet should be updated to _permit_ but not _require_ that taglets
return content for direct inclusion in `<dl>` node. Essentially, this means
inspecting the output from a taglet to determine if it is "old-style" or
"new-style". Then, for as long as block tags are presented in definition lists:

   * if the output from a taglet is old-style, then no further action need
     be taken, or
   * if the output from a taglet is new-style, then the output should be
     wrapped as needed in appropriate `<dt>` and/or `<dd>` nodes.
   
If we wish to present the output for block tags in some other form:

   * if the output from a taglet is old-style, we should analyze the output
     and extract the content of any `<dt>` or `<dd>` tags, or
   * if the output from a taglet is new-style, then no additional analysis
     of the output is required; it can be included as part of the presentation
     of the overall set of block tags.

For system-defined taglets, the "heading" for the output from a taglet is
either implicitly defined as a characteristic of the taglet, and so it should be
"reasonably easy" to exclude the `<dd>` from the content that is returned,
or is explicitly provided in a `<dt>` tag, similar to a user-defined taglet.

For user-defined taglets, the current practice is for the heading and the
associated content to be returned in a single string, with the heading
enclosed in a `<dt>` tag and the associated content enclosed in a `<dd>`
tag. A better solution would be to introduce a new method on `Taglet` to
return the text of the heading directly. It could be a default method
with a default implementation to return the result of the existing `getName`
method.