/**
* 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);
}
}
/** {@inheritDoc} */
public Content getHeader(String header) {
String pkgname =
(annotationType.containingPackage() != null)
? annotationType.containingPackage().name()
: "";
String clname = annotationType.name();
Content bodyTree = getBody(true, getWindowTitle(clname));
addTop(bodyTree);
addNavLinks(true, bodyTree);
bodyTree.addContent(HtmlConstants.START_OF_CLASS_DATA);
HtmlTree div = new HtmlTree(HtmlTag.DIV);
div.addStyle(HtmlStyle.header);
if (pkgname.length() > 0) {
Content pkgNameContent = new StringContent(pkgname);
Content pkgNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, pkgNameContent);
div.addContent(pkgNameDiv);
}
LinkInfoImpl linkInfo =
new LinkInfoImpl(configuration, LinkInfoImpl.Kind.CLASS_HEADER, annotationType);
Content headerContent = new StringContent(header);
Content heading =
HtmlTree.HEADING(HtmlConstants.CLASS_PAGE_HEADING, true, HtmlStyle.title, headerContent);
heading.addContent(getTypeParameterLinks(linkInfo));
div.addContent(heading);
bodyTree.addContent(div);
return bodyTree;
}
/**
* 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);
}
}
/** {@inheritDoc} */
public Content getPackageHeader(String heading) {
String pkgName = packageDoc.name();
Content bodyTree = getBody(true, getWindowTitle(pkgName));
addTop(bodyTree);
addNavLinks(true, bodyTree);
HtmlTree div = new HtmlTree(HtmlTag.DIV);
div.addStyle(HtmlStyle.header);
Content profileContent = new StringContent(profileName);
Content profileNameDiv = HtmlTree.DIV(HtmlStyle.subTitle, profileContent);
div.addContent(profileNameDiv);
Content annotationContent = new HtmlTree(HtmlTag.P);
addAnnotationInfo(packageDoc, annotationContent);
div.addContent(annotationContent);
Content tHeading =
HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true, HtmlStyle.title, packageLabel);
tHeading.addContent(getSpace());
Content packageHead = new RawHtml(heading);
tHeading.addContent(packageHead);
div.addContent(tHeading);
addDeprecationInfo(div);
if (packageDoc.inlineTags().length > 0 && !configuration.nocomment) {
HtmlTree docSummaryDiv = new HtmlTree(HtmlTag.DIV);
docSummaryDiv.addStyle(HtmlStyle.docSummary);
addSummaryComment(packageDoc, docSummaryDiv);
div.addContent(docSummaryDiv);
Content space = getSpace();
Content descLink =
getHyperLink(getDocLink(SectionName.PACKAGE_DESCRIPTION), descriptionLabel, "", "");
Content descPara = new HtmlTree(HtmlTag.P, seeLabel, space, descLink);
div.addContent(descPara);
}
bodyTree.addContent(div);
return bodyTree;
}
/** {@inheritDoc} */
public Content propertyTagOutput(Tag tag, String prefix) {
Content body = new ContentBuilder();
body.addContent(new RawHtml(prefix));
body.addContent(" ");
body.addContent(HtmlTree.CODE(new RawHtml(tag.text())));
body.addContent(".");
Content result = HtmlTree.P(body);
return result;
}
/** {@inheritDoc} */
public void addPackageDescription(Content packageContentTree) {
if (packageDoc.inlineTags().length > 0) {
packageContentTree.addContent(getMarkerAnchor(SectionName.PACKAGE_DESCRIPTION));
Content h2Content =
new StringContent(configuration.getText("doclet.Package_Description", packageDoc.name()));
packageContentTree.addContent(
HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true, h2Content));
addInlineComment(packageDoc, packageContentTree);
}
}
/**
* Add the navigation summary link.
*
* @param builder builder for the member to be documented
* @param label the label for the navigation
* @param type type to be documented
* @param liNav the content tree to which the navigation summary link will be added
*/
protected void addNavSummaryLink(
MemberSummaryBuilder builder, String label, int type, Content liNav) {
AbstractMemberWriter writer = ((AbstractMemberWriter) builder.getMemberSummaryWriter(type));
if (writer == null) {
liNav.addContent(getResource(label));
} else {
liNav.addContent(
writer.getNavSummaryLink(null, !builder.getVisibleMemberMap(type).noVisibleMembers()));
}
}
/**
* Add summary details to the navigation bar.
*
* @param subDiv the content tree to which the summary detail links will be added
*/
protected void addSummaryDetailLinks(Content subDiv) {
try {
Content div = HtmlTree.DIV(getNavSummaryLinks());
div.addContent(getNavDetailLinks());
subDiv.addContent(div);
} catch (Exception e) {
e.printStackTrace();
throw new DocletAbortException(e);
}
}
/**
* Add one line summary comment for the class.
*
* @param cd the class being documented
* @param dlTree the content tree to which the description will be added
*/
protected void addDescription(ClassDoc cd, Content dlTree) {
Content link =
getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.INDEX, cd).strong(true));
Content dt = HtmlTree.DT(link);
dt.addContent(" - ");
addClassInfo(cd, dt);
dlTree.addContent(dt);
Content dd = new HtmlTree(HtmlTag.DD);
addComment(cd, dd);
dlTree.addContent(dd);
}
/**
* Add description for Class, Field, Method or Constructor.
*
* @param member MemberDoc for the member of the Class Kind
* @param dlTree the content tree to which the description will be added
*/
protected void addDescription(MemberDoc member, Content dlTree) {
String name =
(member instanceof ExecutableMemberDoc)
? member.name() + ((ExecutableMemberDoc) member).flatSignature()
: member.name();
Content span =
HtmlTree.SPAN(HtmlStyle.memberNameLink, getDocLink(LinkInfoImpl.Kind.INDEX, member, name));
Content dt = HtmlTree.DT(span);
dt.addContent(" - ");
addMemberDesc(member, dt);
dlTree.addContent(dt);
Content dd = new HtmlTree(HtmlTag.DD);
addComment(member, dd);
dlTree.addContent(dd);
}
/**
* 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()))));
}
/**
* Build the member summary contents of the page.
*
* @param node the XML element that specifies which components to document
* @param classContentTree the content tree to which the documentation will be added
*/
public void buildMemberSummary(XMLNode node, Content classContentTree) throws Exception {
Content memberSummaryTree = writer.getMemberTreeHeader();
configuration
.getBuilderFactory()
.getMemberSummaryBuilder(writer)
.buildChildren(node, memberSummaryTree);
classContentTree.addContent(writer.getMemberSummaryTree(memberSummaryTree));
}
/** {@inheritDoc} */
public Content throwsTagOutput(ThrowsTag throwsTag) {
ContentBuilder body = new ContentBuilder();
Content excName =
(throwsTag.exceptionType() == null)
? new RawHtml(throwsTag.exceptionName())
: htmlWriter.getLink(
new LinkInfoImpl(
configuration, LinkInfoImpl.Kind.MEMBER, throwsTag.exceptionType()));
body.addContent(HtmlTree.CODE(excName));
Content desc = htmlWriter.commentTagsToContent(throwsTag, null, throwsTag.inlineTags(), false);
if (desc != null && !desc.isEmpty()) {
body.addContent(" - ");
body.addContent(desc);
}
HtmlTree result = HtmlTree.DD(body);
return result;
}
/** {@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);
}
}
/** {@inheritDoc} */
public void addClassesSummary(
ClassDoc[] classes,
String label,
String tableSummary,
String[] tableHeader,
Content packageSummaryContentTree) {
HtmlTree li = new HtmlTree(HtmlTag.LI);
li.addStyle(HtmlStyle.blockList);
addClassesSummary(classes, label, tableSummary, tableHeader, li, profileValue);
packageSummaryContentTree.addContent(li);
}
/**
* 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} */
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;
}
/**
* Get summary links for navigation bar.
*
* @return the content tree for the navigation summary links
*/
protected Content getNavSummaryLinks() throws Exception {
Content li = HtmlTree.LI(summaryLabel);
li.addContent(getSpace());
Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li);
MemberSummaryBuilder memberSummaryBuilder =
(MemberSummaryBuilder) configuration.getBuilderFactory().getMemberSummaryBuilder(this);
Content liNavField = new HtmlTree(HtmlTag.LI);
addNavSummaryLink(
memberSummaryBuilder,
"doclet.navField",
VisibleMemberMap.ANNOTATION_TYPE_FIELDS,
liNavField);
addNavGap(liNavField);
ulNav.addContent(liNavField);
Content liNavReq = new HtmlTree(HtmlTag.LI);
addNavSummaryLink(
memberSummaryBuilder,
"doclet.navAnnotationTypeRequiredMember",
VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED,
liNavReq);
addNavGap(liNavReq);
ulNav.addContent(liNavReq);
Content liNavOpt = new HtmlTree(HtmlTag.LI);
addNavSummaryLink(
memberSummaryBuilder,
"doclet.navAnnotationTypeOptionalMember",
VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL,
liNavOpt);
ulNav.addContent(liNavOpt);
return ulNav;
}
/**
* 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 member information for the unicode character along with the list of the members.
*
* @param unicode Unicode for which member list information to be generated
* @param memberlist List of members for the unicode character
* @param contentTree the content tree to which the information will be added
*/
protected void addContents(Character uc, List<? extends Doc> memberlist, Content contentTree) {
String unicode = uc.toString();
contentTree.addContent(getMarkerAnchorForIndex(unicode));
Content headContent = new StringContent(unicode);
Content heading =
HtmlTree.HEADING(HtmlConstants.CONTENT_HEADING, false, HtmlStyle.title, headContent);
contentTree.addContent(heading);
int memberListSize = memberlist.size();
// Display the list only if there are elements to be displayed.
if (memberListSize > 0) {
Content dl = new HtmlTree(HtmlTag.DL);
for (int i = 0; i < memberListSize; i++) {
Doc element = memberlist.get(i);
if (element instanceof MemberDoc) {
addDescription((MemberDoc) element, dl);
} else if (element instanceof ClassDoc) {
addDescription((ClassDoc) element, dl);
} else if (element instanceof PackageDoc) {
addDescription((PackageDoc) element, dl);
}
}
contentTree.addContent(dl);
}
}
/**
* 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);
}
}
/**
* Get detail links for the navigation bar.
*
* @return the content tree for the detail links
*/
protected Content getNavDetailLinks() throws Exception {
Content li = HtmlTree.LI(detailLabel);
li.addContent(getSpace());
Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li);
MemberSummaryBuilder memberSummaryBuilder =
(MemberSummaryBuilder) configuration.getBuilderFactory().getMemberSummaryBuilder(this);
AbstractMemberWriter writerField =
((AbstractMemberWriter)
memberSummaryBuilder.getMemberSummaryWriter(VisibleMemberMap.ANNOTATION_TYPE_FIELDS));
AbstractMemberWriter writerOptional =
((AbstractMemberWriter)
memberSummaryBuilder.getMemberSummaryWriter(
VisibleMemberMap.ANNOTATION_TYPE_MEMBER_OPTIONAL));
AbstractMemberWriter writerRequired =
((AbstractMemberWriter)
memberSummaryBuilder.getMemberSummaryWriter(
VisibleMemberMap.ANNOTATION_TYPE_MEMBER_REQUIRED));
Content liNavField = new HtmlTree(HtmlTag.LI);
if (writerField != null) {
writerField.addNavDetailLink(annotationType.fields().length > 0, liNavField);
} else {
liNavField.addContent(getResource("doclet.navField"));
}
addNavGap(liNavField);
ulNav.addContent(liNavField);
if (writerOptional != null) {
Content liNavOpt = new HtmlTree(HtmlTag.LI);
writerOptional.addNavDetailLink(annotationType.elements().length > 0, liNavOpt);
ulNav.addContent(liNavOpt);
} else if (writerRequired != null) {
Content liNavReq = new HtmlTree(HtmlTag.LI);
writerRequired.addNavDetailLink(annotationType.elements().length > 0, liNavReq);
ulNav.addContent(liNavReq);
} else {
Content liNav = HtmlTree.LI(getResource("doclet.navAnnotationTypeMember"));
ulNav.addContent(liNav);
}
return ulNav;
}
/**
* 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 void addAnnotationTypeSignature(String modifiers, Content annotationInfoTree) {
annotationInfoTree.addContent(new HtmlTree(HtmlTag.BR));
Content pre = new HtmlTree(HtmlTag.PRE);
addAnnotationInfo(annotationType, pre);
pre.addContent(modifiers);
LinkInfoImpl linkInfo =
new LinkInfoImpl(configuration, LinkInfoImpl.Kind.CLASS_SIGNATURE, annotationType);
Content annotationName = new StringContent(annotationType.name());
Content parameterLinks = getTypeParameterLinks(linkInfo);
if (configuration.linksource) {
addSrcLink(annotationType, annotationName, pre);
pre.addContent(parameterLinks);
} else {
Content span = HtmlTree.SPAN(HtmlStyle.memberNameLabel, annotationName);
span.addContent(parameterLinks);
pre.addContent(span);
}
annotationInfoTree.addContent(pre);
}
/**
* Handles the {@literal <ClassDoc>} tag.
*
* @param node the XML element that specifies which components to document
* @param contentTree the content tree to which the documentation will be added
*/
public void buildClassDoc(XMLNode node, Content contentTree) throws Exception {
String key;
if (isInterface) {
key = "doclet.Interface";
} else if (isEnum) {
key = "doclet.Enum";
} else {
key = "doclet.Class";
}
contentTree = writer.getHeader(configuration.getText(key) + " " + classDoc.name());
Content classContentTree = writer.getClassContentHeader();
buildChildren(node, classContentTree);
contentTree.addContent(classContentTree);
writer.addFooter(contentTree);
writer.printDocument(contentTree);
writer.close();
copyDocFiles();
}
/**
* Add gap between navigation bar elements.
*
* @param liNav the content tree to which the gap will be added
*/
protected void addNavGap(Content liNav) {
liNav.addContent(getSpace());
liNav.addContent("|");
liNav.addContent(getSpace());
}
/** {@inheritDoc} */
public void addFooter(Content contentTree) {
contentTree.addContent(HtmlConstants.END_OF_CLASS_DATA);
addNavLinks(false, contentTree);
addBottom(contentTree);
}
/**
* Build the member details contents of the page.
*
* @param node the XML element that specifies which components to document
* @param classContentTree the content tree to which the documentation will be added
*/
public void buildMemberDetails(XMLNode node, Content classContentTree) {
Content memberDetailsTree = writer.getMemberTreeHeader();
buildChildren(node, memberDetailsTree);
classContentTree.addContent(writer.getMemberDetailsTree(memberDetailsTree));
}
/**
* Build the class information tree documentation.
*
* @param node the XML element that specifies which components to document
* @param classContentTree the content tree to which the documentation will be added
*/
public void buildClassInfo(XMLNode node, Content classContentTree) {
Content classInfoTree = writer.getClassInfoTreeHeader();
buildChildren(node, classInfoTree);
classContentTree.addContent(writer.getClassInfo(classInfoTree));
}
