예제 #1
0
  /**
   * @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());
     }
   }
 }
예제 #3
0
  /**
   * 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];
    }
  }
예제 #5
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"));
       }
     }
   }
 }
예제 #6
0
  /**
   * 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;
  }