/**
* Parses a field type definition
*
* @param docField
* @return
*/
protected static Field ParseField(FieldDoc docField) {
assert (docField != null);
Field xmlField = new Field();
xmlField.name = docField.name();
xmlField.comment = docField.commentText();
xmlField.type = ParseType(docField.type());
xmlField.isFinal = docField.isFinal();
if (xmlField.isFinal) {
xmlField.finalExpression = docField.constantValueExpression();
} else if (docField.constantValueExpression() != null) {
// how would a non-final field have a constant value expression?
// my understanding is that this field is only != null when is not final
assert (false);
}
xmlField.isStatic = docField.isStatic();
xmlField.isVolatile = docField.isVolatile();
xmlField.isTransient = docField.isTransient();
xmlField.scope = DetermineScope(docField);
// parse annotations from the field
xmlField.annotationInstances =
ParseAnnotationInstances(docField.annotations(), docField.qualifiedName());
return xmlField;
}
/**
* Parses an enum type definition
*
* @param docField
* @return
*/
protected static EnumField ParseEnumField(FieldDoc docField) {
assert (docField != null);
EnumField xmlEnumField = new EnumField();
xmlEnumField.name = docField.name();
xmlEnumField.comment = docField.commentText();
return xmlEnumField;
}
/**
* Build the field sub header.
*
* @param node the XML element that specifies which components to document
* @param fieldsContentTree content tree to which the documentation will be added
*/
public void buildFieldSubHeader(XMLNode node, Content fieldsContentTree) {
if (!currentClass.definesSerializableFields()) {
FieldDoc field = (FieldDoc) currentMember;
fieldWriter.addMemberHeader(
field.type().asClassDoc(),
field.type().typeName(),
field.type().dimension(),
field.name(),
fieldsContentTree);
}
}
/** Print the class's attributes fd */
private void attributes(Options opt, FieldDoc fd[]) {
for (FieldDoc f : fd) {
if (hidden(f)) continue;
String att = "";
stereotype(opt, f, Align.LEFT);
att = visibility(opt, f) + f.name();
if (opt.showType) att += typeAnnotation(opt, f.type());
tableLine(Align.LEFT, att);
tagvalue(opt, f);
}
}
/**
* 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);
}
/**
* Writes out the JML specs about the field.
*
* @param field the field to describe
*/
public void writeJmlSpecs(@NonNull FieldDoc field) {
Context context = org.jmlspecs.openjml.jmldoc.Main.jmlContext;
Name newFieldName = Names.instance(context).fromString(field.name());
VarSymbol newField = (VarSymbol) currentClassSym.members().lookup(newFieldName).sym;
// System.out.println("Sym " + newField + " for " + newFieldName + " in " + currentClassSym);
if (newField == null) return; // Inherited Java fxields?
JmlSpecs.FieldSpecs fspecs = JmlSpecs.instance(context).getSpecs(newField);
// FIXME - if the only specs are represent clauses, this won't print them
String s = Utils.jmlAnnotations(newField);
if (fspecs != null
&& (!fspecs.list.isEmpty()
|| s.length() != 0)) { // FIXME - what if there are JML annotations but no clauses
strong("JML Specifications: ");
writer.print(s);
writer.dl();
writer.preNoNewLine();
for (JmlTree.JmlTypeClause clause : fspecs.list) {
writer.print(" ");
writer.print(clause);
writer.println();
}
if (isModel) {
TypeSpecs tspecs = JmlSpecs.instance(context).get(currentClassSym);
for (JmlTypeClause t : tspecs.clauses) {
if (!(t instanceof JmlTypeClauseRepresents)) continue;
JmlTypeClauseRepresents tr = (JmlTypeClauseRepresents) t;
if (!(tr.ident instanceof JCTree.JCIdent)) continue;
Name n = ((JCTree.JCIdent) (tr.ident)).name;
if (n == newFieldName) {
writer.print(" ");
writer.print(JmlPretty.write(t, false));
writer.println();
}
}
}
writer.preEnd();
writer.dlEnd();
}
}
/**
* Parses annotation instances from the javadoc annotation instance type
*
* @param annotationDocs Annotations decorated on some type
* @return Serializable representation of annotations
*/
protected static AnnotationInstance[] ParseAnnotationInstances(
AnnotationDesc[] annotationDocs, String origin) {
AnnotationInstance[] annotations = null;
if (annotationDocs != null && annotationDocs.length > 0) {
ArrayList<AnnotationInstance> list = new ArrayList<AnnotationInstance>();
for (AnnotationDesc annot : annotationDocs) {
AnnotationInstance instance = new AnnotationInstance();
AnnotationTypeDoc annotTypeInfo = null;
try {
annotTypeInfo = annot.annotationType();
instance.name = annot.annotationType().name();
instance.qualifiedName = annot.annotationType().qualifiedTypeName();
} catch (ClassCastException castException) {
log.error("Unable to obtain type data about an annotation found on: " + origin);
log.error("Add to the -cp parameter the class/jar that defines this annotation.");
instance.name = null;
instance.qualifiedName = null;
}
AnnotationDesc.ElementValuePair[] arguments = annot.elementValues();
if (arguments != null && arguments.length > 0) {
ArrayList<AnnotationArgument> argumentList = new ArrayList<AnnotationArgument>();
for (AnnotationDesc.ElementValuePair pair : arguments) {
AnnotationArgument annotationArgument = new AnnotationArgument();
annotationArgument.name = pair.element().name();
Type annotationArgumentType = pair.element().returnType();
annotationArgument.type = annotationArgumentType.qualifiedTypeName();
annotationArgument.isPrimitive = annotationArgumentType.isPrimitive();
annotationArgument.isArray = annotationArgumentType.dimension().length() > 0;
Object objValue = pair.value().value();
if (objValue instanceof AnnotationValue[]) {
AnnotationValue[] realValues = (AnnotationValue[]) objValue;
String[] values = new String[realValues.length];
for (int i = 0; i < realValues.length; i++) {
values[i] = realValues[i].value().toString();
}
annotationArgument.value = values;
} else if (objValue instanceof Number) {
Number number = (Number) objValue;
annotationArgument.value = new String[] {number.toString()};
} else if (objValue instanceof Character) {
Character character = (Character) objValue;
annotationArgument.value = new String[] {character.toString()};
} else if (objValue instanceof Boolean) {
Boolean booleanValue = (Boolean) objValue;
annotationArgument.value = new String[] {booleanValue.toString()};
} else if (objValue instanceof String) {
String stringValue = (String) objValue;
annotationArgument.value = new String[] {stringValue};
} else if (objValue instanceof FieldDoc) {
FieldDoc field = (FieldDoc) objValue;
annotationArgument.value = new String[] {field.name()};
} else if (objValue instanceof ClassDoc) {
ClassDoc classDoc = (ClassDoc) objValue;
annotationArgument.value = new String[] {classDoc.qualifiedTypeName()};
}
argumentList.add(annotationArgument);
}
instance.arguments = argumentList.toArray(new AnnotationArgument[] {});
}
list.add(instance);
}
annotations = list.toArray(new AnnotationInstance[] {});
}
return annotations;
}
/*
* This method only handles static final fields.
*/
protected String addStaticStructMember(FieldDoc field, String cname)
throws ClassNotFoundException {
String res = null;
Object exp = null;
if (!field.isStatic()) return res;
if (!field.isFinal()) return res;
exp = field.constantValue();
if (exp != null) {
/* Constant. */
String cn = cname + "_" + field.name();
String suffix = null;
long val = 0;
/* Can only handle int, long, float, and double fields. */
if (exp instanceof Integer) {
suffix = "L";
val = ((Integer) exp).intValue();
}
if (exp instanceof Long) {
// Visual C++ supports the i64 suffix, not LL
suffix = isWindows ? "i64" : "LL";
val = ((Long) exp).longValue();
}
if (exp instanceof Float) suffix = "f";
if (exp instanceof Double) suffix = "";
if (suffix != null) {
// Some compilers will generate a spurious warning
// for the integer constants for Integer.MIN_VALUE
// and Long.MIN_VALUE so we handle them specially.
if ((suffix.equals("L") && (val == Integer.MIN_VALUE))
|| (suffix.equals("LL") && (val == Long.MIN_VALUE))) {
res =
" #undef "
+ cn
+ lineSep
+ " #define "
+ cn
+ " ("
+ (val + 1)
+ suffix
+ "-1)"
+ lineSep;
} else {
res =
" #undef "
+ cn
+ lineSep
+ " #define "
+ cn
+ " "
+ exp.toString()
+ suffix
+ lineSep;
}
}
}
return res;
}
@Override
public DocReferenceable getFieldDocRef(FieldDoc fieldDoc) {
return new UnknownApiRef(fieldDoc.name());
}
/**
* Prints the class if needed.
*
* <p>A class is a rootClass if it's included among the classes returned by RootDoc.classes(),
* this information is used to properly compute relative links in diagrams for UMLDoc
*/
public String printClass(ClassDoc c, boolean rootClass) {
ClassInfo ci;
boolean toPrint;
Options opt = optionProvider.getOptionsFor(c);
String className = c.toString();
if ((ci = getClassInfo(className)) != null) toPrint = !ci.nodePrinted;
else {
toPrint = true;
ci = newClassInfo(className, true, hidden(c));
}
if (toPrint && !hidden(c) && (!c.isEnum() || opt.showEnumerations)) {
// Associate classname's alias
String r = className;
w.println("\t// " + r);
// Create label
w.print("\t" + ci.name + " [label=");
boolean showMembers =
(opt.showAttributes && c.fields().length > 0)
|| (c.isEnum() && opt.showEnumConstants && c.enumConstants().length > 0)
|| (opt.showOperations && c.methods().length > 0)
|| (opt.showConstructors && c.constructors().length > 0);
externalTableStart(opt, c.qualifiedName(), classToUrl(c, rootClass));
// Calculate the number of innerTable rows we will emmit
int nRows = 1;
if (showMembers) {
if (opt.showAttributes) nRows++;
else if (!c.isEnum() && (opt.showConstructors || opt.showOperations)) nRows++;
if (c.isEnum() && opt.showEnumConstants) nRows++;
if (!c.isEnum() && (opt.showConstructors || opt.showOperations)) nRows++;
}
firstInnerTableStart(opt, nRows);
if (c.isInterface()) tableLine(Align.CENTER, guilWrap(opt, "interface"));
if (c.isEnum()) tableLine(Align.CENTER, guilWrap(opt, "enumeration"));
stereotype(opt, c, Align.CENTER);
Font font = c.isAbstract() && !c.isInterface() ? Font.CLASS_ABSTRACT : Font.CLASS;
String qualifiedName = qualifiedName(opt, r);
int startTemplate = qualifiedName.indexOf('<');
int idx = 0;
if (startTemplate < 0) idx = qualifiedName.lastIndexOf('.');
else idx = qualifiedName.lastIndexOf('.', startTemplate);
if (opt.showComment)
tableLine(Align.LEFT, htmlNewline(escape(c.commentText())), opt, Font.CLASS);
else if (opt.postfixPackage && idx > 0 && idx < (qualifiedName.length() - 1)) {
String packageName = qualifiedName.substring(0, idx);
String cn = className.substring(idx + 1);
tableLine(Align.CENTER, escape(cn), opt, font);
tableLine(Align.CENTER, packageName, opt, Font.PACKAGE);
} else {
tableLine(Align.CENTER, escape(qualifiedName), opt, font);
}
tagvalue(opt, c);
firstInnerTableEnd(opt, nRows);
/*
* Warning: The boolean expressions guarding innerTableStart()
* in this block, should match those in the code block above
* marked: "Calculate the number of innerTable rows we will emmit"
*/
if (showMembers) {
if (opt.showAttributes) {
innerTableStart();
FieldDoc[] fields = c.fields();
// if there are no fields, print an empty line to generate proper HTML
if (fields.length == 0) tableLine(Align.LEFT, "");
else attributes(opt, c.fields());
innerTableEnd();
} else if (!c.isEnum() && (opt.showConstructors || opt.showOperations)) {
// show an emtpy box if we don't show attributes but
// we show operations
innerTableStart();
tableLine(Align.LEFT, "");
innerTableEnd();
}
if (c.isEnum() && opt.showEnumConstants) {
innerTableStart();
FieldDoc[] ecs = c.enumConstants();
// if there are no constants, print an empty line to generate proper HTML
if (ecs.length == 0) {
tableLine(Align.LEFT, "");
} else {
for (FieldDoc fd : c.enumConstants()) {
tableLine(Align.LEFT, fd.name());
}
}
innerTableEnd();
}
if (!c.isEnum() && (opt.showConstructors || opt.showOperations)) {
innerTableStart();
boolean printedLines = false;
if (opt.showConstructors) printedLines |= operations(opt, c.constructors());
if (opt.showOperations) printedLines |= operations(opt, c.methods());
if (!printedLines)
// if there are no operations nor constructors,
// print an empty line to generate proper HTML
tableLine(Align.LEFT, "");
innerTableEnd();
}
}
externalTableEnd();
w.print(", URL=\"" + classToUrl(c, rootClass) + "\"");
nodeProperties(opt);
// If needed, add a note for this node
int ni = 0;
for (Tag t : c.tags("note")) {
String noteName = "n" + ni + "c" + ci.name;
w.print("\t// Note annotation\n");
w.print("\t" + noteName + " [label=");
externalTableStart(
UmlGraph.getCommentOptions(), c.qualifiedName(), classToUrl(c, rootClass));
innerTableStart();
tableLine(
Align.LEFT, htmlNewline(escape(t.text())), UmlGraph.getCommentOptions(), Font.CLASS);
innerTableEnd();
externalTableEnd();
nodeProperties(UmlGraph.getCommentOptions());
w.print("\t" + noteName + " -> " + relationNode(c) + "[arrowhead=none];\n");
ni++;
}
ci.nodePrinted = true;
}
return ci.name;
}