/**
* @param member1 the first method to compare.
* @param member2 the second method to compare.
* @return true if member1 overrides/hides or is overriden/hidden by member2.
*/
public static boolean executableMembersEqual(
ExecutableMemberDoc member1, ExecutableMemberDoc member2) {
if (!(member1 instanceof MethodDoc && member2 instanceof MethodDoc)) return false;
MethodDoc method1 = (MethodDoc) member1;
MethodDoc method2 = (MethodDoc) member2;
if (method1.isStatic() && method2.isStatic()) {
Parameter[] targetParams = method1.parameters();
Parameter[] currentParams;
if (method1.name().equals(method2.name())
&& (currentParams = method2.parameters()).length == targetParams.length) {
int j;
for (j = 0; j < targetParams.length; j++) {
if (!(targetParams[j].typeName().equals(currentParams[j].typeName())
|| currentParams[j].type() instanceof TypeVariable
|| targetParams[j].type() instanceof TypeVariable)) {
break;
}
}
if (j == targetParams.length) {
return true;
}
}
return false;
} else {
return method1.overrides(method2) || method2.overrides(method1) || member1 == member2;
}
}
/**
* Build the method tags.
*
* @param node the XML element that specifies which components to document
* @param methodsContentTree content tree to which the documentation will be added
*/
public void buildMethodTags(XMLNode node, Content methodsContentTree) {
methodWriter.addMemberTags((MethodDoc) currentMember, methodsContentTree);
MethodDoc method = (MethodDoc) currentMember;
if (method.name().compareTo("writeExternal") == 0 && method.tags("serialData").length == 0) {
if (configuration.serialwarn) {
configuration
.getDocletSpecificMsg()
.warning(
currentMember.position(),
"doclet.MissingSerialDataTag",
method.containingClass().qualifiedName(),
method.name());
}
}
}
/**
* Build the comments for the method. Do nothing if {@link Configuration#nocomment} is set to
* true.
*
* @param node the XML element that specifies which components to document
* @param methodDocTree the content tree to which the documentation will be added
*/
public void buildMethodComments(XMLNode node, Content methodDocTree) {
if (!configuration.nocomment) {
MethodDoc method = (MethodDoc) methods.get(currentMethodIndex);
if (method.inlineTags().length == 0) {
DocFinder.Output docs = DocFinder.search(configuration, new DocFinder.Input(method));
method =
docs.inlineTags != null && docs.inlineTags.length > 0
? (MethodDoc) docs.holder
: method;
}
// NOTE: When we fix the bug where ClassDoc.interfaceTypes() does
// not pass all implemented interfaces, holder will be the
// interface type. For now, it is really the erasure.
writer.addComments(method.containingClass(), method, methodDocTree);
}
}
private static String[] getTags(MethodDoc methodDoc, String tagName) {
Tag[] tags = methodDoc.tags(tagName);
if (ArrayUtils.isNotEmpty(tags)) {
String[] a = new String[tags.length];
for (int i = 0; i < a.length; i++) a[i] = tags[i].text();
return a;
} else {
return new String[0];
}
}
/** 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"));
}
}
}
}
/**
* 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;
}
private static String getTag(MethodDoc methodDoc, String tagName, String def) {
Tag[] tags = methodDoc.tags(tagName);
return ArrayUtils.isNotEmpty(tags) ? tags[0].text() : def;
}
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;
}
