Skip to content
Permalink
Browse files
8253733: Cleanup internal taglet API
Reviewed-by: prappo
  • Loading branch information
jonathan-gibbons committed Sep 30, 2020
1 parent e5ba020 commit 4fb8c7769615205556c3f983ef67546d90bb46d2
Showing with 316 additions and 314 deletions.
  1. +1 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java
  2. +1 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java
  3. +1 −1 ...k.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstantsSummaryWriterImpl.java
  4. +46 −32 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
  5. +6 −7 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlSerialFieldWriter.java
  6. +3 −7 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlSerialMethodWriter.java
  7. +12 −34 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java
  8. +1 −1 ...dk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java
  9. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/BaseTaglet.java
  10. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/CodeTaglet.java
  11. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/DeprecatedTaglet.java
  12. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/DocRootTaglet.java
  13. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/IndexTaglet.java
  14. +3 −3 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/InheritDocTaglet.java
  15. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/LiteralTaglet.java
  16. +1 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ParamTaglet.java
  17. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ReturnTaglet.java
  18. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SeeTaglet.java
  19. +3 −8 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SimpleTaglet.java
  20. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SummaryTaglet.java
  21. +2 −2 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/SystemPropertyTaglet.java
  22. +13 −11 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/Taglet.java
  23. +21 −20 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java
  24. +172 −155 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletWriter.java
  25. +1 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ThrowsTaglet.java
  26. +3 −4 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/UserTaglet.java
  27. +7 −6 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/ValueTaglet.java
  28. +1 −1 src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
