# HG changeset patch # User jjg # Date 1565378825 25200 # Node ID 072f27397b69c317f4f98ae1b06a33d3be6a1123 # Parent a64caa5269cfadfb0e7f61703c0798b58ed859b5 8227697: Improve text in Taglet API spec for expected results with standard doclet Reviewed-by: hannesw diff -r a64caa5269cf -r 072f27397b69 src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java --- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java Fri Aug 09 11:27:08 2019 -0700 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java Fri Aug 09 12:27:05 2019 -0700 @@ -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 @@ * This doclet generates HTML-formatted documentation for the specified modules, * packages and types. * + *
}. + *
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: * - *
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. + *
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 User-Defined Taglets + * for the Standard Doclet * @since 9 */ @@ -85,14 +114,19 @@ /** * 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 + * + *
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 User-Defined Taglets + * for the Standard Doclet */ String toString(List extends DocTree> tags, Element element);