Skip to content
Permalink
Browse files

8235306: Support doc-comment tags that can be inline or block tags

Reviewed-by: hannesw
  • Loading branch information
jonathan-gibbons committed Dec 13, 2019
1 parent 4d1176f commit 3c0e2b4e16d8fb2f96741bc8d4188aa47f58dd15
Showing with 462 additions and 242 deletions.
  1. +30 −16 src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Taglet.java
  2. +9 −9 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
  3. +3 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BasePropertyTaglet.java
  4. +15 −15 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BaseTaglet.java
  5. +2 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/CodeTaglet.java
  6. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/DeprecatedTaglet.java
  7. +2 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/DocRootTaglet.java
  8. +2 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/IndexTaglet.java
  9. +2 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java
  10. +2 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/LiteralTaglet.java
  11. +2 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java
  12. +2 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ReturnTaglet.java
  13. +2 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SeeTaglet.java
  14. +13 −12 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SimpleTaglet.java
  15. +3 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SummaryTaglet.java
  16. +4 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SystemPropertyTaglet.java
  17. +36 −19 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/Taglet.java
  18. +119 −105 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java
  19. +10 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java
  20. +17 −14 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/UserTaglet.java
  21. +2 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ValueTaglet.java
  22. +152 −0 test/langtools/jdk/javadoc/doclet/testBimodalTaglets/TestBimodalTaglets.java
  23. +31 −31 test/langtools/jdk/javadoc/doclet/testTaglets/TestTaglets.out
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -36,9 +36,10 @@
* 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; 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.
* comments; custom tags can be instantiated individually as 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> 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
@@ -78,20 +79,32 @@
public interface Taglet {

/**
* Returns the set of locations in which a tag may be used.
* @return the set of locations in which a tag may be used
* Returns the set of supported locations for block tags.
* @return the set of supported locations for block tags
*/
Set<Location> getAllowedLocations();

/**
* Indicates whether this taglet is for inline tags or not.
* @return true if this taglet is for an inline tag, and false otherwise
* Indicates whether this taglet supports inline tags.
*
* @return true if this taglet supports inline tags
*/
boolean isInlineTag();

/**
* Returns the name of the tag.
* @return the name of this custom tag.
* Indicates whether this taglet supports block tags.
*
* @return true if this taglet supports block tags
* @implSpec This implementation returns the inverse
* result to {@code isInlineTag}.
*/
default boolean isBlockTag() {
return !isInlineTag();
}

/**
* Returns the name of the tag supported by this taglet.
* @return the name of this tag
*/
String getName();

@@ -115,10 +128,11 @@ default void init(DocletEnvironment env, Doclet doclet) { }
* Returns the string representation of a series of instances of
* this tag to be included in the generated output.
*
* <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.
* <p>If this taglet supports {@link #isInlineTag inline} tags, it will
* be called once per instance of the inline tag, each time with a singleton list.
* If this taglet supports {@link #isBlockTag block} tags, it will be called once
* for each comment containing instances of block tags, with a list of all the instances
* of the block tag in that comment.
*
* @param tags the list of instances of this tag
* @param element the element to which the enclosing comment belongs
@@ -133,14 +147,14 @@ default void init(DocletEnvironment env, Doclet doclet) { }
/**
* The kind of location in which a tag may be used.
*/
public static enum Location {
enum Location {
/** In an Overview document. */
OVERVIEW,
/** In the documentation for a module. */
MODULE,
/** In the documentation for a package. */
PACKAGE,
/** In the documentation for a class, interface or enum. */
/** In the documentation for a type, such as a class, interface or enum. */
TYPE,
/** In the documentation for a constructor. */
CONSTRUCTOR,
@@ -1323,16 +1323,16 @@ public Content commentTagsToContent(DocTree holderTag, Element element,
* an inline tag, such as in comments or in free-form text arguments
* to block tags.
*
* @param holderTag specific tag where comment resides
* @param element specific element where comment resides
* @param tags array of text tags and inline tags (often alternating)
present in the text of interest for this element
* @param isFirstSentence true if text is first sentence
* @param inSummary if the comment tags are added into the summary section
* @param holderTag specific tag where comment resides
* @param element specific element where comment resides
* @param trees array of text tags and inline tags (often alternating)
* present in the text of interest for this element
* @param isFirstSentence true if text is first sentence
* @param inSummary if the comment tags are added into the summary section
* @return a Content object
*/
public Content commentTagsToContent(DocTree holderTag, Element element,
List<? extends DocTree> tags, boolean isFirstSentence, boolean inSummary) {
List<? extends DocTree> trees, boolean isFirstSentence, boolean inSummary) {

final Content result = new ContentBuilder() {
@Override
@@ -1342,10 +1342,10 @@ public void add(CharSequence text) {
};
CommentHelper ch = utils.getCommentHelper(element);
// Array of all possible inline tags for this javadoc run
configuration.tagletManager.checkTags(element, tags, true);
configuration.tagletManager.checkTags(element, trees, true);
commentRemoved = false;

for (ListIterator<? extends DocTree> iterator = tags.listIterator(); iterator.hasNext();) {
for (ListIterator<? extends DocTree> iterator = trees.listIterator(); iterator.hasNext();) {
boolean isFirstNode = !iterator.hasPrevious();
DocTree tag = iterator.next();
boolean isLastNode = !iterator.hasNext();
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2018, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2019, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -29,6 +29,7 @@
import javax.lang.model.element.Element;

import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;

/**
@@ -44,7 +45,7 @@
public abstract class BasePropertyTaglet extends BaseTaglet {

public BasePropertyTaglet(String name) {
super(name, false, EnumSet.of(Site.METHOD));
super(name, false, EnumSet.of(Location.METHOD));
}

/**
@@ -29,6 +29,7 @@
import javax.lang.model.element.Element;

import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;

/**
@@ -40,30 +41,29 @@
* deletion without notice.</b>
*/
public class BaseTaglet implements Taglet {
/**
* The different kinds of place where any given tag may be used.
*/
enum Site {
OVERVIEW, MODULE, PACKAGE, TYPE, CONSTRUCTOR, METHOD, FIELD
}

protected final String name;
private final boolean inline;
private final Set<Site> sites;
private final Set<Location> sites;

BaseTaglet(String name, boolean inline, Set<Site> sites) {
BaseTaglet(String name, boolean inline, Set<Location> sites) {
this.name = name;
this.inline = inline;
this.sites = sites;
}

@Override
public Set<Location> getAllowedLocations() {
return sites;
}

/**
* Returns true if this {@code Taglet} can be used in constructor documentation.
* @return true if this {@code Taglet} can be used in constructor documentation and false
* otherwise.
*/
public final boolean inConstructor() {
return sites.contains(Site.CONSTRUCTOR);
return sites.contains(Location.CONSTRUCTOR);
}

/**
@@ -72,7 +72,7 @@ public final boolean inConstructor() {
* otherwise.
*/
public final boolean inField() {
return sites.contains(Site.FIELD);
return sites.contains(Location.FIELD);
}

/**
@@ -81,7 +81,7 @@ public final boolean inField() {
* otherwise.
*/
public final boolean inMethod() {
return sites.contains(Site.METHOD);
return sites.contains(Location.METHOD);
}

/**
@@ -90,7 +90,7 @@ public final boolean inMethod() {
* otherwise.
*/
public final boolean inOverview() {
return sites.contains(Site.OVERVIEW);
return sites.contains(Location.OVERVIEW);
}

/**
@@ -99,7 +99,7 @@ public final boolean inOverview() {
* otherwise.
*/
public final boolean inModule() {
return sites.contains(Site.MODULE);
return sites.contains(Location.MODULE);
}

/**
@@ -108,7 +108,7 @@ public final boolean inModule() {
* otherwise.
*/
public final boolean inPackage() {
return sites.contains(Site.PACKAGE);
return sites.contains(Location.PACKAGE);
}

/**
@@ -117,7 +117,7 @@ public final boolean inPackage() {
* otherwise.
*/
public final boolean inType() {
return sites.contains(Site.TYPE);
return sites.contains(Location.TYPE);
}

/**
@@ -30,6 +30,7 @@
import javax.lang.model.element.Element;

import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;

import static com.sun.source.doctree.DocTree.Kind.CODE;
@@ -55,7 +56,7 @@
public class CodeTaglet extends BaseTaglet {

CodeTaglet() {
super(CODE.tagName, true, EnumSet.allOf(Site.class));
super(CODE.tagName, true, EnumSet.allOf(Location.class));
}

@Override
@@ -28,7 +28,7 @@
import java.util.EnumSet;
import javax.lang.model.element.Element;

import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;

import static com.sun.source.doctree.DocTree.Kind.DEPRECATED;
@@ -46,7 +46,7 @@

public DeprecatedTaglet() {
super(DEPRECATED.tagName, false,
EnumSet.of(Site.MODULE, Site.TYPE, Site.CONSTRUCTOR, Site.METHOD, Site.FIELD));
EnumSet.of(Location.MODULE, Location.TYPE, Location.CONSTRUCTOR, Location.METHOD, Location.FIELD));
}

@Override
@@ -29,6 +29,7 @@
import javax.lang.model.element.Element;

import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;

import static com.sun.source.doctree.DocTree.Kind.DOC_ROOT;
@@ -50,7 +51,7 @@
* Construct a new DocRootTaglet.
*/
public DocRootTaglet() {
super(DOC_ROOT.tagName, true, EnumSet.allOf(Site.class));
super(DOC_ROOT.tagName, true, EnumSet.allOf(Location.class));
}

@Override
@@ -29,6 +29,7 @@
import javax.lang.model.element.Element;

import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;

import static com.sun.source.doctree.DocTree.Kind.INDEX;
@@ -42,7 +43,7 @@
public class IndexTaglet extends BaseTaglet {

IndexTaglet() {
super(INDEX.tagName, true, EnumSet.allOf(Site.class));
super(INDEX.tagName, true, EnumSet.allOf(Location.class));
}

@Override
@@ -30,6 +30,7 @@
import javax.lang.model.element.ExecutableElement;

import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.BaseConfiguration;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.Messages;
@@ -57,7 +58,7 @@
* Construct a new InheritDocTaglet.
*/
public InheritDocTaglet () {
super(INHERIT_DOC.tagName, true, EnumSet.of(Site.TYPE, Site.METHOD));
super(INHERIT_DOC.tagName, true, EnumSet.of(Location.TYPE, Location.METHOD));
}

/**
@@ -29,6 +29,7 @@
import javax.lang.model.element.Element;

import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;

import static com.sun.source.doctree.DocTree.Kind.LITERAL;
@@ -48,7 +49,7 @@
public class LiteralTaglet extends BaseTaglet {

LiteralTaglet() {
super(LITERAL.tagName, true, EnumSet.allOf(Site.class));
super(LITERAL.tagName, true, EnumSet.allOf(Location.class));
}

@Override
@@ -34,6 +34,7 @@

import com.sun.source.doctree.DocTree;
import com.sun.source.doctree.ParamTree;
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.Messages;
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
@@ -65,7 +66,7 @@
* Construct a ParamTaglet.
*/
public ParamTaglet() {
super(PARAM.tagName, false, EnumSet.of(Site.TYPE, Site.CONSTRUCTOR, Site.METHOD));
super(PARAM.tagName, false, EnumSet.of(Location.TYPE, Location.CONSTRUCTOR, Location.METHOD));
}

/**
@@ -34,6 +34,7 @@
import javax.lang.model.type.TypeMirror;

import com.sun.source.doctree.DocTree;
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.Messages;
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
@@ -54,7 +55,7 @@
public class ReturnTaglet extends BaseTaglet implements InheritableTaglet {

public ReturnTaglet() {
super(RETURN.tagName, false, EnumSet.of(Site.METHOD));
super(RETURN.tagName, false, EnumSet.of(Location.METHOD));
}

@Override

0 comments on commit 3c0e2b4

Please sign in to comment.
You can’t perform that action at this time.