@@ -274,7 +274,7 @@ private void addModifier(Element member, Content code) {
* @param contentTree the content tree to which the deprecated information will be added.
*/
protected void addDeprecatedInfo(Element member, Content contentTree) {
Content output = (new DeprecatedTaglet()).getTagletOutput(member,
Content output = (new DeprecatedTaglet()).getAllBlockTagOutput(member,
writer.getTagletWriterInstance(false));
if (!output.isEmpty()) {
Content deprecatedContent = output;
@@ -376,7 +376,7 @@ public void addClassTree(Content classContentTree) {
@Override
public void addParamInfo(Content classInfoTree) {
if (utils.hasBlockTag(typeElement, DocTree.Kind.PARAM)) {
Content paramInfo = (new ParamTaglet()).getTagletOutput(typeElement,
Content paramInfo = (new ParamTaglet()).getAllBlockTagOutput(typeElement,
getTagletWriterInstance(false));
if (!paramInfo.isEmpty()) {
classInfoTree.add(HtmlTree.DL(HtmlStyle.notes, paramInfo));
@@ -258,7 +258,7 @@ private Content getNameColumn(VariableElement member) {
* @return the value column of the constant table row
*/
private Content getValue(VariableElement member) {
String value = utils.constantValueExpresion(member);
String value = utils.constantValueExpression(member);
Content valueContent = new StringContent(value);
return HtmlTree.CODE(valueContent);
}
@@ -94,6 +94,7 @@
import jdk.javadoc.internal.doclets.toolkit.PackageSummaryWriter;
import jdk.javadoc.internal.doclets.toolkit.Resources;
import jdk.javadoc.internal.doclets.toolkit.taglets.DocRootTaglet;
import jdk.javadoc.internal.doclets.toolkit.taglets.Taglet;
import jdk.javadoc.internal.doclets.toolkit.taglets.TagletWriter;
import jdk.javadoc.internal.doclets.toolkit.util.Comparators;
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
@@ -332,29 +333,54 @@ protected void addTagsInfo(Element e, Content htmlTree) {
if (utils.isExecutableElement(e) && !utils.isConstructor(e)) {
addMethodInfo((ExecutableElement)e, dl);
}
Content output = new ContentBuilder();
TagletWriter.genTagOutput(configuration.tagletManager, e,
configuration.tagletManager.getBlockTaglets(e),
getTagletWriterInstance(false), output);
Content output = getBlockTagOutput(e);
dl.add(output);
htmlTree.add(dl);
}

/**
* Check whether there are any tags for Serialization Overview
* section to be printed.
* Returns the content generated from the default supported set of block tags
* for this element.
*
* @param field the VariableElement object to check for tags.
* @return true if there are tags to be printed else return false.
* @param element the element
*
* @return the content
*/
protected Content getBlockTagOutput(Element element) {
return getBlockTagOutput(element, configuration.tagletManager.getBlockTaglets(element));
}

/**
* Returns the content generated from a specified set of block tags
* for this element.
*
* @param element the element
* @param taglets the taglets to handle the required set of tags
*
* @return the content
*/
protected Content getBlockTagOutput(Element element, List<Taglet> taglets) {
return getTagletWriterInstance(false)
.getBlockTagOutput(configuration.tagletManager, element, taglets);
}

/**
* Returns whether there are any tags in a field for the Serialization Overview
* section to be generated.
*
* @param field the field to check
* @return {@code true} if and only if there are tags to be included
*/
protected boolean hasSerializationOverviewTags(VariableElement field) {
Content output = new ContentBuilder();
TagletWriter.genTagOutput(configuration.tagletManager, field,
configuration.tagletManager.getBlockTaglets(field),
getTagletWriterInstance(false), output);
Content output = getBlockTagOutput(field);
return !output.isEmpty();
}

private Content getInlineTagOutput(Element element, DocTree holder, DocTree tree, boolean isFirstSentence, boolean inSummary) {
return getTagletWriterInstance(isFirstSentence, inSummary)
.getInlineTagOutput(element, configuration.tagletManager, holder, tree);
}

/**
* Returns a TagletWriter that knows how to write HTML.
*
@@ -1440,11 +1466,8 @@ private Content copyDocRootContent(Content content) {

@Override
public Boolean visitDocRoot(DocRootTree node, Content c) {
Content docRootContent = TagletWriter.getInlineTagOutput(element,
configuration.tagletManager,
holderTag,
node,
getTagletWriterInstance(isFirstSentence));
Content docRootContent = getInlineTagOutput(element, holderTag, node,
isFirstSentence, false);
if (c != null) {
c.add(docRootContent);
} else {
@@ -1476,19 +1499,16 @@ public Boolean visitErroneous(ErroneousTree node, Content c) {

@Override
public Boolean visitInheritDoc(InheritDocTree node, Content c) {
Content output = TagletWriter.getInlineTagOutput(element,
configuration.tagletManager, holderTag,
tag, getTagletWriterInstance(isFirstSentence));
Content output = getInlineTagOutput(element, holderTag, node,
isFirstSentence, false);
result.add(output);
// if we obtained the first sentence successfully, nothing more to do
return (isFirstSentence && !output.isEmpty());
}

@Override
public Boolean visitIndex(IndexTree node, Content p) {
Content output = TagletWriter.getInlineTagOutput(element,
configuration.tagletManager, holderTag, tag,
getTagletWriterInstance(isFirstSentence, inSummary));
Content output = getInlineTagOutput(element, holderTag, node, isFirstSentence, inSummary);
if (output != null) {
result.add(output);
}
@@ -1535,18 +1555,14 @@ public Boolean visitStartElement(StartElementTree node, Content c) {

@Override
public Boolean visitSummary(SummaryTree node, Content c) {
Content output = TagletWriter.getInlineTagOutput(element,
configuration.tagletManager, holderTag, tag,
getTagletWriterInstance(isFirstSentence));
Content output = getInlineTagOutput(element, holderTag, node, isFirstSentence, false);
result.add(output);
return false;
}

@Override
public Boolean visitSystemProperty(SystemPropertyTree node, Content p) {
Content output = TagletWriter.getInlineTagOutput(element,
configuration.tagletManager, holderTag, tag,
getTagletWriterInstance(isFirstSentence, inSummary));
Content output = getInlineTagOutput(element, holderTag, node, isFirstSentence, inSummary);
if (output != null) {
result.add(output);
}
@@ -1579,9 +1595,7 @@ public Boolean visitText(TextTree node, Content c) {

@Override
protected Boolean defaultAction(DocTree node, Content c) {
Content output = TagletWriter.getInlineTagOutput(element,
configuration.tagletManager, holderTag, tag,
getTagletWriterInstance(isFirstSentence));
Content output = getInlineTagOutput(element, holderTag, node, isFirstSentence, false);
if (output != null) {
result.add(output);
}
@@ -196,13 +196,12 @@ public void addMemberDescription(VariableElement field, DocTree serialFieldTag,
*/
@Override
public void addMemberTags(VariableElement field, Content contentTree) {
Content tagContent = new ContentBuilder();
TagletWriter.genTagOutput(configuration.tagletManager, field,
configuration.tagletManager.getBlockTaglets(field),
writer.getTagletWriterInstance(false), tagContent);
HtmlTree dl = HtmlTree.DL(HtmlStyle.notes);
dl.add(tagContent);
contentTree.add(dl); // TODO: what if empty?
Content tagContent = writer.getBlockTagOutput(field);
if (!tagContent.isEmpty()) {
HtmlTree dl = HtmlTree.DL(HtmlStyle.notes);
dl.add(tagContent);
contentTree.add(dl);
}
}

/**
@@ -153,16 +153,12 @@ public void addMemberDescription(ExecutableElement member, Content methodsConten
*/
@Override
public void addMemberTags(ExecutableElement member, Content methodsContentTree) {
Content tagContent = new ContentBuilder();
TagletManager tagletManager =
configuration.tagletManager;
TagletWriter.genTagOutput(tagletManager, member,
tagletManager.getSerializedFormTaglets(),
writer.getTagletWriterInstance(false), tagContent);
TagletManager tagletManager = configuration.tagletManager;
Content tagContent = writer.getBlockTagOutput(member, tagletManager.getSerializedFormTaglets());
HtmlTree dl = HtmlTree.DL(HtmlStyle.notes);
dl.add(tagContent);
methodsContentTree.add(dl);
if (name(member).compareTo("writeExternal") == 0
if (name(member).equals("writeExternal")
&& utils.getSerialDataTrees(member).isEmpty()) {
serialWarning(member, "doclet.MissingSerialDataTag",
utils.getFullyQualifiedName(member.getEnclosingElement()), name(member));
@@ -143,9 +143,9 @@ public Content deprecatedTagOutput(Element element) {
result.add(HtmlTree.SPAN(HtmlStyle.deprecatedLabel,
htmlWriter.getDeprecatedPhrase(element)));
if (!deprs.isEmpty()) {
List<? extends DocTree> commentTags = ch.getDescription(deprs.get(0));
if (!commentTags.isEmpty()) {
result.add(commentTagsToOutput(null, element, commentTags, false));
List<? extends DocTree> commentTrees = ch.getDescription(deprs.get(0));
if (!commentTrees.isEmpty()) {
result.add(commentTagsToOutput(element, null, commentTrees, false));
}
}
}
@@ -154,8 +154,8 @@ public Content deprecatedTagOutput(Element element) {
result.add(HtmlTree.SPAN(HtmlStyle.deprecatedLabel,
htmlWriter.getDeprecatedPhrase(element)));
if (!deprs.isEmpty()) {
List<? extends DocTree> bodyTags = ch.getBody(deprs.get(0));
Content body = commentTagsToOutput(null, element, bodyTags, false);
List<? extends DocTree> bodyTrees = ch.getBody(deprs.get(0));
Content body = commentTagsToOutput(element, null, bodyTrees, false);
if (!body.isEmpty())
result.add(HtmlTree.DIV(HtmlStyle.deprecationComment, body));
}
@@ -205,18 +205,6 @@ public Content paramTagOutput(Element element, DocTree paramTag, String paramNam
return HtmlTree.DD(body);
}

@Override
public Content propertyTagOutput(Element element, DocTree tag, String prefix) {
Content body = new ContentBuilder();
CommentHelper ch = utils.getCommentHelper(element);
body.add(new RawHtml(prefix));
body.add(" ");
body.add(HtmlTree.CODE(new RawHtml(ch.getText(tag))));
body.add(".");
Content result = HtmlTree.P(body);
return result;
}

@Override
public Content returnTagOutput(Element element, DocTree returnTag) {
CommentHelper ch = utils.getCommentHelper(element);
@@ -273,7 +261,7 @@ private void appendSeparatorIfNotEmpty(ContentBuilder body) {
}

@Override
public Content simpleTagOutput(Element element, List<? extends DocTree> simpleTags, String header) {
public Content simpleBlockTagOutput(Element element, List<? extends DocTree> simpleTags, String header) {
CommentHelper ch = utils.getCommentHelper(element);
ContentBuilder body = new ContentBuilder();
boolean many = false;
@@ -290,16 +278,6 @@ public Content simpleTagOutput(Element element, List<? extends DocTree> simpleTa
HtmlTree.DD(body));
}

@Override
public Content simpleTagOutput(Element element, DocTree simpleTag, String header) {
CommentHelper ch = utils.getCommentHelper(element);
List<? extends DocTree> description = ch.getDescription(simpleTag);
Content body = htmlWriter.commentTagsToContent(simpleTag, element, description, false, inSummary);
return new ContentBuilder(
HtmlTree.DT(new RawHtml(header)),
HtmlTree.DD(body));
}

@Override
protected Content systemPropertyTagOutput(Element element, DocTree tag) {
SystemPropertyTree itt = (SystemPropertyTree) tag;
@@ -358,18 +336,18 @@ public Content valueTagOutput(VariableElement field, String constantVal, boolean
}

@Override
public Content commentTagsToOutput(DocTree holderTag, List<? extends DocTree> tags) {
return commentTagsToOutput(holderTag, null, tags, false);
public Content commentTagsToOutput(DocTree holder, List<? extends DocTree> tags) {
return commentTagsToOutput(null, holder, tags, false);
}

@Override
public Content commentTagsToOutput(Element holder, List<? extends DocTree> tags) {
return commentTagsToOutput(null, holder, tags, false);
public Content commentTagsToOutput(Element element, List<? extends DocTree> tags) {
return commentTagsToOutput(element, null, tags, false);
}

@Override
public Content commentTagsToOutput(DocTree holderTag,
Element holder,
public Content commentTagsToOutput(Element holder,
DocTree holderTag,
List<? extends DocTree> tags,
boolean isFirstSentence)
{
@@ -238,7 +238,7 @@ protected void buildSerialUIDInfo(Content classTree) {
if (field.getSimpleName().toString().compareTo(SERIAL_VERSION_UID) == 0 &&
field.getConstantValue() != null) {
writer.addSerialUIDInfo(SERIAL_VERSION_UID_HEADER,
utils.constantValueExpresion(field), serialUidTree);
utils.constantValueExpression(field), serialUidTree);
break;
}
}
@@ -143,7 +143,7 @@ public boolean accepts(DocTree tree) {
* @implSpec This implementation throws {@link UnsupportedTagletOperationException}.
*/
@Override
public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) {
public Content getInlineTagOutput(Element element, DocTree tag, TagletWriter writer) {
throw new UnsupportedTagletOperationException("Method not supported in taglet " + getName() + ".");
}

@@ -153,7 +153,7 @@ public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer
* @implSpec This implementation throws {@link UnsupportedTagletOperationException}
*/
@Override
public Content getTagletOutput(Element holder, TagletWriter writer) {
public Content getAllBlockTagOutput(Element holder, TagletWriter writer) {
throw new UnsupportedTagletOperationException("Method not supported in taglet " + getName() + ".");
}
}
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2020, 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
@@ -58,7 +58,7 @@
}

@Override
public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) {
public Content getInlineTagOutput(Element element, DocTree tag, TagletWriter writer) {
return writer.codeTagOutput(element, tag);
}
}
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2020, 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
@@ -49,7 +49,7 @@ public DeprecatedTaglet() {
}

@Override
public Content getTagletOutput(Element holder, TagletWriter writer) {
public Content getAllBlockTagOutput(Element holder, TagletWriter writer) {
return writer.deprecatedTagOutput(holder);
}
}
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2001, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2001, 2020, 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
@@ -53,7 +53,7 @@ public DocRootTaglet() {
}

@Override
public Content getTagletOutput(Element holder, DocTree tag, TagletWriter writer) {
public Content getInlineTagOutput(Element holder, DocTree tag, TagletWriter writer) {
return writer.getDocRootOutput();
}
}
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2015, 2020, 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
@@ -45,7 +45,7 @@
}

@Override
public Content getTagletOutput(Element element, DocTree tag, TagletWriter writer) {
public Content getInlineTagOutput(Element element, DocTree tag, TagletWriter writer) {
return writer.indexTagOutput(element, tag);
}
}
Loading

1 comment on commit 4fb8c77

@bridgekeeper

This comment has been minimized.

Copy link

@bridgekeeper bridgekeeper bot commented on 4fb8c77 Sep 30, 2020

Please sign in to comment.