/**
   * 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);
        }
      }
    }
  }
 /**
  * Get the name of the package, this class is in.
  *
  * @param cd ClassDoc.
  */
 public String getPkgName(ClassDoc cd) {
   String pkgName = cd.containingPackage().name();
   if (pkgName.length() > 0) {
     pkgName += ".";
     return pkgName;
   }
   return "";
 }
 /**
  * Return true if the given <code>ProgramElement</code> is inherited by the class that is being
  * documented.
  *
  * @param ped The <code>ProgramElement</code> being checked. return true if the <code>
  *     ProgramElement</code> is being inherited and false otherwise.
  */
 protected boolean isInherited(ProgramElementDoc ped) {
   if (ped.isPrivate()
       || (ped.isPackagePrivate()
           && !ped.containingPackage().equals(classdoc.containingPackage()))) {
     return false;
   }
   return true;
 }
  /**
   * Add the given class to the given map.
   *
   * @param classdoc the ClassDoc to add to the catelog.
   * @param map the Map to add the ClassDoc to.
   */
  private void addClass(ClassDoc classdoc, Map<String, Set<ClassDoc>> map) {

    PackageDoc pkg = classdoc.containingPackage();
    if (pkg.isIncluded() || (configuration.nodeprecated && Util.isDeprecated(pkg))) {
      // No need to catalog this class if it's package is
      // included on the command line or if -nodeprecated option is set
      // and the containing package is marked as deprecated.
      return;
    }
    String key = Util.getPackageName(pkg);
    Set<ClassDoc> s = map.get(key);
    if (s == null) {
      packageSet.add(key);
      s = new HashSet<ClassDoc>();
    }
    s.add(classdoc);
    map.put(key, s);
  }
  /**
   * 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;
  }