Skip to content
Permalink
Browse files

8235947: Cleanup/simplify Utils.getBlockTags

Reviewed-by: prappo, hannesw
  • Loading branch information
jonathan-gibbons committed Dec 18, 2019
1 parent a3c0f4c commit dc5728ed954418953cef5688be6e694ec4e88213
Showing with 183 additions and 176 deletions.
  1. +8 −9 ...jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MemberSummaryBuilder.java
  2. +53 −8 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BaseTaglet.java
  3. +1 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/CodeTaglet.java
  4. +2 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/DeprecatedTaglet.java
  5. +1 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/DocRootTaglet.java
  6. +1 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/IndexTaglet.java
  7. +2 −4 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java
  8. +1 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/LiteralTaglet.java
  9. +1 −4 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java
  10. +2 −4 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ReturnTaglet.java
  11. +1 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SeeTaglet.java
  12. +52 −29 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SimpleTaglet.java
  13. +1 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SummaryTaglet.java
  14. +1 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SystemPropertyTaglet.java
  15. +12 −12 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java
  16. +13 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletWriter.java
  17. +1 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java
  18. +1 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/UserTaglet.java
  19. +1 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ValueTaglet.java
  20. +0 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/CommentHelper.java
  21. +28 −72 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
@@ -38,6 +38,7 @@
import com.sun.source.doctree.DocCommentTree;
import com.sun.source.doctree.DocTree;
import com.sun.source.doctree.DocTree.Kind;
import com.sun.source.doctree.UnknownBlockTagTree;
import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeWriter;
import jdk.javadoc.internal.doclets.toolkit.ClassWriter;
import jdk.javadoc.internal.doclets.toolkit.Content;
@@ -365,7 +366,9 @@ private void processProperty(Element member,
utils.propertyName((ExecutableElement) member));
fullBody.addAll(cmtutils.makeFirstSentenceTree(text));
}
List<? extends DocTree> propertyTags = utils.getBlockTags(property, "propertyDescription");
List<? extends DocTree> propertyTags = utils.getBlockTags(property,
t -> (t instanceof UnknownBlockTagTree)
&& ((UnknownBlockTagTree) t).getTagName().equals("propertyDescription"));
if (propertyTags.isEmpty()) {
List<? extends DocTree> comment = utils.getFullBody(property);
blockTags.addAll(cmtutils.makePropertyDescriptionTree(comment));
@@ -378,14 +381,10 @@ private void processProperty(Element member,
List<? extends DocTree> tags = utils.getBlockTags(property, Kind.SINCE);
blockTags.addAll(tags);

List<? extends DocTree> bTags = utils.getBlockTags(property, Kind.UNKNOWN_BLOCK_TAG);
CommentHelper ch = utils.getCommentHelper(property);
for (DocTree dt : bTags) {
String tagName = ch.getTagName(dt);
if ( "defaultValue".equals(tagName)) {
blockTags.add(dt);
}
}
List<? extends DocTree> bTags = utils.getBlockTags(property,
t -> (t instanceof UnknownBlockTagTree)
&& ((UnknownBlockTagTree) t).getTagName().equals("defaultValue"));
blockTags.addAll(bTags);

//add @see tags
if (!isGetter && !isSetter) {
@@ -29,6 +29,7 @@
import javax.lang.model.element.Element;

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

@@ -42,11 +43,20 @@
*/
public class BaseTaglet implements Taglet {

protected final DocTree.Kind tagKind;
protected final String name;
private final boolean inline;
private final Set<Location> sites;

BaseTaglet(DocTree.Kind tagKind, boolean inline, Set<Location> sites) {
this.tagKind = tagKind;
this.name = tagKind.tagName;
this.inline = inline;
this.sites = sites;
}

BaseTaglet(String name, boolean inline, Set<Location> sites) {
this.tagKind = inline ? DocTree.Kind.UNKNOWN_INLINE_TAG : DocTree.Kind.UNKNOWN_BLOCK_TAG;
this.name = name;
this.inline = inline;
this.sites = sites;
@@ -59,6 +69,7 @@

/**
* 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.
*/
@@ -68,87 +79,121 @@ public final boolean inConstructor() {

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

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

/**
* Returns true if this {@code Taglet} can be used in overview documentation.
*
* @return true if this {@code Taglet} can be used in method documentation and false
* otherwise.
*/
public final boolean inOverview() {
return sites.contains(Location.OVERVIEW);
return sites.contains(Location.OVERVIEW);
}

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

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

/**
* Returns true if this {@code Taglet} can be used in type documentation (classes or interfaces).
*
* @return true if this {@code Taglet} can be used in type documentation and false
* otherwise.
*/
public final boolean inType() {
return sites.contains(Location.TYPE);
return sites.contains(Location.TYPE);
}

/**
* Returns true if this {@code Taglet} is an inline tag.
*
* @return true if this {@code Taglet} represents an inline tag and false otherwise.
*/
public final boolean isInlineTag() {
return inline;
}

/**
* Returns the kind of trees recognized by this taglet.
*
* @return the kind of trees recognized by this taglet
*/
public DocTree.Kind getTagKind() {
return tagKind;
}

/**
* Returns the name of this tag.
*
* @return the name of this tag.
*/
public String getName() {
return name;
}

/**
* Returns whether or not this taglet accepts a {@code DocTree} node.
* The taglet accepts a tree node if it has the same kind, and
* if the kind is {@code UNKNOWN_BLOCK_TAG} the same tag name.
*
* @param tree the tree node
* @return {@code true} if this taglet accepts this tree node.
*/
public boolean accepts(DocTree tree) {
return (tree.getKind() == DocTree.Kind.UNKNOWN_BLOCK_TAG
&& tagKind == DocTree.Kind.UNKNOWN_BLOCK_TAG)
? ((UnknownBlockTagTree) tree).getTagName().equals(name)
: tree.getKind() == tagKind;
}

/**
* {@inheritDoc}
*
* @throws UnsupportedTagletOperationException thrown when the method is
* not supported by the taglet.
* not supported by the taglet.
*/
public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) {
throw new UnsupportedTagletOperationException("Method not supported in taglet " + getName() + ".");
}

/**
* {@inheritDoc}
*
* @throws UnsupportedTagletOperationException thrown when the method is not
* supported by the taglet.
* supported by the taglet.
*/
public Content getTagletOutput(Element holder, TagletWriter writer) {
throw new UnsupportedTagletOperationException("Method not supported in taglet " + getName() + ".");
@@ -33,8 +33,6 @@
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;

import static com.sun.source.doctree.DocTree.Kind.CODE;

/**
* An inline Taglet used to denote literal code fragments.
* The enclosed text is interpreted as not containing HTML markup or
@@ -56,7 +54,7 @@
public class CodeTaglet extends BaseTaglet {

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

@Override
@@ -28,11 +28,10 @@
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;

/**
* A taglet that represents the @deprecated tag.
*
@@ -45,7 +44,7 @@
public class DeprecatedTaglet extends BaseTaglet {

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

@@ -32,8 +32,6 @@
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;

import static com.sun.source.doctree.DocTree.Kind.DOC_ROOT;

/**
* An inline Taglet representing {&#064;docRoot}. This taglet is
* used to get the relative path to the document's root output
@@ -51,7 +49,7 @@
* Construct a new DocRootTaglet.
*/
public DocRootTaglet() {
super(DOC_ROOT.tagName, true, EnumSet.allOf(Location.class));
super(DocTree.Kind.DOC_ROOT, true, EnumSet.allOf(Location.class));
}

@Override
@@ -32,8 +32,6 @@
import jdk.javadoc.doclet.Taglet.Location;
import jdk.javadoc.internal.doclets.toolkit.Content;

import static com.sun.source.doctree.DocTree.Kind.INDEX;

/**
* An inline Taglet used to index word or a phrase.
* The enclosed text is interpreted as not containing HTML markup or
@@ -43,7 +41,7 @@
public class IndexTaglet extends BaseTaglet {

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

@Override
@@ -39,8 +39,6 @@
import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;

import static com.sun.source.doctree.DocTree.Kind.INHERIT_DOC;

/**
* An inline Taglet representing the {@code inheritDoc} tag. This tag should only
* be used with a method. It is used to inherit documentation from overridden
@@ -58,7 +56,7 @@
* Construct a new InheritDocTaglet.
*/
public InheritDocTaglet () {
super(INHERIT_DOC.tagName, true, EnumSet.of(Location.TYPE, Location.METHOD));
super(DocTree.Kind.INHERIT_DOC, true, EnumSet.of(Location.TYPE, Location.METHOD));
}

/**
@@ -114,7 +112,7 @@ private Content retrieveInheritedDocumentation(TagletWriter writer,

@Override
public Content getTagletOutput(Element e, DocTree tag, TagletWriter tagletWriter) {
DocTree inheritTag = (tag.getKind() == INHERIT_DOC) ? null : tag;
DocTree inheritTag = (tag.getKind() == DocTree.Kind.INHERIT_DOC) ? null : tag;
return retrieveInheritedDocumentation(tagletWriter, e,
inheritTag, tagletWriter.isFirstSentence);
}
@@ -31,8 +31,6 @@
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;
/**
* An inline Taglet used to denote literal text.
* For example, the text:
@@ -49,7 +47,7 @@
public class LiteralTaglet extends BaseTaglet {

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

@Override
@@ -29,7 +29,6 @@

import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.Name;
import javax.lang.model.element.TypeElement;

import com.sun.source.doctree.DocTree;
@@ -42,8 +41,6 @@
import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;

import static com.sun.source.doctree.DocTree.Kind.PARAM;

/**
* A taglet that represents the @param tag.
*
@@ -66,7 +63,7 @@
* Construct a ParamTaglet.
*/
public ParamTaglet() {
super(PARAM.tagName, false, EnumSet.of(Location.TYPE, Location.CONSTRUCTOR, Location.METHOD));
super(DocTree.Kind.PARAM, false, EnumSet.of(Location.TYPE, Location.CONSTRUCTOR, Location.METHOD));
}

/**
@@ -42,8 +42,6 @@
import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;

import static com.sun.source.doctree.DocTree.Kind.RETURN;

/**
* A taglet that represents the @return tag.
*
@@ -55,7 +53,7 @@
public class ReturnTaglet extends BaseTaglet implements InheritableTaglet {

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

@Override
@@ -76,7 +74,7 @@ public Content getTagletOutput(Element holder, TagletWriter writer) {
Messages messages = writer.configuration().getMessages();
Utils utils = writer.configuration().utils;
TypeMirror returnType = utils.getReturnType((ExecutableElement)holder);
List<? extends DocTree> tags = utils.getBlockTags(holder, name);
List<? extends DocTree> tags = utils.getBlockTags(holder, DocTree.Kind.RETURN);

//Make sure we are not using @return tag on method with void return type.
if (returnType != null && utils.isVoid(returnType)) {
@@ -38,8 +38,6 @@
import jdk.javadoc.internal.doclets.toolkit.util.DocFinder.Input;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;

import static com.sun.source.doctree.DocTree.Kind.SEE;

/**
* A taglet that represents the @see tag.
*
@@ -51,7 +49,7 @@
public class SeeTaglet extends BaseTaglet implements InheritableTaglet {

public SeeTaglet() {
super(SEE.tagName, false, EnumSet.allOf(Location.class));
super(DocTree.Kind.SEE, false, EnumSet.allOf(Location.class));
}

@Override

0 comments on commit dc5728e

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