/* * Copyright (c) 1997, 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 * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package jdk.javadoc.internal.doclets.formats.html; import java.util.ArrayList; import java.util.List; import java.util.Set; import java.util.TreeSet; import java.util.stream.Collectors; import javax.lang.model.element.Element; import javax.lang.model.element.ExecutableElement; import javax.lang.model.element.Modifier; import javax.lang.model.element.TypeElement; import javax.lang.model.element.TypeParameterElement; import javax.lang.model.type.TypeMirror; import com.sun.source.doctree.DocTree; import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder; import jdk.javadoc.internal.doclets.formats.html.markup.Entity; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.Links; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.formats.html.markup.Table; import jdk.javadoc.internal.doclets.formats.html.markup.TableHeader; import jdk.javadoc.internal.doclets.toolkit.Content; import jdk.javadoc.internal.doclets.toolkit.MemberSummaryWriter; import jdk.javadoc.internal.doclets.toolkit.Resources; import jdk.javadoc.internal.doclets.toolkit.taglets.DeprecatedTaglet; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; import jdk.javadoc.internal.doclets.toolkit.util.Utils; import static javax.lang.model.element.Modifier.ABSTRACT; import static javax.lang.model.element.Modifier.NATIVE; import static javax.lang.model.element.Modifier.PUBLIC; import static javax.lang.model.element.Modifier.STRICTFP; import static javax.lang.model.element.Modifier.SYNCHRONIZED; /** * The base class for member writers. * *
This is NOT part of any supported API.
* If you write code that depends on this, you do so at your own risk.
* This code and its internal interfaces are subject to change or
* deletion without notice.
*/
public abstract class AbstractMemberWriter implements MemberSummaryWriter {
protected final HtmlConfiguration configuration;
protected final HtmlOptions options;
protected final Utils utils;
protected final SubWriterHolderWriter writer;
protected final Contents contents;
protected final Resources resources;
protected final Links links;
protected final TypeElement typeElement;
public final boolean nodepr;
protected boolean printedSummaryHeader = false;
public AbstractMemberWriter(SubWriterHolderWriter writer, TypeElement typeElement) {
this.configuration = writer.configuration;
this.options = configuration.getOptions();
this.writer = writer;
this.nodepr = options.noDeprecated;
this.typeElement = typeElement;
this.utils = configuration.utils;
this.contents = configuration.contents;
this.resources = configuration.resources;
this.links = writer.links;
}
public AbstractMemberWriter(SubWriterHolderWriter writer) {
this(writer, null);
}
/*** abstracts ***/
/**
* Add the summary label for the member.
*
* @param memberTree the content tree to which the label will be added
*/
public abstract void addSummaryLabel(Content memberTree);
/**
* Get the summary for the member summary table.
*
* @return a string for the table summary
*/
private String getTableSummaryX() { return null; }
/**
* Get the summary table header for the member.
*
* @param member the member to be documented
* @return the summary table header
*/
public abstract TableHeader getSummaryTableHeader(Element member);
private Table summaryTable;
private Table getSummaryTable() {
if (summaryTable == null) {
summaryTable = createSummaryTable();
}
return summaryTable;
}
/**
* Create the summary table for this element.
* The table should be created and initialized if needed, and configured
* so that it is ready to add content with {@link Table#addRow(Content[])}
* and similar methods.
*
* @return the summary table
*/
protected abstract Table createSummaryTable();
/**
* Add inherited summary label for the member.
*
* @param typeElement the TypeElement to which to link to
* @param inheritedTree the content tree to which the inherited summary label will be added
*/
public abstract void addInheritedSummaryLabel(TypeElement typeElement, Content inheritedTree);
/**
* Add the summary type for the member.
*
* @param member the member to be documented
* @param tdSummaryType the content tree to which the type will be added
*/
protected abstract void addSummaryType(Element member, Content tdSummaryType);
/**
* Add the summary link for the member.
*
* @param typeElement the TypeElement to be documented
* @param member the member to be documented
* @param tdSummary the content tree to which the link will be added
*/
protected void addSummaryLink(TypeElement typeElement, Element member, Content tdSummary) {
addSummaryLink(LinkInfoImpl.Kind.MEMBER, typeElement, member, tdSummary);
}
/**
* Add the summary link for the member.
*
* @param context the id of the context where the link will be printed
* @param typeElement the TypeElement to be documented
* @param member the member to be documented
* @param tdSummary the content tree to which the summary link will be added
*/
protected abstract void addSummaryLink(LinkInfoImpl.Kind context,
TypeElement typeElement, Element member, Content tdSummary);
/**
* Add the inherited summary link for the member.
*
* @param typeElement the TypeElement to be documented
* @param member the member to be documented
* @param linksTree the content tree to which the inherited summary link will be added
*/
protected abstract void addInheritedSummaryLink(TypeElement typeElement,
Element member, Content linksTree);
/**
* Get the deprecated link.
*
* @param member the member being linked to
* @return a content tree representing the link
*/
protected abstract Content getDeprecatedLink(Element member);
protected CharSequence makeSpace(int len) {
if (len <= 0) {
return "";
}
StringBuilder sb = new StringBuilder(len);
for (int i = 0; i < len; i++) {
sb.append(' ');
}
return sb;
}
/**
* 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(Element member, TypeMirror type,
Content tdSummaryType) {
HtmlTree code = new HtmlTree(HtmlTag.CODE);
addModifier(member, code);
if (type == null) {
code.add(utils.isClass(member) ? "class" : "interface");
code.add(Entity.NO_BREAK_SPACE);
} else {
List extends TypeParameterElement> list = utils.isExecutableElement(member)
? ((ExecutableElement)member).getTypeParameters()
: null;
if (list != null && !list.isEmpty()) {
Content typeParameters = ((AbstractExecutableMemberWriter) this)
.getTypeParameters((ExecutableElement)member);
code.add(typeParameters);
//Code to avoid ugly wrapping in member summary table.
if (typeParameters.charCount() > 10) {
code.add(new HtmlTree(HtmlTag.BR));
} else {
code.add(Entity.NO_BREAK_SPACE);
}
code.add(
writer.getLink(new LinkInfoImpl(configuration,
LinkInfoImpl.Kind.SUMMARY_RETURN_TYPE, type)));
} else {
code.add(
writer.getLink(new LinkInfoImpl(configuration,
LinkInfoImpl.Kind.SUMMARY_RETURN_TYPE, type)));
}
}
tdSummaryType.add(code);
}
/**
* 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(Element member, Content code) {
if (utils.isProtected(member)) {
code.add("protected ");
} else if (utils.isPrivate(member)) {
code.add("private ");
} else if (!utils.isPublic(member)) { // Package private
code.add(resources.getText("doclet.Package_private"));
code.add(" ");
}
boolean isAnnotatedTypeElement = utils.isAnnotationType(member.getEnclosingElement());
if (!isAnnotatedTypeElement && utils.isMethod(member)) {
if (!utils.isInterface(member.getEnclosingElement()) && utils.isAbstract(member)) {
code.add("abstract ");
}
if (utils.isDefault(member)) {
code.add("default ");
}
}
if (utils.isStatic(member)) {
code.add("static ");
}
}
/**
* Add the deprecated information for the given member.
*
* @param member the member being documented.
* @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,
writer.getTagletWriterInstance(false));
if (!output.isEmpty()) {
Content deprecatedContent = output;
Content div = HtmlTree.DIV(HtmlStyle.deprecationBlock, deprecatedContent);
contentTree.add(div);
}
}
/**
* 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(Element member, Content htmltree) {
if (!utils.getFullBody(member).isEmpty()) {
writer.addInlineComment(member, htmltree);
}
}
protected String name(Element member) {
return utils.getSimpleName(member);
}
/**
* Return true if the given ProgramElement
is inherited
* by the class that is being documented.
*
* @param ped The ProgramElement
being checked.
* return true if the ProgramElement
is being inherited and
* false otherwise.
*@return true if inherited
*/
protected boolean isInherited(Element ped){
return (!utils.isPrivate(ped) &&
(!utils.isPackagePrivate(ped) ||
ped.getEnclosingElement().equals(ped.getEnclosingElement())));
}
/**
* 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 contentTree the content tree to which the use information will be added
*/
protected void addUseInfo(List extends Element> mems, Content heading, Content contentTree) {
if (mems == null || mems.isEmpty()) {
return;
}
List extends Element> members = mems;
boolean printedUseTableHeader = false;
if (members.size() > 0) {
Table useTable = new Table(HtmlStyle.useSummary)
.setCaption(heading)
.setRowScopeColumn(1)
.setColumnStyles(HtmlStyle.colFirst, HtmlStyle.colSecond, HtmlStyle.colLast);
for (Element element : members) {
TypeElement te = (typeElement == null)
? utils.getEnclosingTypeElement(element)
: typeElement;
if (!printedUseTableHeader) {
useTable.setHeader(getSummaryTableHeader(element));
printedUseTableHeader = true;
}
Content summaryType = new ContentBuilder();
addSummaryType(element, summaryType);
Content typeContent = new ContentBuilder();
if (te != null
&& !utils.isConstructor(element)
&& !utils.isClass(element)
&& !utils.isInterface(element)
&& !utils.isAnnotationType(element)) {
HtmlTree name = new HtmlTree(HtmlTag.SPAN);
name.setStyle(HtmlStyle.typeNameLabel);
name.add(name(te) + ".");
typeContent.add(name);
}
addSummaryLink(utils.isClass(element) || utils.isInterface(element)
? LinkInfoImpl.Kind.CLASS_USE
: LinkInfoImpl.Kind.MEMBER,
te, element, typeContent);
Content desc = new ContentBuilder();
writer.addSummaryLinkComment(this, element, desc);
useTable.addRow(summaryType, typeContent, desc);
}
contentTree.add(useTable.toContent());
}
}
protected void serialWarning(Element e, String key, String a1, String a2) {
if (configuration.getOptions().serialWarn) {
configuration.messages.warning(e, key, a1, a2);
}
}
/**
* Add the member summary for the given class.
*
* @param tElement the class that is being documented
* @param member the member being documented
* @param firstSentenceTags the first sentence tags to be added to the summary
*/
@Override
public void addMemberSummary(TypeElement tElement, Element member,
List extends DocTree> firstSentenceTags) {
if (tElement != typeElement) {
throw new IllegalStateException();
}
Table table = getSummaryTable();
List