OpenJDK / zgc / zgc
changeset 56455:072f27397b69
8227697: Improve text in Taglet API spec for expected results with standard doclet
Reviewed-by: hannesw
author | jjg |
---|---|
date | Fri, 09 Aug 2019 12:27:05 -0700 |
parents | a64caa5269cf |
children | 7cf02b2c1455 |
files | src/jdk.javadoc/share/classes/jdk/javadoc/doclet/StandardDoclet.java src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java |
diffstat | 2 files changed, 67 insertions(+), 6 deletions(-) [+] |
line wrap: on
line diff
--- 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. * + * <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> */
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java Fri Aug 09 11:27:08 2019 -0700 +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java Fri Aug 09 12:27:05 2019 -0700 @@ -36,13 +36,42 @@ * 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 @@ /** * 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);