/**
* Adds a syntax to the syntaxsection
*
* @param doc, doc item that has to be add to the syntax section
*/
void addSyntax(Doc doc) {
if (doc.isConstructor() || doc.isMethod()) {
StringBuffer syntaxBuffer = new StringBuffer();
for (Parameter parameter : ((ExecutableMemberDoc) doc).parameters()) {
syntaxBuffer.append(parameter.typeName() + " " + parameter.name());
syntaxBuffer.append(", ");
}
if (syntaxBuffer.length() > 2) {
syntaxBuffer.delete(syntaxBuffer.length() - 2, syntaxBuffer.length());
}
String returnType = "";
if (doc.isMethod()) {
MethodDoc methodDoc = (MethodDoc) doc;
returnType = methodDoc.returnType().toString();
int lastDot = returnType.lastIndexOf('.');
if (lastDot != -1) {
returnType = returnType.substring(lastDot + 1);
}
returnType += " ";
}
if (doc.isConstructor()) {
addSyntax("<em>" + doc.commentText() + "</em>");
}
addSyntax(returnType + doc.name() + "(" + syntaxBuffer.toString() + ")");
} else if (doc.isField()) {
FieldDoc fieldDoc = (FieldDoc) doc;
addSyntax(fieldDoc.type().typeName() + " " + doc.name());
}
}
/**
* Prints dependencies recovered from the methods of a class. A dependency is inferred only if
* another relation between the two classes is not already in the graph.
*
* @param classes
*/
public void printInferredDependencies(ClassDoc c) {
Options opt = optionProvider.getOptionsFor(c);
String sourceName = c.toString();
if (hidden(c)) return;
Set<Type> types = new HashSet<Type>();
// harvest method return and parameter types
for (MethodDoc method : filterByVisibility(c.methods(false), opt.inferDependencyVisibility)) {
types.add(method.returnType());
for (Parameter parameter : method.parameters()) {
types.add(parameter.type());
}
}
// and the field types
if (!opt.inferRelationships) {
for (FieldDoc field : filterByVisibility(c.fields(false), opt.inferDependencyVisibility)) {
types.add(field.type());
}
}
// see if there are some type parameters
if (c.asParameterizedType() != null) {
ParameterizedType pt = c.asParameterizedType();
types.addAll(Arrays.asList(pt.typeArguments()));
}
// see if type parameters extend something
for (TypeVariable tv : c.typeParameters()) {
if (tv.bounds().length > 0) types.addAll(Arrays.asList(tv.bounds()));
}
// and finally check for explicitly imported classes (this
// assumes there are no unused imports...)
if (opt.useImports) types.addAll(Arrays.asList(c.importedClasses()));
// compute dependencies
for (Type type : types) {
// skip primitives and type variables, as well as dependencies
// on the source class
if (type.isPrimitive()
|| type instanceof WildcardType
|| type instanceof TypeVariable
|| c.toString().equals(type.asClassDoc().toString())) continue;
// check if the destination is excluded from inference
ClassDoc fc = type.asClassDoc();
if (hidden(fc)) continue;
// check if source and destination are in the same package and if we are allowed
// to infer dependencies between classes in the same package
if (!opt.inferDepInPackage && c.containingPackage().equals(fc.containingPackage())) continue;
// if source and dest are not already linked, add a dependency
RelationPattern rp = getClassInfo(sourceName).getRelation(fc.toString());
if (rp == null || rp.matchesOne(new RelationPattern(RelationDirection.OUT))) {
relation(opt, RelationType.DEPEND, c, fc, "", "", "");
}
}
}
private static void processParameterAnnotations(MethodDoc methodDoc, MethodModel methodModel) {
Parameter[] params = methodDoc.parameters();
// Start with false here. If we find the userId parameter this will be changed to true.
methodModel.setIsAuthenticationRequired(false);
Map<String, ParameterModel> paramMap = new HashMap<String, ParameterModel>();
if (params != null) {
for (Parameter param : params) {
AnnotationDesc[] paramAnnos = param.annotations();
if (paramAnnos != null) {
for (AnnotationDesc ad : paramAnnos) {
String qualifiedName = ad.annotationType().qualifiedName();
Map<String, Object> annotationMap = mapAnnotation(ad);
System.out.println(annotationMap);
if (RequestBody.class.getName().equals(qualifiedName)) {
// Request body
String schema = SchemaUtils.getEffectiveSchema(param.type().qualifiedTypeName());
if (schema != null) {
Link link =
new Link("${" + param.type().qualifiedTypeName() + "}", param.typeName());
methodModel.setRequestBody(link);
}
} else if (PathVariable.class.getName().equals(qualifiedName)) {
// Path parameter
ParameterModel paramModel = new ParameterModel();
paramModel.setName(param.name());
methodModel.addPathVariable(paramModel);
paramMap.put(param.name(), paramModel);
} else if (RequestParam.class.getName().equals(qualifiedName)) {
// if this is the userId parameter then we do now show it,
// rather it means this method requires authentication.
if (AuthorizationConstants.USER_ID_PARAM.equals(
annotationMap.get(REQUEST_PARAMETER_VALUE))) {
methodModel.setIsAuthenticationRequired(true);
} else {
ParameterModel paramModel = new ParameterModel();
paramModel.setName(param.name());
paramModel.setIsOptional(!(isRequired(annotationMap)));
methodModel.addParameter(paramModel);
paramMap.put(param.name(), paramModel);
}
}
}
}
}
}
ParamTag[] paramTags = methodDoc.paramTags();
if (paramTags != null) {
for (ParamTag paramTag : paramTags) {
ParameterModel paramModel = paramMap.get(paramTag.parameterName());
if (paramModel != null) {
paramModel.setDescription(paramTag.parameterComment());
}
}
}
System.out.println(methodModel);
// Lookup the parameter descriptions
}
/**
* 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;
}
/**
* Parses a method parameter type definition
*
* @param docParameter
* @param paramComment
* @return
*/
protected static Param ParseParameter(Parameter docParameter, ParamTag paramComment) {
assert (docParameter != null);
Param xmlParameter = new Param();
xmlParameter.name = docParameter.name();
xmlParameter.type = ParseType(docParameter.type());
if (paramComment != null) {
xmlParameter.comment = paramComment.parameterComment();
}
xmlParameter.annotationInstances =
ParseAnnotationInstances(docParameter.annotations(), docParameter.typeName());
return xmlParameter;
}
private static List<DocParameter> generateParameters(final MethodDoc methodDoc) {
List<DocParameter> paramsList = new LinkedList<DocParameter>();
for (Parameter parameter : methodDoc.parameters()) {
String name = parameter.name();
DocParameter docParameter = new DocParameter(name, parameter.type());
docParameter.setAnnotations(generateAnnotations(parameter.annotations()));
Map<String, String> paramTagsComments = Utils.getParamTagsComments(methodDoc);
String description = paramTagsComments.get(name);
if (description == null) {
logger.warning(
"Missing description of parameter " + name + " of method " + methodDoc.name());
description = "";
}
docParameter.setDescription(description);
paramsList.add(docParameter);
}
return paramsList;
}
/**
* 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;
}
public static AnnotationDesc findAnnotation(
final Parameter parameter, final Class<?>... soughtAnnotations) {
return findAnnotation(parameter.annotations(), soughtAnnotations);
}
private void walkFormParameter(ClassDoc formDoc) {
// walk all fields
for (FieldDoc field : formDoc.fields(false)) {
final AnnotationDesc pathParamAnnotation = Utils.findAnnotation(field, PathParam.class);
if (pathParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(pathParamAnnotation);
pathParameters.add(
new FormFieldParameter(field, pathParamAnnotation, MethodParameterType.Path));
continue;
}
final AnnotationDesc matrixParamAnnotation = Utils.findAnnotation(field, MatrixParam.class);
if (matrixParamAnnotation != null) {
matrixParameters.add(
new FormFieldParameter(field, matrixParamAnnotation, MethodParameterType.Matrix));
continue;
}
final AnnotationDesc queryParamAnnotation = Utils.findAnnotation(field, QueryParam.class);
if (queryParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(queryParamAnnotation);
queryParameters.add(
new FormFieldParameter(field, queryParamAnnotation, MethodParameterType.Query));
continue;
}
final AnnotationDesc headerParamAnnotation = Utils.findAnnotation(field, HeaderParam.class);
if (headerParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(headerParamAnnotation);
headerParameters.add(
new FormFieldParameter(field, headerParamAnnotation, MethodParameterType.Header));
continue;
}
final AnnotationDesc cookieParamAnnotation = Utils.findAnnotation(field, CookieParam.class);
if (cookieParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(cookieParamAnnotation);
cookieParameters.add(
new FormFieldParameter(field, cookieParamAnnotation, MethodParameterType.Cookie));
continue;
}
final AnnotationDesc formParamAnnotation = Utils.findAnnotation(field, FormParam.class);
if (formParamAnnotation != null) {
formParameters.add(
new FormFieldParameter(field, formParamAnnotation, MethodParameterType.Form));
continue;
}
// Recurse into the embedded @Form field
if (formClass != null) {
final AnnotationDesc formAnnotation = Utils.findAnnotation(field, formClass);
if (formAnnotation != null) {
walkFormParameter(field.type().asClassDoc());
continue;
}
}
final AnnotationDesc contextAnnotation = Utils.findAnnotation(field, Context.class);
if (contextAnnotation == null) {
this.inputParameter = new FormFieldParameter(field, null, MethodParameterType.Input);
continue;
}
}
// and methods
for (MethodDoc method : formDoc.methods(false)) {
if (!method.returnType().qualifiedTypeName().equals("void")
|| method.parameters().length != 1
|| !method.name().startsWith("set")) continue;
Parameter parameter = method.parameters()[0];
final AnnotationDesc pathParamAnnotation =
Utils.findParameterAnnotation(method, parameter, 0, PathParam.class);
if (pathParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(pathParamAnnotation);
pathParameters.add(
new FormMethodParameter(method, pathParamAnnotation, MethodParameterType.Path));
continue;
}
final AnnotationDesc matrixParamAnnotation =
Utils.findParameterAnnotation(method, parameter, 0, MatrixParam.class);
if (matrixParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(matrixParamAnnotation);
matrixParameters.add(
new FormMethodParameter(method, matrixParamAnnotation, MethodParameterType.Matrix));
continue;
}
final AnnotationDesc queryParamAnnotation =
Utils.findParameterAnnotation(method, parameter, 0, QueryParam.class);
if (queryParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(queryParamAnnotation);
queryParameters.add(
new FormMethodParameter(method, queryParamAnnotation, MethodParameterType.Query));
continue;
}
final AnnotationDesc headerParamAnnotation =
Utils.findParameterAnnotation(method, parameter, 0, HeaderParam.class);
if (headerParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(headerParamAnnotation);
headerParameters.add(
new FormMethodParameter(method, headerParamAnnotation, MethodParameterType.Header));
continue;
}
final AnnotationDesc cookieParamAnnotation =
Utils.findParameterAnnotation(method, parameter, 0, CookieParam.class);
if (cookieParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(cookieParamAnnotation);
cookieParameters.add(
new FormMethodParameter(method, cookieParamAnnotation, MethodParameterType.Cookie));
continue;
}
final AnnotationDesc formParamAnnotation =
Utils.findParameterAnnotation(method, parameter, 0, FormParam.class);
if (formParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(formParamAnnotation);
formParameters.add(
new FormMethodParameter(method, formParamAnnotation, MethodParameterType.Form));
continue;
}
// I'm not sure if @Form can be used on setter methods on an @Form field, but just in case...
if (formClass != null) {
// recurse into @Form parameters
final AnnotationDesc formAnnotation =
Utils.findParameterAnnotation(method, parameter, 0, formClass);
if (formAnnotation != null) {
walkFormParameter(parameter.type().asClassDoc());
continue;
}
}
final AnnotationDesc contextAnnotation =
Utils.findParameterAnnotation(method, parameter, 0, Context.class);
if (contextAnnotation == null) {
this.inputParameter = new FormMethodParameter(method, null, MethodParameterType.Input);
}
}
}
private void setupParameters() {
int i = -1;
for (final Parameter parameter : method.parameters()) {
i++;
final AnnotationDesc pathParamAnnotation =
Utils.findParameterAnnotation(declaringMethod, parameter, i, PathParam.class);
if (pathParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(pathParamAnnotation);
pathParameters.add(
new RealMethodParameter(
parameter, i, pathParamAnnotation, MethodParameterType.Path, declaringMethod));
continue;
}
final AnnotationDesc matrixParamAnnotation =
Utils.findParameterAnnotation(declaringMethod, parameter, i, MatrixParam.class);
if (matrixParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(matrixParamAnnotation);
matrixParameters.add(
new RealMethodParameter(
parameter, i, matrixParamAnnotation, MethodParameterType.Matrix, declaringMethod));
continue;
}
final AnnotationDesc queryParamAnnotation =
Utils.findParameterAnnotation(declaringMethod, parameter, i, QueryParam.class);
if (queryParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(queryParamAnnotation);
queryParameters.add(
new RealMethodParameter(
parameter, i, queryParamAnnotation, MethodParameterType.Query, declaringMethod));
continue;
}
final AnnotationDesc cookieParamAnnotation =
Utils.findParameterAnnotation(declaringMethod, parameter, i, CookieParam.class);
if (cookieParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(cookieParamAnnotation);
cookieParameters.add(
new RealMethodParameter(
parameter, i, cookieParamAnnotation, MethodParameterType.Cookie, declaringMethod));
continue;
}
final AnnotationDesc formParamAnnotation =
Utils.findParameterAnnotation(declaringMethod, parameter, i, FormParam.class);
if (formParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(formParamAnnotation);
formParameters.add(
new RealMethodParameter(
parameter, i, formParamAnnotation, MethodParameterType.Form, declaringMethod));
continue;
}
final AnnotationDesc headerParamAnnotation =
Utils.findParameterAnnotation(declaringMethod, parameter, i, HeaderParam.class);
if (headerParamAnnotation != null) {
String name = (String) Utils.getAnnotationValue(headerParamAnnotation);
headerParameters.add(
new RealMethodParameter(
parameter, i, headerParamAnnotation, MethodParameterType.Header, declaringMethod));
continue;
}
if (formClass != null) {
final AnnotationDesc formAnnotation =
Utils.findParameterAnnotation(declaringMethod, parameter, i, formClass);
if (formAnnotation != null) {
walkFormParameter(parameter.type().asClassDoc());
continue;
}
}
final AnnotationDesc contextAnnotation =
Utils.findParameterAnnotation(declaringMethod, parameter, i, Context.class);
if (contextAnnotation == null) {
this.inputParameter =
new RealMethodParameter(parameter, i, null, MethodParameterType.Input, declaringMethod);
}
}
}
