/**
* Build the summaries for the methods that belong to the given class.
*
* @param node the XML element that specifies which components to document
* @param classContentTree content tree to which the documentation will be added
*/
public void buildSerializableMethods(XMLNode node, Content classContentTree) {
Content serializableMethodTree = methodWriter.getSerializableMethodsHeader();
MemberDoc[] members = currentClass.serializationMethods();
int membersLength = members.length;
if (membersLength > 0) {
for (int i = 0; i < membersLength; i++) {
currentMember = members[i];
Content methodsContentTree = methodWriter.getMethodsContentHeader((i == membersLength - 1));
buildChildren(node, methodsContentTree);
serializableMethodTree.addContent(methodsContentTree);
}
}
if (currentClass.serializationMethods().length > 0) {
classContentTree.addContent(
methodWriter.getSerializableMethods(
configuration.getText("doclet.Serialized_Form_methods"), serializableMethodTree));
if (currentClass.isSerializable() && !currentClass.isExternalizable()) {
if (currentClass.serializationMethods().length == 0) {
Content noCustomizationMsg =
methodWriter.getNoCustomizationMsg(
configuration.getText("doclet.Serializable_no_customization"));
classContentTree.addContent(
methodWriter.getSerializableMethods(
configuration.getText("doclet.Serialized_Form_methods"), noCustomizationMsg));
}
}
}
}
/**
* 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()))));
}
protected void write(OutputStream o, ClassDoc clazz) throws ClassNotFoundException {
String cname = mangleClassName(clazz.qualifiedName());
PrintWriter pw = wrapWriter(o);
fields = clazz.fields();
methods = clazz.methods();
generateDeclsForClass(pw, clazz, cname);
}
/**
* Constructor.
*
* @param filename the file to be generated.
* @throws IOException
* @throws DocletAbortException
*/
public PackageUseWriter(
ConfigurationImpl configuration, ClassUseMapper mapper, DocPath filename, PackageDoc pkgdoc)
throws IOException {
super(configuration, DocPath.forPackage(pkgdoc).resolve(filename));
this.pkgdoc = pkgdoc;
// by examining all classes in this package, find what packages
// use these classes - produce a map between using package and
// used classes.
ClassDoc[] content = pkgdoc.allClasses();
for (int i = 0; i < content.length; ++i) {
ClassDoc usedClass = content[i];
Set<ClassDoc> usingClasses = mapper.classToClass.get(usedClass.qualifiedName());
if (usingClasses != null) {
for (Iterator<ClassDoc> it = usingClasses.iterator(); it.hasNext(); ) {
ClassDoc usingClass = it.next();
PackageDoc usingPackage = usingClass.containingPackage();
Set<ClassDoc> usedClasses = usingPackageToUsedClasses.get(usingPackage.name());
if (usedClasses == null) {
usedClasses = new TreeSet<ClassDoc>();
usingPackageToUsedClasses.put(Util.getPackageName(usingPackage), usedClasses);
}
usedClasses.add(usedClass);
}
}
}
}
/** Builds a view along with its parent views, recursively */
private static View buildView(RootDoc root, ClassDoc viewClass, OptionProvider provider) {
ClassDoc superClass = viewClass.superclass();
if (superClass == null || superClass.tags("view").length == 0)
return new View(root, viewClass, provider);
return new View(root, viewClass, buildView(root, superClass, provider));
}
/** Returns true if the given element is hidden. */
private static boolean isHidden(Doc doc) {
// Methods, fields, constructors.
if (doc instanceof MemberDoc) {
return hasHideAnnotation(doc);
}
// Classes, interfaces, enums, annotation types.
if (doc instanceof ClassDoc) {
ClassDoc classDoc = (ClassDoc) doc;
// Check the containing package.
if (hasHideAnnotation(classDoc.containingPackage())) {
return true;
}
// Check the class doc and containing class docs if this is a
// nested class.
ClassDoc current = classDoc;
do {
if (hasHideAnnotation(current)) {
return true;
}
current = current.containingClass();
} while (current != null);
}
return false;
}
/**
* Builds the views according to the parameters on the command line
*
* @param opt The options
* @param srcRootDoc The RootDoc for the source classes
* @param viewRootDoc The RootDoc for the view classes (may be different, or may be the same as
* the srcRootDoc)
*/
public static View[] buildViews(Options opt, RootDoc srcRootDoc, RootDoc viewRootDoc) {
if (opt.viewName != null) {
ClassDoc viewClass = viewRootDoc.classNamed(opt.viewName);
if (viewClass == null) {
System.out.println(
"View " + opt.viewName + " not found! Exiting without generating any output.");
return null;
}
if (viewClass.tags("view").length == 0) {
System.out.println(viewClass + " is not a view!");
return null;
}
if (viewClass.isAbstract()) {
System.out.println(viewClass + " is an abstract view, no output will be generated!");
return null;
}
return new View[] {buildView(srcRootDoc, viewClass, opt)};
} else if (opt.findViews) {
List<View> views = new ArrayList<View>();
ClassDoc[] classes = viewRootDoc.classes();
// find view classes
for (int i = 0; i < classes.length; i++)
if (classes[i].tags("view").length > 0 && !classes[i].isAbstract())
views.add(buildView(srcRootDoc, classes[i], opt));
return views.toArray(new View[views.size()]);
} else return new View[0];
}
private static void addAllInterfaceTypes(
Map<ClassDoc, Type> results,
Type type,
Type[] interfaceTypes,
boolean raw,
Configuration configuration) {
for (int i = 0; i < interfaceTypes.length; i++) {
Type interfaceType = interfaceTypes[i];
ClassDoc interfaceClassDoc = interfaceType.asClassDoc();
if (!(interfaceClassDoc.isPublic()
|| (configuration != null && isLinkable(interfaceClassDoc, configuration)))) {
continue;
}
if (raw) interfaceType = interfaceType.asClassDoc();
results.put(interfaceClassDoc, interfaceType);
List<Type> superInterfaces = getAllInterfaces(interfaceType, configuration);
for (Iterator<Type> iter = superInterfaces.iterator(); iter.hasNext(); ) {
Type superInterface = iter.next();
results.put(superInterface.asClassDoc(), superInterface);
}
}
if (type instanceof ParameterizedType)
findAllInterfaceTypes(results, (ParameterizedType) type, configuration);
else if (((ClassDoc) type).typeParameters().length == 0)
findAllInterfaceTypes(results, (ClassDoc) type, raw, configuration);
else findAllInterfaceTypes(results, (ClassDoc) type, true, configuration);
}
/**
* Return the qualified name of the <code>ClassDoc</code> if it's qualifier is not excluded.
* Otherwise, return the unqualified <code>ClassDoc</code> name.
*
* @param cd the <code>ClassDoc</code> to check.
*/
public String getClassName(ClassDoc cd) {
PackageDoc pd = cd.containingPackage();
if (pd != null && shouldExcludeQualifier(cd.containingPackage().name())) {
return cd.name();
} else {
return cd.qualifiedName();
}
}
/**
* 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);
}
}
/**
* Print the specified relation
*
* @param from the source class
* @param to the destination class
*/
private void relation(
Options opt,
RelationType rt,
ClassDoc from,
ClassDoc to,
String tailLabel,
String label,
String headLabel) {
relation(opt, rt, from, from.toString(), to, to.toString(), tailLabel, label, headLabel);
}
/**
* Return the sub-class/interface list for the class/interface passed.
*
* @param cd class/interface whose sub-class/interface list is required.
* @param isEnum true if the subclasses should be forced to come from the enum tree.
*/
public List subs(ClassDoc cd, boolean isEnum) {
if (isEnum) {
return get(subEnums, cd);
} else if (cd.isAnnotationType()) {
return get(subAnnotationTypes, cd);
} else if (cd.isInterface()) {
return get(subinterfaces, cd);
} else if (cd.isClass()) {
return get(subclasses, cd);
} else {
return null;
}
}
/**
* Given an array of <code>ParamTag</code>s,return its string representation.
*
* @param holder the member that holds the param tags.
* @param writer the TagletWriter that will write this tag.
* @return the TagletOutput representation of these <code>ParamTag</code>s.
*/
public TagletOutput getTagletOutput(Doc holder, TagletWriter writer) {
if (holder instanceof ExecutableMemberDoc) {
ExecutableMemberDoc member = (ExecutableMemberDoc) holder;
TagletOutput output =
getTagletOutput(false, member, writer, member.typeParameters(), member.typeParamTags());
output.appendOutput(
getTagletOutput(true, member, writer, member.parameters(), member.paramTags()));
return output;
} else {
ClassDoc classDoc = (ClassDoc) holder;
return getTagletOutput(
false, classDoc, writer, classDoc.typeParameters(), classDoc.typeParamTags());
}
}
protected void process(ClassDoc clss) {
writer.println("");
writer.println("## *" + clss.simpleTypeName() + "*");
writer.println(clss.commentText());
writer.println("");
if (clss.isEnum()) {
for (FieldDoc field : clss.enumConstants()) {
printEnumConstant(field);
}
writer.println("");
for (MethodDoc method : clss.methods(false)) {
printMethod(method);
}
} else if (clss.isInterface()) {
/*
for (ClassDoc subClass : getDerivedClassessubclasses( clss ))
{
printSubClass(subClass);
}
*/
} else {
for (FieldDoc field : clss.fields(false)) {
printField(field);
}
for (MethodDoc method : clss.methods(false)) {
printMethod(method);
}
}
}
/**
* Build the field information.
*
* @param node the XML element that specifies which components to document
* @param fieldsContentTree content tree to which the documentation will be added
*/
public void buildFieldInfo(XMLNode node, Content fieldsContentTree) {
if (configuration.nocomment) {
return;
}
FieldDoc field = (FieldDoc) currentMember;
ClassDoc cd = field.containingClass();
// Process default Serializable field.
if ((field.tags("serial").length == 0) && !field.isSynthetic() && configuration.serialwarn) {
configuration.message.warning(
field.position(), "doclet.MissingSerialTag", cd.qualifiedName(), field.name());
}
fieldWriter.addMemberDescription(field, fieldsContentTree);
fieldWriter.addMemberTags(field, fieldsContentTree);
}
/**
* Initialises the methods in this controller annotated with <code>@RequestMapping</code> in the
* source class.
*
* @param classDoc the controller's Java documentation object.
*/
private void initMethods(Controller controller, final ClassDoc classDoc) {
ArrayList<Method> methods = new ArrayList<Method>();
for (int i = 0; classDoc.methods(false) != null && i < classDoc.methods(false).length; i++) {
if (isAnnotated(classDoc.methods(false)[i], RequestMapping.class)) {
methods.add(new MethodBuilder().build(new Method(), classDoc.methods(false)[i]));
}
}
controller.setMethods(methods);
if (methods.size() == 0) {
LOG.warn("No methods found with @RequestMapping tag");
}
}
public static Type findSuperTypeFromClass(final ClassDoc klass, String typeName) {
if (klass.qualifiedTypeName().equals(typeName)) return klass;
// find it in the interfaces
final Type foundType = findSuperTypeFromInterface(klass, typeName);
if (foundType != null) {
return foundType;
}
final Type superclass = klass.superclassType();
if (superclass != null && superclass.asClassDoc() != null) {
return findSuperTypeFromClass(superclass.asClassDoc(), typeName);
}
return null;
}
public static Type findSuperTypeFromInterface(final ClassDoc klass, String typeName) {
// find it in the interfaces
final Type[] interfaceTypes = klass.interfaceTypes();
for (final Type interfaceType : interfaceTypes) {
final ClassDoc interfaceClassDoc = interfaceType.asClassDoc();
if (interfaceClassDoc != null) {
if (interfaceClassDoc.qualifiedTypeName().equals(typeName)) return interfaceClassDoc;
final Type foundType = findSuperTypeFromInterface(interfaceClassDoc, typeName);
if (foundType != null) {
return foundType;
}
}
}
return null;
}
/** The documentation for values() and valueOf() in Enums are set by the doclet. */
public static void setEnumDocumentation(Configuration configuration, ClassDoc classDoc) {
MethodDoc[] methods = classDoc.methods();
for (int j = 0; j < methods.length; j++) {
MethodDoc currentMethod = methods[j];
if (currentMethod.name().equals("values") && currentMethod.parameters().length == 0) {
currentMethod.setRawCommentText(
configuration.getText("doclet.enum_values_doc", classDoc.name()));
} else if (currentMethod.name().equals("valueOf") && currentMethod.parameters().length == 1) {
Type paramType = currentMethod.parameters()[0].type();
if (paramType != null && paramType.qualifiedTypeName().equals(String.class.getName())) {
currentMethod.setRawCommentText(configuration.getText("doclet.enum_valueof_doc"));
}
}
}
}
/**
* Given a class, return the closest visible super class.
*
* @param classDoc the class we are searching the parent for.
* @param configuration the current configuration of the doclet.
* @return the closest visible super class. Return null if it cannot be found (i.e. classDoc is
* java.lang.Object).
*/
public static ClassDoc getFirstVisibleSuperClassCD(
ClassDoc classDoc, Configuration configuration) {
if (classDoc == null) {
return null;
}
ClassDoc supClassDoc = classDoc.superclass();
while (supClassDoc != null
&& (!(supClassDoc.isPublic() || isLinkable(supClassDoc, configuration)))) {
supClassDoc = supClassDoc.superclass();
}
if (classDoc.equals(supClassDoc)) {
return null;
}
return supClassDoc;
}
protected void generateDeclsForClass(PrintWriter pw, ClassDoc clazz, String cname)
throws ClassNotFoundException {
doneHandleTypes = new Hashtable();
/* The following handle types are predefined in "typedefs.h". Suppress
inclusion in the output by generating them "into the blue" here. */
genHandleType(null, "java.lang.Class");
genHandleType(null, "java.lang.ClassLoader");
genHandleType(null, "java.lang.Object");
genHandleType(null, "java.lang.String");
genHandleType(null, "java.lang.Thread");
genHandleType(null, "java.lang.ThreadGroup");
genHandleType(null, "java.lang.Throwable");
pw.println("/* LLNI Header for class " + clazz.qualifiedName() + " */" + lineSep);
pw.println("#ifndef _Included_" + cname);
pw.println("#define _Included_" + cname);
pw.println("#include \"typedefs.h\"");
pw.println("#include \"llni.h\"");
pw.println("#include \"jni.h\"" + lineSep);
forwardDecls(pw, clazz);
structSectionForClass(pw, clazz, cname);
methodSectionForClass(pw, clazz, cname);
pw.println("#endif");
}
/**
* 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;
}
}
/**
* Get the tree link.
*
* @return a content tree for the tree link
*/
protected Content getNavLinkTree() {
Content linkContent =
classdoc.containingPackage().isIncluded()
? getHyperLink(DocPath.parent.resolve(DocPaths.PACKAGE_TREE), treeLabel)
: getHyperLink(pathToRoot.resolve(DocPaths.OVERVIEW_TREE), treeLabel);
Content li = HtmlTree.LI(linkContent);
return li;
}
/**
* Write out class use pages.
*
* @throws DocletAbortException
*/
public static void generate(ConfigurationImpl configuration, ClassTree classtree) {
ClassUseMapper mapper = new ClassUseMapper(configuration.root, classtree);
for (ClassDoc aClass : configuration.root.classes()) {
// If -nodeprecated option is set and the containing package is marked
// as deprecated, do not generate the class-use page. We will still generate
// the class-use page if the class is marked as deprecated but the containing
// package is not since it could still be linked from that package-use page.
if (!(configuration.nodeprecated && Util.isDeprecated(aClass.containingPackage())))
ClassUseWriter.generate(configuration, mapper, aClass);
}
for (PackageDoc pkg : configuration.packages) {
// If -nodeprecated option is set and the package is marked
// as deprecated, do not generate the package-use page.
if (!(configuration.nodeprecated && Util.isDeprecated(pkg)))
PackageUseWriter.generate(configuration, mapper, pkg);
}
}
/**
* Get the name of the package, this class is in.
*
* @param cd ClassDoc.
*/
public String getPkgName(ClassDoc cd) {
String pkgName = cd.containingPackage().name();
if (pkgName.length() > 0) {
pkgName += ".";
return pkgName;
}
return "";
}
/**
* For the class return all implemented interfaces including the superinterfaces of the
* implementing interfaces, also iterate over for all the superclasses. For interface return all
* the extended interfaces as well as superinterfaces for those extended interfaces.
*
* @param type type whose implemented or super interfaces are sought.
* @param configuration the current configuration of the doclet.
* @param sort if true, return list of interfaces sorted alphabetically.
* @return List of all the required interfaces.
*/
public static List<Type> getAllInterfaces(Type type, Configuration configuration, boolean sort) {
Map<ClassDoc, Type> results =
sort ? new TreeMap<ClassDoc, Type>() : new LinkedHashMap<ClassDoc, Type>();
Type[] interfaceTypes = null;
Type superType = null;
if (type instanceof ParameterizedType) {
interfaceTypes = ((ParameterizedType) type).interfaceTypes();
superType = ((ParameterizedType) type).superclassType();
} else if (type instanceof ClassDoc) {
interfaceTypes = ((ClassDoc) type).interfaceTypes();
superType = ((ClassDoc) type).superclassType();
} else {
interfaceTypes = type.asClassDoc().interfaceTypes();
superType = type.asClassDoc().superclassType();
}
for (int i = 0; i < interfaceTypes.length; i++) {
Type interfaceType = interfaceTypes[i];
ClassDoc interfaceClassDoc = interfaceType.asClassDoc();
if (!(interfaceClassDoc.isPublic()
|| (configuration == null || isLinkable(interfaceClassDoc, configuration)))) {
continue;
}
results.put(interfaceClassDoc, interfaceType);
List<Type> superInterfaces = getAllInterfaces(interfaceType, configuration, sort);
for (Iterator<Type> iter = superInterfaces.iterator(); iter.hasNext(); ) {
Type t = iter.next();
results.put(t.asClassDoc(), t);
}
}
if (superType == null) return new ArrayList<Type>(results.values());
// Try walking the tree.
addAllInterfaceTypes(
results,
superType,
superType instanceof ClassDoc
? ((ClassDoc) superType).interfaceTypes()
: ((ParameterizedType) superType).interfaceTypes(),
false,
configuration);
List<Type> resultsList = new ArrayList<Type>(results.values());
if (sort) {
Collections.sort(resultsList, new TypeComparator());
}
return resultsList;
}
/**
* Add the navigation summary link.
*
* @param members members to be linked
* @param visibleMemberMap the visible inherited members map
* @param liNav the content tree to which the navigation summary link will be added
*/
protected void addNavSummaryLink(
List<?> members, VisibleMemberMap visibleMemberMap, Content liNav) {
if (members.size() > 0) {
liNav.addContent(getNavSummaryLink(null, true));
return;
}
ClassDoc icd = classdoc.superclass();
while (icd != null) {
List<?> inhmembers = visibleMemberMap.getMembersFor(icd);
if (inhmembers.size() > 0) {
liNav.addContent(getNavSummaryLink(icd, true));
return;
}
icd = icd.superclass();
}
liNav.addContent(getNavSummaryLink(null, false));
}
FieldDefsRes(ClassDoc clazz, FieldDefsRes parent, boolean bottomMost) {
this.className = clazz.qualifiedName();
this.parent = parent;
this.bottomMost = bottomMost;
int byteSize = 0;
if (parent == null) this.s = "";
else this.s = parent.s;
}
/**
* 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 all relations for a given's class's tag
*
* @param tagname the tag containing the given relation
* @param from the source class
* @param edgetype the dot edge specification
*/
private void allRelation(Options opt, RelationType rt, ClassDoc from) {
String tagname = rt.toString().toLowerCase();
for (Tag tag : from.tags(tagname)) {
String t[] = StringUtil.tokenize(tag.text()); // l-src label l-dst target
if (t.length != 4) {
System.err.println(
"Error in "
+ from
+ "\n"
+ tagname
+ " expects four fields (l-src label l-dst target): "
+ tag.text());
return;
}
ClassDoc to = from.findClass(t[3]);
if (to != null) {
if (hidden(to)) continue;
relation(opt, rt, from, to, t[0], t[1], t[2]);
} else {
if (hidden(t[3])) continue;
relation(opt, rt, from, from.toString(), to, t[3], t[0], t[1], t[2]);
}
}
}
