/**
* Add deprecated information to the documentation tree
*
* @param deprmembers list of deprecated members
* @param headingKey the caption for the deprecated members table
* @param tableSummary the summary for the deprecated members table
* @param tableHeader table headers for the deprecated members table
* @param contentTree the content tree to which the deprecated members table will be added
*/
protected void addDeprecatedAPI(
List<Doc> deprmembers,
String headingKey,
String tableSummary,
String[] tableHeader,
Content contentTree) {
if (deprmembers.size() > 0) {
Content caption = writer.getTableCaption(configuration.getResource(headingKey));
Content table =
(configuration.isOutputHtml5())
? HtmlTree.TABLE(HtmlStyle.deprecatedSummary, caption)
: HtmlTree.TABLE(HtmlStyle.deprecatedSummary, tableSummary, caption);
table.addContent(writer.getSummaryTableHeader(tableHeader, "col"));
Content tbody = new HtmlTree(HtmlTag.TBODY);
for (int i = 0; i < deprmembers.size(); i++) {
ProgramElementDoc member = (ProgramElementDoc) deprmembers.get(i);
HtmlTree td = HtmlTree.TD(HtmlStyle.colOne, getDeprecatedLink(member));
if (member.tags("deprecated").length > 0)
writer.addInlineDeprecatedComment(member, member.tags("deprecated")[0], td);
HtmlTree tr = HtmlTree.TR(td);
if (i % 2 == 0) tr.addStyle(HtmlStyle.altColor);
else tr.addStyle(HtmlStyle.rowColor);
tbody.addContent(tr);
}
table.addContent(tbody);
Content li = HtmlTree.LI(HtmlStyle.blockList, table);
Content ul = HtmlTree.UL(HtmlStyle.blockList, li);
contentTree.addContent(ul);
}
}
/**
* Determine if the program element is shown, according to the given level of visibility.
*
* @param ped The given program element.
* @param visLevel The desired visibility level; "public", "protected", "package" or "private". If
* null, only check for an exclude tag.
* @return boolean Set if this element is shown.
*/
public boolean shownElement(Doc doc, String visLevel) {
// If a doc block contains @exclude or a similar such tag,
// then don't display it.
if (doExclude && excludeTag != null && doc != null) {
String rct = doc.getRawCommentText();
if (rct != null && rct.indexOf(excludeTag) != -1) {
return false;
}
}
if (visLevel == null) {
return true;
}
ProgramElementDoc ped = null;
if (doc instanceof ProgramElementDoc) {
ped = (ProgramElementDoc) doc;
}
if (visLevel.compareTo("private") == 0) return true;
// Show all that is not private
if (visLevel.compareTo("package") == 0) return !ped.isPrivate();
// Show all that is not private or package
if (visLevel.compareTo("protected") == 0) return !(ped.isPrivate() || ped.isPackagePrivate());
// Show all that is not private or package or protected,
// i.e. all that is public
if (visLevel.compareTo("public") == 0) return ped.isPublic();
return false;
} // shownElement()
/**
* Return true if the given <code>ProgramElement</code> is inherited by the class that is being
* documented.
*
* @param ped The <code>ProgramElement</code> being checked. return true if the <code>
* ProgramElement</code> is being inherited and false otherwise.
*/
protected boolean isInherited(ProgramElementDoc ped) {
if (ped.isPrivate()
|| (ped.isPackagePrivate()
&& !ped.containingPackage().equals(classdoc.containingPackage()))) {
return false;
}
return true;
}
/** Print the visibility adornment of element e prefixed by any stereotypes */
private String visibility(Options opt, ProgramElementDoc e) {
if (!opt.showVisibility) return " ";
if (e.isPrivate()) return "- ";
else if (e.isPublic()) return "+ ";
else if (e.isProtected()) return "# ";
else if (e.isPackagePrivate()) return "~ ";
else return " ";
}
public static boolean matches(ProgramElementDoc doc1, ProgramElementDoc doc2) {
if (doc1 instanceof ExecutableMemberDoc && doc2 instanceof ExecutableMemberDoc) {
ExecutableMemberDoc ed1 = (ExecutableMemberDoc) doc1;
ExecutableMemberDoc ed2 = (ExecutableMemberDoc) doc2;
return executableMembersEqual(ed1, ed2);
} else {
return doc1.name().equals(doc2.name());
}
}
/**
* Add use information to the documentation tree.
*
* @param mems list of program elements for which the use information will be added
* @param heading the section heading
* @param tableSummary the summary for the use table
* @param contentTree the content tree to which the use information will be added
*/
protected void addUseInfo(
List<? extends ProgramElementDoc> mems,
Content heading,
String tableSummary,
Content contentTree) {
if (mems == null) {
return;
}
List<? extends ProgramElementDoc> members = mems;
boolean printedUseTableHeader = false;
if (members.size() > 0) {
Content caption = writer.getTableCaption(heading);
Content table =
(configuration.isOutputHtml5())
? HtmlTree.TABLE(HtmlStyle.useSummary, caption)
: HtmlTree.TABLE(HtmlStyle.useSummary, tableSummary, caption);
Content tbody = new HtmlTree(HtmlTag.TBODY);
Iterator<? extends ProgramElementDoc> it = members.iterator();
for (int i = 0; it.hasNext(); i++) {
ProgramElementDoc pgmdoc = it.next();
ClassDoc cd = pgmdoc.containingClass();
if (!printedUseTableHeader) {
table.addContent(writer.getSummaryTableHeader(this.getSummaryTableHeader(pgmdoc), "col"));
printedUseTableHeader = true;
}
HtmlTree tr = new HtmlTree(HtmlTag.TR);
if (i % 2 == 0) {
tr.addStyle(HtmlStyle.altColor);
} else {
tr.addStyle(HtmlStyle.rowColor);
}
HtmlTree tdFirst = new HtmlTree(HtmlTag.TD);
tdFirst.addStyle(HtmlStyle.colFirst);
writer.addSummaryType(this, pgmdoc, tdFirst);
tr.addContent(tdFirst);
HtmlTree tdLast = new HtmlTree(HtmlTag.TD);
tdLast.addStyle(HtmlStyle.colLast);
if (cd != null && !(pgmdoc instanceof ConstructorDoc) && !(pgmdoc instanceof ClassDoc)) {
HtmlTree name = new HtmlTree(HtmlTag.SPAN);
name.addStyle(HtmlStyle.typeNameLabel);
name.addContent(cd.name() + ".");
tdLast.addContent(name);
}
addSummaryLink(
pgmdoc instanceof ClassDoc ? LinkInfoImpl.Kind.CLASS_USE : LinkInfoImpl.Kind.MEMBER,
cd,
pgmdoc,
tdLast);
writer.addSummaryLinkComment(this, pgmdoc, tdLast);
tr.addContent(tdLast);
tbody.addContent(tr);
}
table.addContent(tbody);
contentTree.addContent(table);
}
}
/** Return true if c has a @hidden tag associated with it */
private boolean hidden(ProgramElementDoc c) {
Tag tags[] = c.tags("hidden");
if (tags.length > 0) return true;
tags = c.tags("view");
if (tags.length > 0) return true;
Options opt;
if (c instanceof ClassDoc) opt = optionProvider.getOptionsFor((ClassDoc) c);
else opt = optionProvider.getOptionsFor(c.containingClass());
return opt.matchesHideExpression(c.toString());
}
/**
* Construct a new ConstructorWriterImpl.
*
* @param writer The writer for the class that the constructors belong to.
* @param classDoc the class being documented.
*/
public ConstructorWriterImpl(SubWriterHolderWriter writer, ClassDoc classDoc) {
super(writer, classDoc);
VisibleMemberMap visibleMemberMap =
new VisibleMemberMap(classDoc, VisibleMemberMap.CONSTRUCTORS, configuration);
List<ProgramElementDoc> constructors =
new ArrayList<>(visibleMemberMap.getMembersFor(classDoc));
for (ProgramElementDoc constructor : constructors) {
if (constructor.isProtected() || constructor.isPrivate()) {
setFoundNonPubConstructor(true);
}
}
}
/** {@inheritDoc} */
protected void addSummaryType(ProgramElementDoc member, Content tdSummaryType) {
if (foundNonPubConstructor) {
Content code = new HtmlTree(HtmlTag.CODE);
if (member.isProtected()) {
code.addContent("protected ");
} else if (member.isPrivate()) {
code.addContent("private ");
} else if (member.isPublic()) {
code.addContent(writer.getSpace());
} else {
code.addContent(configuration.getText("doclet.Package_private"));
}
tdSummaryType.addContent(code);
}
}
public static boolean isIncluded(String accessModFilter, ProgramElementDoc pd) {
boolean isPublic = pd.isPublic();
if (accessModFilter.equals("-public")) {
return isPublic;
}
boolean isProtected = pd.isProtected();
if (accessModFilter.equals("-protected")) {
return (isPublic || isProtected);
}
boolean isPackage = pd.isPackagePrivate();
if (accessModFilter.equals("-package")) {
return (isPublic || isProtected || isPackage);
}
return true;
}
/**
* Return true if the given Doc is deprecated.
*
* @param doc the Doc to check.
* @return true if the given Doc is deprecated.
*/
public static boolean isDeprecated(ProgramElementDoc doc) {
if (doc.tags("deprecated").length > 0) {
return true;
}
AnnotationDesc[] annotationDescList = doc.annotations();
for (int i = 0; i < annotationDescList.length; i++) {
if (annotationDescList[i]
.annotationType()
.qualifiedName()
.equals(java.lang.Deprecated.class.getName())) {
return true;
}
}
return false;
}
/**
* Add the modifier and type for the member in the member summary.
*
* @param member the member to add the type for
* @param type the type to add
* @param tdSummaryType the content tree to which the modified and type will be added
*/
protected void addModifierAndType(ProgramElementDoc member, Type type, Content tdSummaryType) {
HtmlTree code = new HtmlTree(HtmlTag.CODE);
addModifier(member, code);
if (type == null) {
if (member.isClass()) {
code.addContent("class");
} else {
code.addContent("interface");
}
code.addContent(writer.getSpace());
} else {
if (member instanceof ExecutableMemberDoc
&& ((ExecutableMemberDoc) member).typeParameters().length > 0) {
Content typeParameters =
((AbstractExecutableMemberWriter) this).getTypeParameters((ExecutableMemberDoc) member);
code.addContent(typeParameters);
// Code to avoid ugly wrapping in member summary table.
if (typeParameters.charCount() > 10) {
code.addContent(new HtmlTree(HtmlTag.BR));
} else {
code.addContent(writer.getSpace());
}
code.addContent(
writer.getLink(
new LinkInfoImpl(configuration, LinkInfoImpl.Kind.SUMMARY_RETURN_TYPE, type)));
} else {
code.addContent(
writer.getLink(
new LinkInfoImpl(configuration, LinkInfoImpl.Kind.SUMMARY_RETURN_TYPE, type)));
}
}
tdSummaryType.addContent(code);
}
protected boolean isBusinessMeaningful(ProgramElementDoc doc) {
final AnnotationDesc[] annotations = doc.annotations();
for (AnnotationDesc annotation : annotations) {
if (isBusinessMeaningful(annotation.annotationType())) {
return true;
}
}
return false;
}
/**
* Returns string representation of scope
*
* @param doc
* @return
*/
protected static String DetermineScope(ProgramElementDoc doc) {
ScopeModifier scope;
if (doc.isPrivate()) {
scope = ScopeModifier.PRIVATE;
} else if (doc.isProtected()) {
scope = ScopeModifier.PROTECTED;
} else if (doc.isPackagePrivate()) {
scope = ScopeModifier.PACKAGEPRIVATE;
} else if (doc.isPublic()) {
scope = ScopeModifier.PUBLIC;
} else {
log.error("No scope defined for: " + doc.name());
scope = ScopeModifier.PACKAGEPRIVATE;
}
return scope.toString().toLowerCase();
}
private Map<String, List<ProgramElementDoc>> pkgDivide(
Map<String, ? extends List<? extends ProgramElementDoc>> classMap) {
Map<String, List<ProgramElementDoc>> map = new HashMap<>();
List<? extends ProgramElementDoc> list = classMap.get(classdoc.qualifiedName());
if (list != null) {
Collections.sort(list);
for (ProgramElementDoc doc : list) {
PackageDoc pkg = doc.containingPackage();
pkgSet.add(pkg);
List<ProgramElementDoc> inPkg = map.get(pkg.name());
if (inPkg == null) {
inPkg = new ArrayList<>();
map.put(pkg.name(), inPkg);
}
inPkg.add(doc);
}
}
return map;
}
/**
* Add the member summary for the given class.
*
* @param classDoc the class that is being documented
* @param member the member being documented
* @param firstSentenceTags the first sentence tags to be added to the summary
* @param tableContents the list of contents to which the documentation will be added
* @param counter the counter for determining id and style for the table row
*/
public void addMemberSummary(
ClassDoc classDoc,
ProgramElementDoc member,
Tag[] firstSentenceTags,
List<Content> tableContents,
int counter) {
HtmlTree tdSummaryType = new HtmlTree(HtmlTag.TD);
tdSummaryType.addStyle(HtmlStyle.colFirst);
writer.addSummaryType(this, member, tdSummaryType);
HtmlTree tdSummary = new HtmlTree(HtmlTag.TD);
setSummaryColumnStyle(tdSummary);
addSummaryLink(classDoc, member, tdSummary);
writer.addSummaryLinkComment(this, member, firstSentenceTags, tdSummary);
HtmlTree tr = HtmlTree.TR(tdSummaryType);
tr.addContent(tdSummary);
if (member instanceof MethodDoc && !member.isAnnotationTypeElement()) {
int methodType =
(member.isStatic()) ? MethodTypes.STATIC.value() : MethodTypes.INSTANCE.value();
if (member.containingClass().isInterface()) {
methodType =
(((MethodDoc) member).isAbstract())
? methodType | MethodTypes.ABSTRACT.value()
: methodType | MethodTypes.DEFAULT.value();
} else {
methodType =
(((MethodDoc) member).isAbstract())
? methodType | MethodTypes.ABSTRACT.value()
: methodType | MethodTypes.CONCRETE.value();
}
if (utils.isDeprecated(member) || utils.isDeprecated(classdoc)) {
methodType = methodType | MethodTypes.DEPRECATED.value();
}
methodTypesOr = methodTypesOr | methodType;
String tableId = "i" + counter;
typeMap.put(tableId, methodType);
tr.addAttr(HtmlAttr.ID, tableId);
}
if (counter % 2 == 0) tr.addStyle(HtmlStyle.altColor);
else tr.addStyle(HtmlStyle.rowColor);
tableContents.add(tr);
}
/**
* Add the modifier for the member.
*
* @param member the member to add the type for
* @param code the content tree to which the modified will be added
*/
private void addModifier(ProgramElementDoc member, Content code) {
if (member.isProtected()) {
code.addContent("protected ");
} else if (member.isPrivate()) {
code.addContent("private ");
} else if (!member.isPublic()) { // Package private
code.addContent(configuration.getText("doclet.Package_private"));
code.addContent(" ");
}
if (member.isMethod()) {
if (!(member.containingClass().isInterface()) && ((MethodDoc) member).isAbstract()) {
code.addContent("abstract ");
}
// This check for isDefault() and the default modifier needs to be
// added for it to appear on the "Modifier and Type" column in the
// method summary section. Once the default modifier is added
// to the Modifier list on DocEnv and once it is updated to use the
// javax.lang.model.element.Modifier, we will need to remove this.
if (((MethodDoc) member).isDefault()) {
code.addContent("default ");
}
}
if (member.isStatic()) {
code.addContent("static ");
}
}
/**
* Add comment for each element in the index. If the element is deprecated and it has
* a @deprecated tag, use that comment. Else if the containing class for this element is
* deprecated, then add the word "Deprecated." at the start and then print the normal comment.
*
* @param element Index element
* @param contentTree the content tree to which the comment will be added
*/
protected void addComment(ProgramElementDoc element, Content contentTree) {
Tag[] tags;
Content span = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, deprecatedPhrase);
HtmlTree div = new HtmlTree(HtmlTag.DIV);
div.addStyle(HtmlStyle.block);
if (Util.isDeprecated(element)) {
div.addContent(span);
if ((tags = element.tags("deprecated")).length > 0)
addInlineDeprecatedComment(element, tags[0], div);
contentTree.addContent(div);
} else {
ClassDoc cont = element.containingClass();
while (cont != null) {
if (Util.isDeprecated(cont)) {
div.addContent(span);
contentTree.addContent(div);
break;
}
cont = cont.containingClass();
}
addSummaryComment(element, contentTree);
}
}
/**
* Add qualifiers for the program element as attributes.
*
* @param ped The given program element.
*/
public void addCommonModifiers(ProgramElementDoc ped, int indent) {
addSourcePosition(ped, indent);
// Static and final and visibility on one line
for (int i = 0; i < indent; i++) outputFile.print(" ");
outputFile.print("static=\"" + ped.isStatic() + "\"");
outputFile.print(" final=\"" + ped.isFinal() + "\"");
// Visibility
String visibility = null;
if (ped.isPublic()) visibility = "public";
else if (ped.isProtected()) visibility = "protected";
else if (ped.isPackagePrivate()) visibility = "package";
else if (ped.isPrivate()) visibility = "private";
outputFile.println(" visibility=\"" + visibility + "\"");
// Deprecation on its own line
for (int i = 0; i < indent; i++) outputFile.print(" ");
boolean isDeprecated = false;
Tag[] ta = ((Doc) ped).tags("deprecated");
if (ta.length != 0) {
isDeprecated = true;
}
if (ta.length > 1) {
System.out.println(
"JDiff: warning: multiple @deprecated tags found in comments for "
+ ped.name()
+ ". Using the first one only.");
System.out.println("Text is: " + ((Doc) ped).getRawCommentText());
}
if (isDeprecated) {
String text = ta[0].text(); // Use only one @deprecated tag
if (text != null && text.compareTo("") != 0) {
int idx = endOfFirstSentence(text);
if (idx == 0) {
// No useful comment
outputFile.print("deprecated=\"deprecated, no comment\"");
} else {
String fs = null;
if (idx == -1) fs = text;
else fs = text.substring(0, idx + 1);
String st = API.hideHTMLTags(fs);
outputFile.print("deprecated=\"" + st + "\"");
}
} else {
outputFile.print("deprecated=\"deprecated, no comment\"");
}
} else {
outputFile.print("deprecated=\"not deprecated\"");
}
} // addQualifiers()
public void printSummaryLinkComment(AbstractMemberWriter mw, ProgramElementDoc member) {
printSummaryLinkComment(mw, member, member.firstSentenceTags());
}
private boolean hasComment(ProgramElementDoc doc) {
return doc.commentText().trim().length() > 0;
}
protected String name(ProgramElementDoc member) {
return member.name();
}
/**
* Add the comment for the given member.
*
* @param member the member being documented.
* @param htmltree the content tree to which the comment will be added.
*/
protected void addComment(ProgramElementDoc member, Content htmltree) {
if (member.inlineTags().length > 0) {
writer.addInlineComment(member, htmltree);
}
}
public static AnnotationDesc findAnnotation(
final ProgramElementDoc programElementDoc, final Class<?>... soughtAnnotations) {
return findAnnotation(programElementDoc.annotations(), soughtAnnotations);
}