/**
* Add specific class kind listing. Also add label to the listing.
*
* @param arr Array of specific class kinds, namely Class or Interface or Exception or Error
* @param labelContent content tree of the label to be added
* @param contentTree the content tree to which the class kind listing will be added
*/
protected void addClassKindListing(ClassDoc[] arr, Content labelContent, Content contentTree) {
arr = Util.filterOutPrivateClasses(arr, configuration.javafx);
if (arr.length > 0) {
Arrays.sort(arr);
boolean printedHeader = false;
HtmlTree ul = new HtmlTree(HtmlTag.UL);
ul.setTitle(labelContent);
for (int i = 0; i < arr.length; i++) {
if (documentedClasses != null && !documentedClasses.contains(arr[i])) {
continue;
}
if (!Util.isCoreClass(arr[i]) || !configuration.isGeneratedDoc(arr[i])) {
continue;
}
if (!printedHeader) {
Content heading = HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, true, labelContent);
contentTree.addContent(heading);
printedHeader = true;
}
Content arr_i_name = new StringContent(arr[i].name());
if (arr[i].isInterface()) arr_i_name = HtmlTree.SPAN(HtmlStyle.interfaceName, arr_i_name);
Content link =
getLink(
new LinkInfoImpl(configuration, LinkInfoImpl.Kind.PACKAGE_FRAME, arr[i])
.label(arr_i_name)
.target("classFrame"));
Content li = HtmlTree.LI(link);
ul.addContent(li);
}
contentTree.addContent(ul);
}
}
/**
* Add the classkind (class, interface, exception), error of the class passed.
*
* @param cd the class being documented
* @param contentTree the content tree to which the class info will be added
*/
protected void addClassInfo(ClassDoc cd, Content contentTree) {
contentTree.addContent(
getResource(
"doclet.in",
Util.getTypeName(configuration, cd, false),
getPackageLink(cd.containingPackage(), Util.getPackageName(cd.containingPackage()))));
}
/**
* Generate a package summary page for the left-hand bottom frame. Construct the
* PackageFrameWriter object and then uses it generate the file.
*
* @param configuration the current configuration of the doclet.
* @param packageDoc The package for which "pacakge-frame.html" is to be generated.
*/
public static void generate(ConfigurationImpl configuration, PackageDoc packageDoc) {
PackageFrameWriter packgen;
try {
packgen = new PackageFrameWriter(configuration, packageDoc);
String pkgName = Util.getPackageName(packageDoc);
Content body = packgen.getBody(false, packgen.getWindowTitle(pkgName));
Content pkgNameContent = new StringContent(pkgName);
Content heading =
HtmlTree.HEADING(
HtmlConstants.TITLE_HEADING,
HtmlStyle.bar,
packgen.getTargetPackageLink(packageDoc, "classFrame", pkgNameContent));
body.addContent(heading);
HtmlTree div = new HtmlTree(HtmlTag.DIV);
div.addStyle(HtmlStyle.indexContainer);
packgen.addClassListing(div);
body.addContent(div);
packgen.printHtmlDocument(
configuration.metakeywords.getMetaKeywords(packageDoc), false, body);
packgen.close();
} catch (IOException exc) {
configuration.standardmessage.error(
"doclet.exception_encountered", exc.toString(), DocPaths.PACKAGE_FRAME.getPath());
throw new DocletAbortException(exc);
}
}
/**
* Add class listing for all the classes in this package. Divide class listing as per the class
* kind and generate separate listing for Classes, Interfaces, Exceptions and Errors.
*
* @param contentTree the content tree to which the listing will be added
*/
protected void addClassListing(Content contentTree) {
Configuration config = configuration;
if (packageDoc.isIncluded()) {
addClassKindListing(packageDoc.interfaces(), getResource("doclet.Interfaces"), contentTree);
addClassKindListing(packageDoc.ordinaryClasses(), getResource("doclet.Classes"), contentTree);
addClassKindListing(packageDoc.enums(), getResource("doclet.Enums"), contentTree);
addClassKindListing(packageDoc.exceptions(), getResource("doclet.Exceptions"), contentTree);
addClassKindListing(packageDoc.errors(), getResource("doclet.Errors"), contentTree);
addClassKindListing(
packageDoc.annotationTypes(), getResource("doclet.AnnotationTypes"), contentTree);
} else {
String name = Util.getPackageName(packageDoc);
addClassKindListing(
config.classDocCatalog.interfaces(name), getResource("doclet.Interfaces"), contentTree);
addClassKindListing(
config.classDocCatalog.ordinaryClasses(name), getResource("doclet.Classes"), contentTree);
addClassKindListing(
config.classDocCatalog.enums(name), getResource("doclet.Enums"), contentTree);
addClassKindListing(
config.classDocCatalog.exceptions(name), getResource("doclet.Exceptions"), contentTree);
addClassKindListing(
config.classDocCatalog.errors(name), getResource("doclet.Errors"), contentTree);
addClassKindListing(
config.classDocCatalog.annotationTypes(name),
getResource("doclet.AnnotationTypes"),
contentTree);
}
}
/**
* Add one line summary comment for the package.
*
* @param pkg the package to be documented
* @param dlTree the content tree to which the description will be added
*/
protected void addDescription(PackageDoc pkg, Content dlTree) {
Content link = getPackageLink(pkg, new StringContent(Util.getPackageName(pkg)));
Content dt = HtmlTree.DT(link);
dt.addContent(" - ");
dt.addContent(getResource("doclet.package"));
dt.addContent(" " + pkg.name());
dlTree.addContent(dt);
Content dd = new HtmlTree(HtmlTag.DD);
addSummaryComment(pkg, dd);
dlTree.addContent(dd);
}
/** {@inheritDoc} */
public Content deprecatedTagOutput(Doc doc) {
ContentBuilder result = new ContentBuilder();
Tag[] deprs = doc.tags("deprecated");
if (doc instanceof ClassDoc) {
if (Util.isDeprecated((ProgramElementDoc) doc)) {
result.addContent(
HtmlTree.SPAN(
HtmlStyle.deprecatedLabel,
new StringContent(configuration.getText("doclet.Deprecated"))));
result.addContent(RawHtml.nbsp);
if (deprs.length > 0) {
Tag[] commentTags = deprs[0].inlineTags();
if (commentTags.length > 0) {
result.addContent(commentTagsToOutput(null, doc, deprs[0].inlineTags(), false));
}
}
}
} else {
MemberDoc member = (MemberDoc) doc;
if (Util.isDeprecated((ProgramElementDoc) doc)) {
result.addContent(
HtmlTree.SPAN(
HtmlStyle.deprecatedLabel,
new StringContent(configuration.getText("doclet.Deprecated"))));
result.addContent(RawHtml.nbsp);
if (deprs.length > 0) {
Content body = commentTagsToOutput(null, doc, deprs[0].inlineTags(), false);
if (!body.isEmpty()) result.addContent(HtmlTree.SPAN(HtmlStyle.deprecationComment, body));
}
} else {
if (Util.isDeprecated(member.containingClass())) {
result.addContent(
HtmlTree.SPAN(
HtmlStyle.deprecatedLabel,
new StringContent(configuration.getText("doclet.Deprecated"))));
result.addContent(RawHtml.nbsp);
}
}
}
return result;
}
/**
* Build the signature of the current class.
*
* @param node the XML element that specifies which components to document
* @param classInfoTree the content tree to which the documentation will be added
*/
public void buildClassSignature(XMLNode node, Content classInfoTree) {
StringBuilder modifiers = new StringBuilder(classDoc.modifiers());
modifiers.append(modifiers.length() == 0 ? "" : " ");
if (isEnum) {
modifiers.append("enum ");
int index;
if ((index = modifiers.indexOf("abstract")) >= 0) {
modifiers.delete(index, index + "abstract".length());
modifiers = new StringBuilder(Util.replaceText(modifiers.toString(), " ", " "));
}
if ((index = modifiers.indexOf("final")) >= 0) {
modifiers.delete(index, index + "final".length());
modifiers = new StringBuilder(Util.replaceText(modifiers.toString(), " ", " "));
}
// } else if (classDoc.isAnnotationType()) {
// modifiers.append("@interface ");
} else if (!isInterface) {
modifiers.append("class ");
}
writer.addClassSignature(modifiers.toString(), classInfoTree);
}
/** Copy the doc files for the current ClassDoc if necessary. */
private void copyDocFiles() {
PackageDoc containingPackage = classDoc.containingPackage();
if ((configuration.packages == null
|| Arrays.binarySearch(configuration.packages, containingPackage) < 0)
&& !containingPackagesSeen.contains(containingPackage.name())) {
// Only copy doc files dir if the containing package is not
// documented AND if we have not documented a class from the same
// package already. Otherwise, we are making duplicate copies.
Util.copyDocFiles(configuration, containingPackage);
containingPackagesSeen.add(containingPackage.name());
}
}
/**
* 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 the package deprecation information to the documentation tree.
*
* @param div the content tree to which the deprecation information will be added
*/
public void addDeprecationInfo(Content div) {
Tag[] deprs = packageDoc.tags("deprecated");
if (Util.isDeprecated(packageDoc)) {
HtmlTree deprDiv = new HtmlTree(HtmlTag.DIV);
deprDiv.addStyle(HtmlStyle.deprecatedContent);
Content deprPhrase = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, deprecatedPhrase);
deprDiv.addContent(deprPhrase);
if (deprs.length > 0) {
Tag[] commentTags = deprs[0].inlineTags();
if (commentTags.length > 0) {
addInlineDeprecatedComment(packageDoc, deprs[0], deprDiv);
}
}
div.addContent(deprDiv);
}
}
/**
* Construct a new ClassBuilder.
*
* @param context the build context
* @param classDoc the class being documented.
* @param writer the doclet specific writer.
*/
private ClassBuilder(Context context, ClassDoc classDoc, ClassWriter writer) {
super(context);
this.classDoc = classDoc;
this.writer = writer;
if (classDoc.isInterface()) {
isInterface = true;
isEnum = false;
} else if (classDoc.isEnum()) {
isInterface = false;
isEnum = true;
Util.setEnumDocumentation(configuration, classDoc);
} else {
isInterface = false;
isEnum = false;
}
}
/** {@inheritDoc} */
public void addAnnotationTypeDeprecationInfo(Content annotationInfoTree) {
Content hr = new HtmlTree(HtmlTag.HR);
annotationInfoTree.addContent(hr);
Tag[] deprs = annotationType.tags("deprecated");
if (Util.isDeprecated(annotationType)) {
Content deprLabel = HtmlTree.SPAN(HtmlStyle.deprecatedLabel, deprecatedPhrase);
Content div = HtmlTree.DIV(HtmlStyle.block, deprLabel);
if (deprs.length > 0) {
Tag[] commentTags = deprs[0].inlineTags();
if (commentTags.length > 0) {
div.addContent(getSpace());
addInlineDeprecatedComment(annotationType, deprs[0], div);
}
}
annotationInfoTree.addContent(div);
}
}
/**
* Add description about the Static Varible/Method/Constructor for a member.
*
* @param member MemberDoc for the member within the Class Kind
* @param contentTree the content tree to which the member description will be added
*/
protected void addMemberDesc(MemberDoc member, Content contentTree) {
ClassDoc containing = member.containingClass();
String classdesc = Util.getTypeName(configuration, containing, true) + " ";
if (member.isField()) {
if (member.isStatic()) {
contentTree.addContent(getResource("doclet.Static_variable_in", classdesc));
} else {
contentTree.addContent(getResource("doclet.Variable_in", classdesc));
}
} else if (member.isConstructor()) {
contentTree.addContent(getResource("doclet.Constructor_for", classdesc));
} else if (member.isMethod()) {
if (member.isStatic()) {
contentTree.addContent(getResource("doclet.Static_method_in", classdesc));
} else {
contentTree.addContent(getResource("doclet.Method_in", classdesc));
}
}
addPreQualifiedClassLink(LinkInfoImpl.Kind.INDEX, containing, false, contentTree);
}
/** {@inheritDoc} */
protected Content codeTagOutput(Tag tag) {
Content result = HtmlTree.CODE(new StringContent(Util.normalizeNewlines(tag.text())));
return result;
}
/** {@inheritDoc} */
protected Content literalTagOutput(Tag tag) {
Content result = new StringContent(Util.normalizeNewlines(tag.text()));
return result;
}
