| /* |
| * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package com.sun.tools.javadoc; |
| |
| import java.io.IOException; |
| import java.util.Collection; |
| import java.util.Locale; |
| |
| import javax.tools.JavaFileManager; |
| import javax.tools.JavaFileObject; |
| import javax.tools.StandardJavaFileManager; |
| |
| import com.sun.javadoc.*; |
| import com.sun.tools.javac.tree.JCTree.JCClassDecl; |
| import com.sun.tools.javac.util.List; |
| import com.sun.tools.javac.util.ListBuffer; |
| import com.sun.tools.javac.util.Position; |
| |
| /** |
| * This class holds the information from one run of javadoc. |
| * Particularly the packages, classes and options specified |
| * by the user. |
| * |
| * <p><b>This is NOT part of any supported API. |
| * If you write code that depends on this, you do so at your own risk. |
| * This code and its internal interfaces are subject to change or |
| * deletion without notice.</b> |
| * |
| * @since 1.2 |
| * @author Robert Field |
| * @author Atul M Dambalkar |
| * @author Neal Gafter (rewrite) |
| */ |
| public class RootDocImpl extends DocImpl implements RootDoc { |
| |
| /** |
| * list of classes specified on the command line. |
| */ |
| private List<ClassDocImpl> cmdLineClasses; |
| |
| /** |
| * list of packages specified on the command line. |
| */ |
| private List<PackageDocImpl> cmdLinePackages; |
| |
| /** |
| * a collection of all options. |
| */ |
| private List<String[]> options; |
| |
| /** |
| * Constructor used when reading source files. |
| * |
| * @param env the documentation environment, state for this javadoc run |
| * @param classes list of classes specified on the commandline |
| * @param packages list of package names specified on the commandline |
| * @param options list of options |
| */ |
| public RootDocImpl(DocEnv env, List<JCClassDecl> classes, List<String> packages, List<String[]> options) { |
| super(env, null); |
| this.options = options; |
| setPackages(env, packages); |
| setClasses(env, classes); |
| } |
| |
| /** |
| * Constructor used when reading class files. |
| * |
| * @param env the documentation environment, state for this javadoc run |
| * @param classes list of class names specified on the commandline |
| * @param options list of options |
| */ |
| public RootDocImpl(DocEnv env, List<String> classes, List<String[]> options) { |
| super(env, null); |
| this.options = options; |
| cmdLinePackages = List.nil(); |
| ListBuffer<ClassDocImpl> classList = new ListBuffer<ClassDocImpl>(); |
| for (String className : classes) { |
| ClassDocImpl c = env.loadClass(className); |
| if (c == null) |
| env.error(null, "javadoc.class_not_found", className); |
| else |
| classList = classList.append(c); |
| } |
| cmdLineClasses = classList.toList(); |
| } |
| |
| /** |
| * Initialize classes information. Those classes are input from |
| * command line. |
| * |
| * @param env the compilation environment |
| * @param classes a list of ClassDeclaration |
| */ |
| private void setClasses(DocEnv env, List<JCClassDecl> classes) { |
| ListBuffer<ClassDocImpl> result = new ListBuffer<ClassDocImpl>(); |
| for (JCClassDecl def : classes) { |
| //### Do we want modifier check here? |
| if (env.shouldDocument(def.sym)) { |
| ClassDocImpl cd = env.getClassDoc(def.sym); |
| if (cd != null) { |
| cd.isIncluded = true; |
| result.append(cd); |
| } //else System.out.println(" (classdoc is null)");//DEBUG |
| } //else System.out.println(" (env.shouldDocument() returned false)");//DEBUG |
| } |
| cmdLineClasses = result.toList(); |
| } |
| |
| /** |
| * Initialize packages information. |
| * |
| * @param env the compilation environment |
| * @param packages a list of package names (String) |
| */ |
| private void setPackages(DocEnv env, List<String> packages) { |
| ListBuffer<PackageDocImpl> packlist = new ListBuffer<PackageDocImpl>(); |
| for (String name : packages) { |
| PackageDocImpl pkg = env.lookupPackage(name); |
| if (pkg != null) { |
| pkg.isIncluded = true; |
| packlist.append(pkg); |
| } else { |
| env.warning(null, "main.no_source_files_for_package", name); |
| } |
| } |
| cmdLinePackages = packlist.toList(); |
| } |
| |
| /** |
| * Command line options. |
| * |
| * <pre> |
| * For example, given: |
| * javadoc -foo this that -bar other ... |
| * |
| * This method will return: |
| * options()[0][0] = "-foo" |
| * options()[0][1] = "this" |
| * options()[0][2] = "that" |
| * options()[1][0] = "-bar" |
| * options()[1][1] = "other" |
| * </pre> |
| * |
| * @return an array of arrays of String. |
| */ |
| public String[][] options() { |
| return options.toArray(new String[options.length()][]); |
| } |
| |
| /** |
| * Packages specified on the command line. |
| */ |
| public PackageDoc[] specifiedPackages() { |
| return (PackageDoc[])cmdLinePackages |
| .toArray(new PackageDocImpl[cmdLinePackages.length()]); |
| } |
| |
| /** |
| * Classes and interfaces specified on the command line. |
| */ |
| public ClassDoc[] specifiedClasses() { |
| ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<ClassDocImpl>(); |
| for (ClassDocImpl cd : cmdLineClasses) { |
| cd.addAllClasses(classesToDocument, true); |
| } |
| return (ClassDoc[])classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]); |
| } |
| |
| /** |
| * Return all classes and interfaces (including those inside |
| * packages) to be documented. |
| */ |
| public ClassDoc[] classes() { |
| ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<ClassDocImpl>(); |
| for (ClassDocImpl cd : cmdLineClasses) { |
| cd.addAllClasses(classesToDocument, true); |
| } |
| for (PackageDocImpl pd : cmdLinePackages) { |
| pd.addAllClassesTo(classesToDocument); |
| } |
| return classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]); |
| } |
| |
| /** |
| * Return a ClassDoc for the specified class/interface name |
| * |
| * @param qualifiedName qualified class name |
| * (i.e. includes package name). |
| * |
| * @return a ClassDocImpl holding the specified class, null if |
| * this class is not referenced. |
| */ |
| public ClassDoc classNamed(String qualifiedName) { |
| return env.lookupClass(qualifiedName); |
| } |
| |
| /** |
| * Return a PackageDoc for the specified package name |
| * |
| * @param name package name |
| * |
| * @return a PackageDoc holding the specified package, null if |
| * this package is not referenced. |
| */ |
| public PackageDoc packageNamed(String name) { |
| return env.lookupPackage(name); |
| } |
| |
| /** |
| * Return the name of this Doc item. |
| * |
| * @return the string <code>"*RootDocImpl*"</code>. |
| */ |
| public String name() { |
| return "*RootDocImpl*"; |
| } |
| |
| /** |
| * Return the name of this Doc item. |
| * |
| * @return the string <code>"*RootDocImpl*"</code>. |
| */ |
| public String qualifiedName() { |
| return "*RootDocImpl*"; |
| } |
| |
| /** |
| * Return true if this Doc is include in the active set. |
| * RootDocImpl isn't even a program entity so it is always false. |
| */ |
| public boolean isIncluded() { |
| return false; |
| } |
| |
| /** |
| * Print error message, increment error count. |
| * |
| * @param msg message to print |
| */ |
| public void printError(String msg) { |
| env.printError(msg); |
| } |
| |
| /** |
| * Print error message, increment error count. |
| * |
| * @param msg message to print |
| */ |
| public void printError(SourcePosition pos, String msg) { |
| env.printError(pos, msg); |
| } |
| |
| /** |
| * Print warning message, increment warning count. |
| * |
| * @param msg message to print |
| */ |
| public void printWarning(String msg) { |
| env.printWarning(msg); |
| } |
| |
| /** |
| * Print warning message, increment warning count. |
| * |
| * @param msg message to print |
| */ |
| public void printWarning(SourcePosition pos, String msg) { |
| env.printWarning(pos, msg); |
| } |
| |
| /** |
| * Print a message. |
| * |
| * @param msg message to print |
| */ |
| public void printNotice(String msg) { |
| env.printNotice(msg); |
| } |
| |
| /** |
| * Print a message. |
| * |
| * @param msg message to print |
| */ |
| public void printNotice(SourcePosition pos, String msg) { |
| env.printNotice(pos, msg); |
| } |
| |
| /** |
| * Return the path of the overview file and null if it does not exist. |
| * @return the path of the overview file and null if it does not exist. |
| */ |
| private JavaFileObject getOverviewPath() { |
| for (String[] opt : options) { |
| if (opt[0].equals("-overview")) { |
| if (env.fileManager instanceof StandardJavaFileManager) { |
| StandardJavaFileManager fm = (StandardJavaFileManager) env.fileManager; |
| return fm.getJavaFileObjects(opt[1]).iterator().next(); |
| } |
| } |
| } |
| return null; |
| } |
| |
| /** |
| * Do lazy initialization of "documentation" string. |
| */ |
| @Override |
| protected String documentation() { |
| if (documentation == null) { |
| JavaFileObject overviewPath = getOverviewPath(); |
| if (overviewPath == null) { |
| // no doc file to be had |
| documentation = ""; |
| } else { |
| // read from file |
| try { |
| documentation = readHTMLDocumentation( |
| overviewPath.openInputStream(), |
| overviewPath); |
| } catch (IOException exc) { |
| documentation = ""; |
| env.error(null, "javadoc.File_Read_Error", overviewPath.getName()); |
| } |
| } |
| } |
| return documentation; |
| } |
| |
| /** |
| * Return the source position of the entity, or null if |
| * no position is available. |
| */ |
| @Override |
| public SourcePosition position() { |
| JavaFileObject path; |
| return ((path = getOverviewPath()) == null) ? |
| null : |
| SourcePositionImpl.make(path, Position.NOPOS, null); |
| } |
| |
| /** |
| * Return the locale provided by the user or the default locale value. |
| */ |
| public Locale getLocale() { |
| return env.doclocale.locale; |
| } |
| |
| /** |
| * Return the current file manager. |
| */ |
| public JavaFileManager getFileManager() { |
| return env.fileManager; |
| } |
| |
| public void initDocLint(Collection<String> opts, Collection<String> customTagNames) { |
| env.initDoclint(opts, customTagNames); |
| } |
| |
| public boolean showTagMessages() { |
| return env.showTagMessages(); |
| } |
| } |