8227697: Improve text in Taglet API spec for expected results with standard doclet

Reviewed-by: hannesw

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java

@@ -26,8 +26,10 @@
 package jdk.javadoc.doclet;
 
 import java.util.Locale;
+import java.util.List;
 import java.util.Set;
 
+import javax.lang.model.element.Element;
 import javax.lang.model.SourceVersion;
 
 import jdk.javadoc.internal.doclets.formats.html.HtmlDoclet;
@@ -36,6 +38,31 @@ import jdk.javadoc.internal.doclets.formats.html.HtmlDoclet;
  * This doclet generates HTML-formatted documentation for the specified modules,
  * packages and types.
  *
+ * <h2><a id="user-defined-taglets">User-Defined Taglets</a></h2>
+ *
+ * The standard doclet supports user-defined {@link Taglet taglets},
+ * which can be used to generate customized output for user-defined tags
+ * in documentation comments.
+ *
+ * Taglets invoked by the standard doclet must return strings from
+ * {@link Taglet#toString(List,Element) Taglet.toString} as follows:
+ *
+ * <dl>
+ * <dt> <i>Inline Tags</i>
+ * <dd> The returned string must be
+ *      <a href="https://www.w3.org/TR/html52/dom.html#flow-content">flow content</a>,
+ *      or any valid fragment of HTML code that may appear in the body of a document.
+ *      There may be additional constraints, depending on how the tag is to be
+ *      used in a documentation comment: for example, if the tag may be used
+ *      within an inline element such as {@code <b>} or {@code <i>}, the taglet
+ *      must not return a string containing block tags, like {@code <h3>} or
+ *      {@code <p>}.
+ * <dt> <i>Block Tags</i>
+ * <dd> The returned string must be suitable content for a definition list,
+ *      or {@code <dl>} element. It will typically be a series of pairs
+ *      of {@code <dt>} and {@code <dd>} elements.
+ * </dl>
+ *
  * @see <a href="{@docRoot}/../specs/javadoc/doc-comment-spec.html">
  *      Documentation Comment Specification for the Standard Doclet</a>
  */

src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java

@@ -36,13 +36,42 @@ import com.sun.source.doctree.DocTree;
  * The interface for a custom taglet supported by doclets such as
  * the {@link jdk.javadoc.doclet.StandardDoclet standard doclet}.
  * Custom taglets are used to handle custom tags in documentation
- * comments.
+ * comments; custom tags can be either <i>block tags</i>, which
+ * appear at the end of a comment, or <i>inline tags</i>, which
+ * can appear within the main body of a documentation comment.
  *
- * <p>A custom taglet must implement this interface, and must have
- * a public default constructor (i.e. a public constructor with no
- * parameters), by which, the doclet will instantiate and
- * register the custom taglet.
+ * <p> Each implementation of a taglet must provide a public no-argument constructor
+ * to be used by doclets to instantiate the taglet. A doclet will interact
+ * with classes implementing this interface as follows:
  *
+ * <ol>
+ * <li> The doclet will create an instance of a taglet using the no-arg
+ *      constructor of the taglet class.
+ * <li> Next, the doclet calls the {@link #init(DocletEnvironment,Doclet) init}
+        method with an appropriate environment and doclet.
+ * <li> Afterwards, the doclet calls {@link #getName() getName},
+ *      {@link #getAllowedLocations() getAllowedLocations}, and
+ *      {@link #isInlineTag() isInlineTag}, to determine the characteristics
+ *      of the tags supported by the taglet.
+ * <li> As appropriate, the doclet calls the
+ *      {@link #toString(List,Element) toString} method on the taglet object,
+ *      giving it a list of tags and the element for which the tags are part
+ *      of the element's documentation comment, from which the taglet can
+ *      determine the string to be included in the documentation.
+ *      The doclet will typically specify any requirements on the contents of
+ *      the string that is returned.
+ * </ol>
+ *
+ * <p>If a taglet object is created and used without the above protocol being
+ * followed, then the taglet's behavior is not defined by this interface
+ * specification.
+ *
+ * @apiNote
+ * It is typical for a taglet to be designed to work in conjunction with a
+ * specific doclet.
+ *
+ * @see <a href="StandardDoclet.html#user-defined-taglets">User-Defined Taglets
+ *      for the Standard Doclet</a>
  * @since 9
  */
 
@@ -85,14 +114,19 @@ public interface Taglet {
     /**
      * Returns the string representation of a series of instances of
      * this tag to be included in the generated output.
-     * If this taglet is for an {@link #isInlineTag inline} tag it will
+     *
+     * <p>If this taglet is for an {@link #isInlineTag inline} tag it will
      * be called once per instance of the tag, each time with a singleton list.
      * Otherwise, if this tag is a block tag, it will be called once per
      * comment, with a list of all the instances of the tag in a comment.
+     *
      * @param tags the list of instances of this tag
      * @param element the element to which the enclosing comment belongs
      * @return the string representation of the tags to be included in
      *  the generated output
+     *
+     * @see <a href="StandardDoclet.html#user-defined-taglets">User-Defined Taglets
+     *      for the Standard Doclet</a>
      */
     String toString(List<? extends DocTree> tags, Element element);