/** * 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); } } } }
/** Copy the doc files for the current ClassDoc if necessary. */ private void copyDocFiles() { PackageDoc containingPackage = annotationTypeDoc.containingPackage(); if ((configuration.packages == null || Arrays.binarySearch(configuration.packages, containingPackage) < 0) && !containingPackagesSeen.contains(containingPackage.name())) { // Only copy doc files dir if the containing package is not // documented AND if we have not documented a class from the same // package already. Otherwise, we are making duplicate copies. Util.copyDocFiles( configuration, Util.getPackageSourcePath(configuration, annotationTypeDoc.containingPackage()) + DirectoryManager.getDirectoryPath(annotationTypeDoc.containingPackage()) + File.separator, DocletConstants.DOC_FILES_DIR_NAME, true); containingPackagesSeen.add(containingPackage.name()); } }
/** * Add the list of classes that use the given package. * * @param contentTree the content tree to which the class list will be added */ protected void addClassList(Content contentTree) throws IOException { String[] classTableHeader = new String[] { configuration.getText( "doclet.0_and_1", configuration.getText("doclet.Class"), configuration.getText("doclet.Description")) }; Iterator<String> itp = usingPackageToUsedClasses.keySet().iterator(); while (itp.hasNext()) { String packageName = itp.next(); PackageDoc usingPackage = configuration.root.packageNamed(packageName); HtmlTree li = new HtmlTree(HtmlTag.LI); li.addStyle(HtmlStyle.blockList); if (usingPackage != null) { li.addContent(getMarkerAnchor(usingPackage.name())); } String tableSummary = configuration.getText( "doclet.Use_Table_Summary", configuration.getText("doclet.classes")); Content table = HtmlTree.TABLE( HtmlStyle.useSummary, 0, 3, 0, tableSummary, getTableCaption( configuration.getResource( "doclet.ClassUse_Classes.in.0.used.by.1", getPackageLink(pkgdoc, Util.getPackageName(pkgdoc)), getPackageLink(usingPackage, Util.getPackageName(usingPackage))))); table.addContent(getSummaryTableHeader(classTableHeader, "col")); Content tbody = new HtmlTree(HtmlTag.TBODY); Iterator<ClassDoc> itc = usingPackageToUsedClasses.get(packageName).iterator(); for (int i = 0; itc.hasNext(); i++) { HtmlTree tr = new HtmlTree(HtmlTag.TR); if (i % 2 == 0) { tr.addStyle(HtmlStyle.altColor); } else { tr.addStyle(HtmlStyle.rowColor); } addClassRow(itc.next(), packageName, tr); tbody.addContent(tr); } table.addContent(tbody); li.addContent(table); contentTree.addContent(li); } }
/** Generate the package use list. */ protected void generatePackageUseFile() throws IOException { Content body = getPackageUseHeader(); HtmlTree div = new HtmlTree(HtmlTag.DIV); div.addStyle(HtmlStyle.contentContainer); if (usingPackageToUsedClasses.isEmpty()) { div.addContent(getResource("doclet.ClassUse_No.usage.of.0", pkgdoc.name())); } else { addPackageUse(div); } body.addContent(div); addNavLinks(false, body); addBottom(body); printHtmlDocument(null, true, body); }
/** * Add the package use information. * * @param pkg the package that used the given package * @param contentTree the content tree to which the information will be added */ protected void addPackageUse(PackageDoc pkg, Content contentTree) throws IOException { Content tdFirst = HtmlTree.TD( HtmlStyle.colFirst, getHyperLink(Util.getPackageName(pkg), new StringContent(Util.getPackageName(pkg)))); contentTree.addContent(tdFirst); HtmlTree tdLast = new HtmlTree(HtmlTag.TD); tdLast.addStyle(HtmlStyle.colLast); if (pkg != null && pkg.name().length() != 0) { addSummaryComment(pkg, tdLast); } else { tdLast.addContent(getSpace()); } contentTree.addContent(tdLast); }
/** * Build the package serialized form for the current package being processed. * * @param node the XML element that specifies which components to document * @param serializedSummariesTree content tree to which the documentation will be added */ public void buildPackageSerializedForm(XMLNode node, Content serializedSummariesTree) { Content packageSerializedTree = writer.getPackageSerializedHeader(); String foo = currentPackage.name(); ClassDoc[] classes = currentPackage.allClasses(false); if (classes == null || classes.length == 0) { return; } if (!serialInclude(currentPackage)) { return; } if (!serialClassFoundToDocument(classes)) { return; } buildChildren(node, packageSerializedTree); serializedSummariesTree.addContent(packageSerializedTree); }
/** * Get the header for the package use listing. * * @return a content tree representing the package use header */ protected Content getPackageUseHeader() { String packageText = configuration.getText("doclet.Package"); String name = pkgdoc.name(); String title = configuration.getText("doclet.Window_ClassUse_Header", packageText, name); Content bodyTree = getBody(true, getWindowTitle(title)); addTop(bodyTree); addNavLinks(true, bodyTree); ContentBuilder headContent = new ContentBuilder(); headContent.addContent(getResource("doclet.ClassUse_Title", packageText)); headContent.addContent(new HtmlTree(HtmlTag.BR)); headContent.addContent(name); Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true, HtmlStyle.title, headContent); Content div = HtmlTree.DIV(HtmlStyle.header, heading); bodyTree.addContent(div); return bodyTree; }
/** * Given a package, return it's file name without the extension. * * @param packageDoc the package to check. * @return the file name of the given package. */ public static String getPackageFileHeadName(PackageDoc packageDoc) { return packageDoc == null || packageDoc.name().length() == 0 ? DocletConstants.DEFAULT_PACKAGE_FILE_NAME : packageDoc.name(); }
/** * 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; }
/** * Add at least the first sentence from a doc block for a package to the API. This is used by the * report generator if no comment is provided. The default source tree may not include the * package.html files, so this may be unavailable in many cases. Need to make sure that HTML tags * are not confused with XML tags. This could be done by stuffing the < character to another * string or by handling HTML in the parser. This second option is neater. Note that XML expects * all element tags to have either a closing "/>" or a matching end element tag. Due to the * difficulties of converting incorrect HTML to XHTML, the first option is used. */ public void addPkgDocumentation(RootDoc root, PackageDoc pd, int indent) { String rct = null; String filename = pd.name(); try { // See if the source path was specified as part of the // options and prepend it if it was. String srcLocation = null; String[][] options = root.options(); for (int opt = 0; opt < options.length; opt++) { if ((options[opt][0]).compareTo("-sourcepath") == 0) { srcLocation = options[opt][1]; break; } } filename = filename.replace('.', JDiff.DIR_SEP.charAt(0)); if (srcLocation != null) { // Make a relative location absolute if (srcLocation.startsWith("..")) { String curDir = System.getProperty("user.dir"); while (srcLocation.startsWith("..")) { srcLocation = srcLocation.substring(3); int idx = curDir.lastIndexOf(JDiff.DIR_SEP); curDir = curDir.substring(0, idx + 1); } srcLocation = curDir + srcLocation; } filename = srcLocation + JDiff.DIR_SEP + filename; } // Try both ".htm" and ".html" filename += JDiff.DIR_SEP + "package.htm"; File f2 = new File(filename); if (!f2.exists()) { filename += "l"; } FileInputStream f = new FileInputStream(filename); BufferedReader d = new BufferedReader(new InputStreamReader(f)); String str = d.readLine(); // Ignore everything except the lines between <body> elements boolean inBody = false; while (str != null) { if (!inBody) { if (str.toLowerCase().trim().startsWith("<body")) { inBody = true; } str = d.readLine(); // Get the next line continue; // Ignore the line } else { if (str.toLowerCase().trim().startsWith("</body")) { inBody = false; continue; // Ignore the line } } if (rct == null) rct = str + "\n"; else rct += str + "\n"; str = d.readLine(); } } catch (java.io.FileNotFoundException e) { // If it doesn't exist, that's fine if (trace) System.out.println("No package level documentation file at '" + filename + "'"); } catch (java.io.IOException e) { System.out.println("Error reading file \"" + filename + "\": " + e.getMessage()); System.exit(5); } if (rct != null) { rct = stripNonPrintingChars(rct, (Doc) pd); rct = rct.trim(); if (rct.compareTo("") != 0 && rct.indexOf(Comments.placeHolderText) == -1 && rct.indexOf("InsertOtherCommentsHere") == -1) { int idx = endOfFirstSentence(rct); if (idx == 0) return; for (int i = 0; i < indent; i++) outputFile.print(" "); outputFile.println("<doc>"); for (int i = 0; i < indent; i++) outputFile.print(" "); String firstSentence = null; if (idx == -1) firstSentence = rct; else firstSentence = rct.substring(0, idx + 1); String firstSentenceNoTags = API.stuffHTMLTags(firstSentence); outputFile.println(firstSentenceNoTags); for (int i = 0; i < indent; i++) outputFile.print(" "); outputFile.println("</doc>"); } } }
/** * Process each package and the classes/interfaces within it. * * @param pd an array of PackageDoc objects */ public void processPackages(RootDoc root) { PackageDoc[] specified_pd = root.specifiedPackages(); Map pdl = new TreeMap(); for (int i = 0; specified_pd != null && i < specified_pd.length; i++) { pdl.put(specified_pd[i].name(), specified_pd[i]); } // Classes may be specified separately, so merge their packages into the // list of specified packages. ClassDoc[] cd = root.specifiedClasses(); // This is lists of the specific classes to document Map classesToUse = new HashMap(); for (int i = 0; cd != null && i < cd.length; i++) { PackageDoc cpd = cd[i].containingPackage(); if (cpd == null && !packagesOnly) { // If the RootDoc object has been created from a jar file // this duplicates classes, so we have to be able to disable it. // TODO this is still null? cpd = root.packageNamed("anonymous"); } String pkgName = cpd.name(); String className = cd[i].name(); if (trace) System.out.println("Found package " + pkgName + " for class " + className); if (!pdl.containsKey(pkgName)) { if (trace) System.out.println("Adding new package " + pkgName); pdl.put(pkgName, cpd); } // Keep track of the specific classes to be used for this package List classes; if (classesToUse.containsKey(pkgName)) { classes = (ArrayList) classesToUse.get(pkgName); } else { classes = new ArrayList(); } classes.add(cd[i]); classesToUse.put(pkgName, classes); } PackageDoc[] pd = (PackageDoc[]) pdl.values().toArray(new PackageDoc[0]); for (int i = 0; pd != null && i < pd.length; i++) { String pkgName = pd[i].name(); // Check for an exclude tag in the package doc block, but not // in the package.htm[l] file. if (!shownElement(pd[i], null)) continue; if (trace) System.out.println("PROCESSING PACKAGE: " + pkgName); outputFile.println("<package name=\"" + pkgName + "\">"); int tagCount = pd[i].tags().length; if (trace) System.out.println("#tags: " + tagCount); List classList; if (classesToUse.containsKey(pkgName)) { // Use only the specified classes in the package System.out.println("Using the specified classes"); classList = (ArrayList) classesToUse.get(pkgName); } else { // Use all classes in the package classList = new LinkedList(Arrays.asList(pd[i].allClasses())); } Collections.sort(classList); ClassDoc[] classes = new ClassDoc[classList.size()]; classes = (ClassDoc[]) classList.toArray(classes); processClasses(classes, pkgName); addPkgDocumentation(root, pd[i], 2); outputFile.println("</package>"); } } // processPackages