/**
* 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);
}
}
/**
* Generate the deprecated API list.
*
* @param deprapi list of deprecated API built already.
*/
protected void generateDeprecatedListFile(DeprecatedAPIListBuilder deprapi) throws IOException {
Content body = getHeader();
body.addContent(getContentsList(deprapi));
String memberTableSummary;
String[] memberTableHeader = new String[1];
HtmlTree div = new HtmlTree(HtmlTag.DIV);
div.addStyle(HtmlStyle.contentContainer);
for (int i = 0; i < DeprecatedAPIListBuilder.NUM_TYPES; i++) {
if (deprapi.hasDocumentation(i)) {
addAnchor(deprapi, i, div);
memberTableSummary =
configuration.getText(
"doclet.Member_Table_Summary",
configuration.getText(HEADING_KEYS[i]),
configuration.getText(SUMMARY_KEYS[i]));
memberTableHeader[0] =
configuration.getText(
"doclet.0_and_1",
configuration.getText(HEADER_KEYS[i]),
configuration.getText("doclet.Description"));
writers[i].addDeprecatedAPI(
deprapi.getList(i), HEADING_KEYS[i], memberTableSummary, memberTableHeader, div);
}
}
body.addContent(div);
addNavLinks(false, body);
addBottom(body);
printHtmlDocument(null, true, body);
}
/**
* Write the output to the file.
*
* @param body the documentation content to be written to the file.
* @param path the path for the file.
*/
private void writeToFile(Content body, DocPath path) throws IOException {
Content htmlDocType = configuration.isOutputHtml5() ? DocType.HTML5 : DocType.TRANSITIONAL;
Content head = new HtmlTree(HtmlTag.HEAD);
head.addContent(
HtmlTree.TITLE(new StringContent(configuration.getText("doclet.Window_Source_title"))));
head.addContent(getStyleSheetProperties());
Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(), head, body);
Content htmlDocument = new HtmlDocument(htmlDocType, htmlTree);
configuration.message.notice("doclet.Generating_0", path.getPath());
DocFile df = DocFile.createFileForOutput(configuration, path);
try (Writer w = df.openWriter()) {
htmlDocument.write(w, true);
}
}
/**
* 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 ");
}
}
/**
* Get the header for the deprecated API Listing.
*
* @return a content tree for the header
*/
public Content getHeader() {
String title = configuration.getText("doclet.Window_Deprecated_List");
Content bodyTree = getBody(true, getWindowTitle(title));
addTop(bodyTree);
addNavLinks(true, bodyTree);
return bodyTree;
}
/**
* 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);
}
}
/**
* Convert the given Class to an HTML.
*
* @param cd the class to convert.
* @param outputdir the name of the directory to output to.
*/
public void convertClass(ClassDoc cd, DocPath outputdir) {
if (cd == null) {
return;
}
try {
SourcePosition sp = cd.position();
if (sp == null) return;
Reader r;
// temp hack until we can update SourcePosition API.
if (sp instanceof SourcePositionImpl) {
FileObject fo = ((SourcePositionImpl) sp).fileObject();
if (fo == null) return;
r = fo.openReader(true);
} else {
File file = sp.file();
if (file == null) return;
r = new FileReader(file);
}
int lineno = 1;
String line;
relativePath = DocPaths.SOURCE_OUTPUT.resolve(DocPath.forPackage(cd)).invert();
Content body = getHeader();
Content pre = new HtmlTree(HtmlTag.PRE);
try (LineNumberReader reader = new LineNumberReader(r)) {
while ((line = reader.readLine()) != null) {
addLineNo(pre, lineno);
addLine(pre, line, lineno);
lineno++;
}
}
addBlankLines(pre);
Content div = HtmlTree.DIV(HtmlStyle.sourceContainer, pre);
body.addContent((configuration.allowTag(HtmlTag.MAIN)) ? HtmlTree.MAIN(div) : div);
writeToFile(body, outputdir.resolve(DocPath.forClass(cd)));
} catch (IOException e) {
e.printStackTrace();
}
}
/**
* Constructor.
*
* @param filename the file to be generated.
* @throws IOException
* @throws DocletAbortException
*/
public ClassUseWriter(
ConfigurationImpl configuration, ClassUseMapper mapper, DocPath filename, ClassDoc classdoc)
throws IOException {
super(configuration, filename);
this.classdoc = classdoc;
if (mapper.classToPackageAnnotations.containsKey(classdoc.qualifiedName()))
pkgToPackageAnnotations =
new TreeSet<>(mapper.classToPackageAnnotations.get(classdoc.qualifiedName()));
configuration.currentcd = classdoc;
this.pkgSet = new TreeSet<>();
this.pkgToClassTypeParameter = pkgDivide(mapper.classToClassTypeParam);
this.pkgToClassAnnotations = pkgDivide(mapper.classToClassAnnotations);
this.pkgToMethodTypeParameter = pkgDivide(mapper.classToExecMemberDocTypeParam);
this.pkgToMethodArgTypeParameter = pkgDivide(mapper.classToExecMemberDocArgTypeParam);
this.pkgToFieldTypeParameter = pkgDivide(mapper.classToFieldDocTypeParam);
this.pkgToFieldAnnotations = pkgDivide(mapper.annotationToFieldDoc);
this.pkgToMethodReturnTypeParameter = pkgDivide(mapper.classToExecMemberDocReturnTypeParam);
this.pkgToMethodAnnotations = pkgDivide(mapper.classToExecMemberDocAnnotations);
this.pkgToMethodParameterAnnotations = pkgDivide(mapper.classToExecMemberDocParamAnnotation);
this.pkgToSubclass = pkgDivide(mapper.classToSubclass);
this.pkgToSubinterface = pkgDivide(mapper.classToSubinterface);
this.pkgToImplementingClass = pkgDivide(mapper.classToImplementingClass);
this.pkgToField = pkgDivide(mapper.classToField);
this.pkgToMethodReturn = pkgDivide(mapper.classToMethodReturn);
this.pkgToMethodArgs = pkgDivide(mapper.classToMethodArgs);
this.pkgToMethodThrows = pkgDivide(mapper.classToMethodThrows);
this.pkgToConstructorAnnotations = pkgDivide(mapper.classToConstructorAnnotations);
this.pkgToConstructorParameterAnnotations = pkgDivide(mapper.classToConstructorParamAnnotation);
this.pkgToConstructorArgs = pkgDivide(mapper.classToConstructorArgs);
this.pkgToConstructorArgTypeParameter = pkgDivide(mapper.classToConstructorDocArgTypeParam);
this.pkgToConstructorThrows = pkgDivide(mapper.classToConstructorThrows);
// tmp test
if (pkgSet.size() > 0
&& mapper.classToPackage.containsKey(classdoc.qualifiedName())
&& !pkgSet.equals(mapper.classToPackage.get(classdoc.qualifiedName()))) {
configuration.root.printWarning(
"Internal error: package sets don't match: "
+ pkgSet
+ " with: "
+ mapper.classToPackage.get(classdoc.qualifiedName()));
}
methodSubWriter = new MethodWriterImpl(this);
constrSubWriter = new ConstructorWriterImpl(this);
fieldSubWriter = new FieldWriterImpl(this);
classSubWriter = new NestedClassWriterImpl(this);
classUseTableSummary =
configuration.getText("doclet.Use_Table_Summary", configuration.getText("doclet.classes"));
subclassUseTableSummary =
configuration.getText(
"doclet.Use_Table_Summary", configuration.getText("doclet.subclasses"));
subinterfaceUseTableSummary =
configuration.getText(
"doclet.Use_Table_Summary", configuration.getText("doclet.subinterfaces"));
fieldUseTableSummary =
configuration.getText("doclet.Use_Table_Summary", configuration.getText("doclet.fields"));
methodUseTableSummary =
configuration.getText("doclet.Use_Table_Summary", configuration.getText("doclet.methods"));
constructorUseTableSummary =
configuration.getText(
"doclet.Use_Table_Summary", configuration.getText("doclet.constructors"));
}
protected void serialWarning(SourcePosition pos, String key, String a1, String a2) {
if (configuration.serialwarn) {
configuration.getDocletSpecificMsg().warning(pos, key, a1, a2);
}
}
