/** {@inheritDoc} */
public Content getTagletOutput(Tag tag, TagletWriter writer) {
ArrayList inlineTags = new ArrayList();
inlineTags.add(new TextTag(tag.holder(), "<b>"));
inlineTags.addAll(Arrays.asList(tag.inlineTags()));
inlineTags.add(new TextTag(tag.holder(), "</b>"));
return writer.commentTagsToOutput(tag, (Tag[]) inlineTags.toArray(new Tag[] {}));
}
/**
* Parses an annotation type definition
*
* @param docClass
* @return
*/
protected static Annotation ParseAnnotation(ClassDoc docClass) {
AnnotationTypeDoc docAnnotation = (AnnotationTypeDoc) docClass;
assert (docAnnotation != null);
Annotation xmlAnnotation = new Annotation();
xmlAnnotation.name = docClass.name();
xmlAnnotation.qualifiedName = docClass.qualifiedName();
xmlAnnotation.comment = docClass.commentText();
xmlAnnotation.isIncluded = docClass.isIncluded();
xmlAnnotation.scope = DetermineScope(docClass);
AnnotationTypeElementDoc[] elements = docAnnotation.elements();
if (elements != null && elements.length > 0) {
ArrayList<AnnotationElement> elementList = new ArrayList<AnnotationElement>();
for (AnnotationTypeElementDoc element : elements) {
elementList.add(ParseAnnotationElement(element));
}
xmlAnnotation.elements = elementList.toArray(new AnnotationElement[] {});
} else {
log.debug("No elements in annotation: " + docClass.name());
}
xmlAnnotation.annotationInstances =
ParseAnnotationInstances(docClass.annotations(), docClass.qualifiedName());
return xmlAnnotation;
}
private static String[] getOutputArgs(String[] args) {
ArrayList<String> l = new ArrayList<String>();
for (String arg : args) {
if (arg.startsWith("-a")) l.add(StringUtils.removeStart(arg, "-a"));
}
return l.toArray(new String[l.size()]);
}
public String[] getDisplayHttpExamples() {
ArrayList<String> l = new ArrayList<String>();
if (ArrayUtils.isNotEmpty(httpExamples)) {
for (String example : httpExamples) {
if (StringUtils.isNotBlank(example)) l.add(example);
}
}
return l.toArray(new String[l.size()]);
}
/**
* Parses a constructor type definition
*
* @param docConstructor
* @return
*/
protected static Constructor ParseConstructor(ConstructorDoc docConstructor) {
assert (docConstructor != null);
Constructor xmlConstructor = new Constructor();
xmlConstructor.name = docConstructor.name();
xmlConstructor.comment = docConstructor.commentText();
xmlConstructor.scope = DetermineScope(docConstructor);
xmlConstructor.isVarArgs = docConstructor.isVarArgs();
xmlConstructor.isDefault =
docConstructor.position().line() == docConstructor.containingClass().position().line();
Parameter[] parameters = docConstructor.parameters();
if (parameters != null && parameters.length > 0) {
ParamTag[] paramComments = docConstructor.paramTags();
ArrayList<Param> methodList = new ArrayList<Param>();
for (Parameter parameter : parameters) {
ParamTag paramComment = null;
// look to see if this parameter has comments
// if so, paramComment will be set
for (ParamTag testParam : paramComments) {
String testParamName = testParam.parameterName();
if (testParamName != null) {
if (testParamName.compareTo(parameter.name()) == 0) {
paramComment = testParam;
break;
}
}
}
methodList.add(ParseParameter(parameter, paramComment));
}
xmlConstructor.parameters = methodList.toArray(new Param[] {});
} else {
log.debug("No parameters for method: " + docConstructor.name());
}
// parse annotations for the constructor
xmlConstructor.annotationInstances =
ParseAnnotationInstances(docConstructor.annotations(), docConstructor.qualifiedName());
return xmlConstructor;
}
/**
* Parse type variables for generics
*
* @param variables
* @return
*/
protected static TypeVar[] ParseTypeVariables(TypeVariable[] variables, ParamTag[] tags) {
TypeVar[] vars = null;
if (variables != null && variables.length > 0) {
ArrayList<TypeVar> varsList = new ArrayList<TypeVar>();
for (TypeVariable variable : variables) {
TypeVar var = new TypeVar();
var.name = variable.typeName();
Type[] bounds = variable.bounds();
if (bounds != null && bounds.length > 0) {
ArrayList<String> list = new ArrayList<String>();
for (Type bound : bounds) {
list.add(bound.qualifiedTypeName());
}
var.bounds = list.toArray(new String[] {});
}
for (ParamTag tag : tags)
if (tag.parameterName().equals(var.name)) var.comment = tag.parameterComment();
varsList.add(var);
}
vars = varsList.toArray(new TypeVar[] {});
}
return vars;
}
/**
* Parses the enum type definition
*
* @param docClass
* @return
*/
protected static Enum ParseEnum(ClassDoc docClass) {
assert (docClass != null);
Enum xmlEnum = new Enum();
xmlEnum.name = docClass.name();
xmlEnum.qualifiedName = docClass.qualifiedName();
xmlEnum.comment = docClass.commentText();
xmlEnum.isIncluded = docClass.isIncluded();
xmlEnum.scope = DetermineScope(docClass);
Type superClassType = docClass.superclassType();
if (superClassType != null) {
xmlEnum.superClass = superClassType.qualifiedTypeName();
}
Type[] interfaces = docClass.interfaceTypes();
ArrayList<String> interfaceTypeNames = new ArrayList<String>();
if (interfaces != null && interfaces.length > 0) {
for (Type interfaceType : interfaces) {
interfaceTypeNames.add(interfaceType.qualifiedTypeName());
}
}
xmlEnum.extendedFrom = interfaceTypeNames.toArray(new String[] {});
FieldDoc[] fields = docClass.enumConstants();
if (fields != null && fields.length > 0) {
ArrayList<EnumField> fieldList = new ArrayList<EnumField>();
for (FieldDoc field : fields) {
fieldList.add(ParseEnumField(field));
}
xmlEnum.fields = fieldList.toArray(new EnumField[] {});
}
xmlEnum.annotationInstances =
ParseAnnotationInstances(docClass.annotations(), docClass.qualifiedName());
return xmlEnum;
}
/**
* Parses an interface type definition
*
* @param docClass
* @return
*/
protected static Interface ParseInterface(ClassDoc docClass) {
assert (docClass != null);
Interface xmlInterface = new Interface();
xmlInterface.name = docClass.name();
xmlInterface.qualifiedName = docClass.qualifiedName();
xmlInterface.comment = docClass.commentText();
xmlInterface.isIncluded = docClass.isIncluded();
xmlInterface.scope = DetermineScope(docClass);
xmlInterface.typeVariables =
ParseTypeVariables(docClass.typeParameters(), docClass.typeParamTags());
Type[] interfaces = docClass.interfaceTypes();
ArrayList<String> interfaceTypeNames = new ArrayList<String>();
if (interfaces != null && interfaces.length > 0) {
for (Type interfaceType : interfaces) {
interfaceTypeNames.add(interfaceType.qualifiedTypeName());
}
xmlInterface.interfaces = interfaceTypeNames.toArray(new String[] {});
}
MethodDoc[] methods = docClass.methods();
if (methods != null && methods.length > 0) {
ArrayList<Method> methodList = new ArrayList<Method>();
for (MethodDoc method : methods) {
methodList.add(ParseMethod(method));
}
xmlInterface.methods = methodList.toArray(new Method[] {});
} else {
log.debug("No methods in interface: " + docClass.name());
}
xmlInterface.annotationInstances =
ParseAnnotationInstances(docClass.annotations(), docClass.qualifiedName());
return xmlInterface;
}
/**
* Parses a method type definition
*
* @param docMethod
* @return
*/
protected static Method ParseMethod(MethodDoc docMethod) {
assert (docMethod != null);
Method xmlMethod = new Method();
xmlMethod.name = docMethod.name();
xmlMethod.hash = computeHash(docMethod.qualifiedName(), docMethod.signature());
xmlMethod.qualifiedName = docMethod.qualifiedName();
xmlMethod.comment = docMethod.commentText();
xmlMethod.signature = docMethod.signature();
xmlMethod.isNative = docMethod.isNative();
xmlMethod.isVarArgs = docMethod.isVarArgs();
xmlMethod.isSynchronized = docMethod.isSynchronized();
xmlMethod.isFinal = docMethod.isFinal();
xmlMethod.isAbstract = docMethod.isAbstract();
xmlMethod.isStatic = docMethod.isStatic();
xmlMethod.scope = DetermineScope(docMethod);
// Parse parameters of the method
Parameter[] parameters = docMethod.parameters();
if (parameters != null && parameters.length > 0) {
ParamTag[] paramComments = docMethod.paramTags();
ArrayList<Param> paramList = new ArrayList<Param>();
for (Parameter parameter : parameters) {
ParamTag paramComment = null;
// look to see if this parameter has comments
// if so, paramComment will be set
for (ParamTag testParam : paramComments) {
String testParamName = testParam.parameterName();
if (testParamName != null) {
if (testParamName.compareTo(parameter.name()) == 0) {
paramComment = testParam;
break;
}
}
}
paramList.add(ParseParameter(parameter, paramComment));
}
xmlMethod.parameters = paramList.toArray(new Param[] {});
} else {
log.debug("No parameters for method: " + docMethod.name());
}
// Parse result data
Result returnInfo = new Result();
Tag[] returnTags = docMethod.tags("@return");
if (returnTags != null && returnTags.length > 0) {
// there should be only one return tag. but heck,
// if they specify two, so what...
StringBuilder builder = new StringBuilder();
for (Tag returnTag : returnTags) {
String returnTagText = returnTag.text();
if (returnTagText != null) {
builder.append(returnTagText);
builder.append("\n");
}
}
returnInfo.comment = builder.substring(0, builder.length() - 1);
}
returnInfo.type = ParseType(docMethod.returnType());
xmlMethod.result = returnInfo;
// Parse exceptions of the method
Type[] types = docMethod.thrownExceptionTypes();
ThrowsTag[] exceptionComments = docMethod.throwsTags();
if (types != null && types.length > 0) {
ArrayList<ExceptionInstance> exceptionList = new ArrayList<ExceptionInstance>();
for (Type exceptionType : types) {
ExceptionInstance exception = new ExceptionInstance();
exception.type = ParseType(exceptionType);
for (ThrowsTag exceptionComment : exceptionComments) {
if (exceptionType == exceptionComment.exceptionType()) {
exception.comment = exceptionComment.exceptionComment();
ClassDoc exceptionDetails = exceptionComment.exception();
// not yet parsing Exceptions defined within the supplied code set
exception.type = ParseType(exceptionComment.exceptionType());
break;
}
}
exceptionList.add(exception);
}
xmlMethod.exceptions = exceptionList.toArray(new ExceptionInstance[] {});
}
// parse annotations from the method
xmlMethod.annotationInstances =
ParseAnnotationInstances(docMethod.annotations(), docMethod.qualifiedName());
return xmlMethod;
}
/**
* 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;
}
/**
* Parses the data for a class type definition
*
* @param docClass
* @return
*/
protected static Class ParseClass(ClassDoc docClass) {
assert (docClass != null);
Class xmlClass = new Class();
// illegal use of this class.
assert (xmlClass != null);
xmlClass.name = docClass.name();
xmlClass.qualifiedName = docClass.qualifiedName();
xmlClass.isSerializable = docClass.isSerializable();
xmlClass.isExternalizable = docClass.isExternalizable();
xmlClass.isAbstract = docClass.isAbstract();
xmlClass.isException = docClass.isException();
xmlClass.isError = docClass.isError();
xmlClass.comment = docClass.commentText();
xmlClass.scope = DetermineScope(docClass);
xmlClass.isIncluded = docClass.isIncluded();
xmlClass.typeVariables =
ParseTypeVariables(docClass.typeParameters(), docClass.typeParamTags());
Type superClassType = docClass.superclassType();
if (superClassType != null) {
xmlClass.superClass = ParseType(superClassType);
}
Type[] interfaces = docClass.interfaceTypes();
ArrayList<TypeInfo> interfaceTypeNames = new ArrayList<TypeInfo>();
if (interfaces != null && interfaces.length > 0) {
for (Type interfaceType : interfaces) {
interfaceTypeNames.add(ParseType(interfaceType));
}
xmlClass.interfaces = interfaceTypeNames.toArray(new TypeInfo[] {});
}
ConstructorDoc[] constructors = docClass.constructors();
if (constructors != null && constructors.length > 0) {
ArrayList<Constructor> constructorList = new ArrayList<Constructor>();
for (ConstructorDoc constructor : constructors) {
constructorList.add(ParseConstructor(constructor));
}
xmlClass.constructors = constructorList.toArray(new Constructor[] {});
} else {
log.debug("No constructors in class: " + docClass.name());
}
MethodDoc[] methods = docClass.methods();
if (methods != null && methods.length > 0) {
ArrayList<Method> methodList = new ArrayList<Method>();
for (MethodDoc method : methods) {
methodList.add(ParseMethod(method));
}
xmlClass.methods = methodList.toArray(new Method[] {});
} else {
log.debug("No methods in class: " + docClass.name());
}
FieldDoc[] fields = docClass.fields();
if (fields != null && fields.length > 0) {
ArrayList<Field> fieldList = new ArrayList<Field>();
for (FieldDoc field : fields) {
fieldList.add(ParseField(field));
}
xmlClass.fields = fieldList.toArray(new Field[] {});
}
xmlClass.annotationInstances =
ParseAnnotationInstances(docClass.annotations(), docClass.qualifiedName());
return xmlClass;
}
private static ApiDoc scanMethodDoc(ClassDoc classDoc, MethodDoc methodDoc) {
String routePrefix = "";
// RoutePrefix for class
for (AnnotationDesc annDesc : classDoc.annotations()) {
if (RoutePrefix.class.getName().equals(annDesc.annotationType().qualifiedTypeName())) {
routePrefix = annotationToString(annDesc, "value", "");
break;
}
}
AnnotationDesc[] annDescs = methodDoc.annotations();
if (ArrayUtils.isEmpty(annDescs)) return null;
for (AnnotationDesc annDesc : annDescs) {
if (IgnoreDocument.class.getName().equals(annDesc.annotationType().qualifiedTypeName()))
return null;
}
// RoutePrefix for method
for (AnnotationDesc annDesc : annDescs) {
if (RoutePrefix.class.getName().equals(annDesc.annotationType().qualifiedTypeName())) {
routePrefix = annotationToString(annDesc, "value", "");
break;
}
}
Class httpExamplePackageClass = null;
String[] routes = null;
String[] httpMethods = {"GET", "POST"};
boolean deprecated = false;
for (AnnotationDesc annDesc : annDescs) {
if (Route.class.getName().equals(annDesc.annotationType().qualifiedTypeName())) {
for (AnnotationDesc.ElementValuePair annValue : annDesc.elementValues()) {
String name = annValue.element().name();
if ("url".equals(name)) {
routes = annotationToStringArray(annValue.value().value());
} else if ("method".equals(name)) {
httpMethods = annotationToStringArray(annValue.value().value());
}
}
}
if (Deprecated.class.getName().equals(annDesc.annotationType().qualifiedTypeName()))
deprecated = true;
if (HttpExamplePackage.class.getName().equals(annDesc.annotationType().qualifiedTypeName())) {
for (AnnotationDesc.ElementValuePair annValue : annDesc.elementValues()) {
String name = annValue.element().name();
if ("value".equals(name)) {
ClassDoc httpExamplePackageClassAnn = (ClassDoc) annValue.value().value();
httpExamplePackageClass =
ClassHelper.forName(httpExamplePackageClassAnn.qualifiedTypeName());
}
}
}
}
if (routes == null) return null;
if (httpExamplePackageClass == null) {
annDescs = classDoc.annotations();
for (AnnotationDesc annDesc : annDescs) {
if (HttpExamplePackage.class
.getName()
.equals(annDesc.annotationType().qualifiedTypeName())) {
for (AnnotationDesc.ElementValuePair annValue : annDesc.elementValues()) {
String name = annValue.element().name();
if ("value".equals(name)) {
ClassDoc httpExamplePackageClassAnn = (ClassDoc) annValue.value().value();
httpExamplePackageClass =
ClassHelper.forName(httpExamplePackageClassAnn.qualifiedTypeName());
}
}
}
}
}
ApiDoc apiDoc = new ApiDoc();
apiDoc.group = getTag(methodDoc, GROUP_TAG, "");
apiDoc.routes = addRoutePrefix(routes, routePrefix);
apiDoc.httpMethods = httpMethods;
apiDoc.description = expandText(methodDoc.commentText());
apiDoc.login = parseBoolean(getTag(methodDoc, LOGIN_TAG, "y"));
apiDoc.deprecated = deprecated;
apiDoc.httpReturn = getTag(methodDoc, HTTP_RETURN, "");
apiDoc.remark = expandText(getTag(methodDoc, REMARK_TAG, ""));
apiDoc.className = classDoc.qualifiedTypeName();
apiDoc.httpExamplePackageClass = httpExamplePackageClass;
String[] httpExamples = expandTexts(getTags(methodDoc, HTTP_EXAMPLE_TAG));
for (int i = 0; i < httpExamples.length; i++) {
String httpExample = httpExamples[i];
if (httpExample.startsWith("@")) {
if (apiDoc.httpExamplePackageClass != null) {
httpExamples[i] =
VfsHelper.loadTextInClasspath(
apiDoc.httpExamplePackageClass, StringUtils.removeStart(httpExample, "@"));
} else {
httpExamples[i] = "";
}
}
}
apiDoc.httpExamples = httpExamples;
ArrayList<ParamDoc> l = new ArrayList<ParamDoc>();
for (String httpParamTag : getTags(methodDoc, HTTP_PARAM_TAG)) {
ParamDoc httpParamDoc = parseParamDoc(httpParamTag);
if (httpParamDoc != null) l.add(httpParamDoc);
}
apiDoc.httpParams = l.toArray(new ParamDoc[l.size()]);
return apiDoc;
}
