Пример #1
0
  /**
   * 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;
  }
  /**
   * Constructor.
   *
   * @param filename the file to be generated.
   * @throws IOException
   * @throws DocletAbortException
   */
  public PackageUseWriter(
      ConfigurationImpl configuration, ClassUseMapper mapper, DocPath filename, PackageDoc pkgdoc)
      throws IOException {
    super(configuration, DocPath.forPackage(pkgdoc).resolve(filename));
    this.pkgdoc = pkgdoc;

    // by examining all classes in this package, find what packages
    // use these classes - produce a map between using package and
    // used classes.
    ClassDoc[] content = pkgdoc.allClasses();
    for (int i = 0; i < content.length; ++i) {
      ClassDoc usedClass = content[i];
      Set<ClassDoc> usingClasses = mapper.classToClass.get(usedClass.qualifiedName());
      if (usingClasses != null) {
        for (Iterator<ClassDoc> it = usingClasses.iterator(); it.hasNext(); ) {
          ClassDoc usingClass = it.next();
          PackageDoc usingPackage = usingClass.containingPackage();
          Set<ClassDoc> usedClasses = usingPackageToUsedClasses.get(usingPackage.name());
          if (usedClasses == null) {
            usedClasses = new TreeSet<ClassDoc>();
            usingPackageToUsedClasses.put(Util.getPackageName(usingPackage), usedClasses);
          }
          usedClasses.add(usedClass);
        }
      }
    }
  }
Пример #3
0
  /**
   * 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;
  }
Пример #4
0
  /**
   * 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;
  }
 /**
  * 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);
 }
Пример #6
0
 /**
  * Given an array of <code>Tag</code>s representing this custom tag, return its string
  * representation.
  *
  * @param throwTags the array of <code>ThrowsTag</code>s to convert.
  * @param writer the TagletWriter that will write this tag.
  * @param alreadyDocumented the set of exceptions that have already been documented.
  * @param allowDups True if we allow duplicate throws tags to be documented.
  * @return the TagletOutput representation of this <code>Tag</code>.
  */
 protected TagletOutput throwsTagsOutput(
     ThrowsTag[] throwTags,
     TagletWriter writer,
     Set<String> alreadyDocumented,
     boolean allowDups) {
   TagletOutput result = writer.getOutputInstance();
   if (throwTags.length > 0) {
     for (int i = 0; i < throwTags.length; ++i) {
       ThrowsTag tt = throwTags[i];
       ClassDoc cd = tt.exception();
       if ((!allowDups)
           && (alreadyDocumented.contains(tt.exceptionName())
               || (cd != null && alreadyDocumented.contains(cd.qualifiedName())))) {
         continue;
       }
       if (alreadyDocumented.size() == 0) {
         result.appendOutput(writer.getThrowsHeader());
       }
       result.appendOutput(writer.throwsTagOutput(tt));
       alreadyDocumented.add(cd != null ? cd.qualifiedName() : tt.exceptionName());
     }
   }
   return result;
 }
Пример #7
0
 /**
  * Given a class, return the closest visible super class.
  *
  * @param classDoc the class we are searching the parent for.
  * @param configuration the current configuration of the doclet.
  * @return the closest visible super class. Return null if it cannot be found (i.e. classDoc is
  *     java.lang.Object).
  */
 public static Type getFirstVisibleSuperClass(ClassDoc classDoc, Configuration configuration) {
   if (classDoc == null) {
     return null;
   }
   Type sup = classDoc.superclassType();
   ClassDoc supClassDoc = classDoc.superclass();
   while (sup != null && (!(supClassDoc.isPublic() || isLinkable(supClassDoc, configuration)))) {
     if (supClassDoc.superclass().qualifiedName().equals(supClassDoc.qualifiedName())) break;
     sup = supClassDoc.superclassType();
     supClassDoc = supClassDoc.superclass();
   }
   if (classDoc.equals(supClassDoc)) {
     return null;
   }
   return sup;
 }
Пример #8
0
  public ThrowsTagImpl(String text, ClassDocImpl contextClass, MemberDocImpl contextMember) {
    super(text);

    char[] textarr = text.toCharArray();
    int i = 0;
    for (; i < textarr.length; ++i) {
      if (!Parser.isWhitespace(textarr[i])) break;
    }
    for (; i < textarr.length; ++i) {
      if (Parser.isWhitespace(textarr[i])) {
        this.exceptionName = new String(textarr, 0, i).trim();
        this.exceptionComment = new String(textarr, i, textarr.length - i).trim();
        break;
      }
    }
    if (null != exceptionName) {
      if (contextClass == null) {
        this.exception = Main.getRootDoc().classNamed(exceptionName);
      } else {
        this.exception = contextClass.findClass(exceptionName);
      }
      if (exception != null) this.exceptionName = exception.qualifiedName();
      else {
        if (text.trim().startsWith("<")) {
          Main.getRootDoc()
              .printWarning(
                  "Expected exception name but got '"
                      + text
                      + "' in class "
                      + contextClass.getClassName());
        }
      }
    } else {
      Main.getRootDoc()
          .printWarning(
              "@throws tag in comment for "
                  + contextClass.qualifiedName()
                  + "."
                  + contextMember.name()
                  + " doesn't specify an exception.");
    }
    if (this.exceptionComment != null) {
      setBody(this.exceptionComment, contextClass, contextMember);
    }
  }
Пример #9
0
  /**
   * The entry point into the Parser class.
   *
   * @param root A RootDoc intstance obtained via the doclet API
   * @return A XML (XStream) serializable element, containing everything parsed from javadoc doclet
   */
  public static Root ParseRoot(RootDoc root) {
    processingStorage = new HashMap<PackageDoc, ParserMediary>();

    try {
      md5 = MessageDigest.getInstance("MD5");
    } catch (NoSuchAlgorithmException e) {
      log.error("unable to acquire MD5 algorithm", e);
      return null;
    }

    rootXml = new Root();

    ClassDoc[] allClasses = root.classes();

    for (ClassDoc classDoc : allClasses) {
      PackageDoc doc = classDoc.containingPackage();

      ParserMediary mediary = null;

      // the age old 'if I have it pull out existing, if I don't make a new one'
      if (processingStorage.containsKey(doc)) {
        mediary = processingStorage.get(doc);
      } else {
        mediary =
            new ParserMediary(
                doc.name(),
                doc.commentText(),
                ParseAnnotationInstances(doc.annotations(), doc.name()));

        processingStorage.put(doc, mediary);
      }

      if (classDoc.isIncluded()) {
        // dev comment--why do enums show up as ordinary class?
        if (classDoc.isOrdinaryClass() || classDoc.isException() || classDoc.isError()) {
          mediary.addClass(ParseClass(classDoc));
        } else if (classDoc.isEnum()) {
          mediary.addEnum(ParseEnum(classDoc));
        } else if (isAnnotation(classDoc)) {
          mediary.addAnnotation(ParseAnnotation(classDoc));
        } else if (classDoc.isInterface()) {
          mediary.addInterface(ParseInterface(classDoc));
        }
      } else {
        log.debug("Skipping not-included class " + classDoc.qualifiedName());
      }
    }

    if (processingStorage.size() > 0) {
      List list = new ArrayList<Package>();

      for (ParserMediary mediary : processingStorage.values()) {
        list.add(mediary.wrapup());
      }

      rootXml.packages = (Package[]) list.toArray(new Package[] {});
    } else {
      log.warn("No packages found!");
    }

    return rootXml;
  }
Пример #10
0
  /**
   * 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;
  }