1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/javadoc/RootDocImpl.java Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,354 @@
1.4 +/*
1.5 + * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Sun designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Sun in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
1.25 + * CA 95054 USA or visit www.sun.com if you need additional information or
1.26 + * have any questions.
1.27 + */
1.28 +
1.29 +package com.sun.tools.javadoc;
1.30 +
1.31 +import java.io.IOException;
1.32 +import java.io.FileInputStream;
1.33 +import java.io.File;
1.34 +
1.35 +import com.sun.javadoc.*;
1.36 +
1.37 +import com.sun.tools.javac.tree.JCTree.JCClassDecl;
1.38 +import com.sun.tools.javac.code.Symbol;
1.39 +import com.sun.tools.javac.util.List;
1.40 +import com.sun.tools.javac.util.ListBuffer;
1.41 +import com.sun.tools.javac.util.Position;
1.42 +
1.43 +/**
1.44 + * This class holds the information from one run of javadoc.
1.45 + * Particularly the packages, classes and options specified
1.46 + * by the user..
1.47 + *
1.48 + * @since 1.2
1.49 + * @author Robert Field
1.50 + * @author Atul M Dambalkar
1.51 + * @author Neal Gafter (rewrite)
1.52 + */
1.53 +public class RootDocImpl extends DocImpl implements RootDoc {
1.54 +
1.55 + /**
1.56 + * list of classes specified on the command line.
1.57 + */
1.58 + private List<ClassDocImpl> cmdLineClasses;
1.59 +
1.60 + /**
1.61 + * list of packages specified on the command line.
1.62 + */
1.63 + private List<PackageDocImpl> cmdLinePackages;
1.64 +
1.65 + /**
1.66 + * a collection of all options.
1.67 + */
1.68 + private List<String[]> options;
1.69 +
1.70 + /**
1.71 + * Constructor used when reading source files.
1.72 + *
1.73 + * @param env the documentation environment, state for this javadoc run
1.74 + * @param classes list of classes specified on the commandline
1.75 + * @param packages list of package names specified on the commandline
1.76 + * @param options list of options
1.77 + */
1.78 + public RootDocImpl(DocEnv env, List<JCClassDecl> classes, List<String> packages, List<String[]> options) {
1.79 + super(env, null);
1.80 + this.options = options;
1.81 + setPackages(env, packages);
1.82 + setClasses(env, classes);
1.83 + }
1.84 +
1.85 + /**
1.86 + * Constructor used when reading class files.
1.87 + *
1.88 + * @param env the documentation environment, state for this javadoc run
1.89 + * @param classes list of class names specified on the commandline
1.90 + * @param options list of options
1.91 + */
1.92 + public RootDocImpl(DocEnv env, List<String> classes, List<String[]> options) {
1.93 + super(env, null);
1.94 + this.options = options;
1.95 + cmdLinePackages = List.nil();
1.96 + ListBuffer<ClassDocImpl> classList = new ListBuffer<ClassDocImpl>();
1.97 + for (String className : classes) {
1.98 + ClassDocImpl c = env.loadClass(className);
1.99 + if (c == null)
1.100 + env.error(null, "javadoc.class_not_found", className);
1.101 + else
1.102 + classList = classList.append(c);
1.103 + }
1.104 + cmdLineClasses = classList.toList();
1.105 + }
1.106 +
1.107 + /**
1.108 + * Initialize classes information. Those classes are input from
1.109 + * command line.
1.110 + *
1.111 + * @param env the compilation environment
1.112 + * @param classes a list of ClassDeclaration
1.113 + */
1.114 + private void setClasses(DocEnv env, List<JCClassDecl> classes) {
1.115 + ListBuffer<ClassDocImpl> result = new ListBuffer<ClassDocImpl>();
1.116 + for (JCClassDecl def : classes) {
1.117 + //### Do we want modifier check here?
1.118 + if (env.shouldDocument(def.sym)) {
1.119 + ClassDocImpl cd = env.getClassDoc(def.sym);
1.120 + if (cd != null) {
1.121 + cd.isIncluded = true;
1.122 + result.append(cd);
1.123 + } //else System.out.println(" (classdoc is null)");//DEBUG
1.124 + } //else System.out.println(" (env.shouldDocument() returned false)");//DEBUG
1.125 + }
1.126 + cmdLineClasses = result.toList();
1.127 + }
1.128 +
1.129 + /**
1.130 + * Initialize packages information.
1.131 + *
1.132 + * @param env the compilation environment
1.133 + * @param packages a list of package names (String)
1.134 + */
1.135 + private void setPackages(DocEnv env, List<String> packages) {
1.136 + ListBuffer<PackageDocImpl> packlist = new ListBuffer<PackageDocImpl>();
1.137 + for (String name : packages) {
1.138 + PackageDocImpl pkg = env.lookupPackage(name);
1.139 + if (pkg != null) {
1.140 + pkg.isIncluded = true;
1.141 + packlist.append(pkg);
1.142 + } else {
1.143 + env.warning(null, "main.no_source_files_for_package", name);
1.144 + }
1.145 + }
1.146 + cmdLinePackages = packlist.toList();
1.147 + }
1.148 +
1.149 + /**
1.150 + * Command line options.
1.151 + *
1.152 + * <pre>
1.153 + * For example, given:
1.154 + * javadoc -foo this that -bar other ...
1.155 + *
1.156 + * This method will return:
1.157 + * options()[0][0] = "-foo"
1.158 + * options()[0][1] = "this"
1.159 + * options()[0][2] = "that"
1.160 + * options()[1][0] = "-bar"
1.161 + * options()[1][1] = "other"
1.162 + * </pre>
1.163 + *
1.164 + * @return an array of arrays of String.
1.165 + */
1.166 + public String[][] options() {
1.167 + return options.toArray(new String[options.length()][]);
1.168 + }
1.169 +
1.170 + /**
1.171 + * Packages specified on the command line.
1.172 + */
1.173 + public PackageDoc[] specifiedPackages() {
1.174 + return (PackageDoc[])cmdLinePackages
1.175 + .toArray(new PackageDocImpl[cmdLinePackages.length()]);
1.176 + }
1.177 +
1.178 + /**
1.179 + * Classes and interfaces specified on the command line.
1.180 + */
1.181 + public ClassDoc[] specifiedClasses() {
1.182 + ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<ClassDocImpl>();
1.183 + for (ClassDocImpl cd : cmdLineClasses) {
1.184 + cd.addAllClasses(classesToDocument, true);
1.185 + }
1.186 + return (ClassDoc[])classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]);
1.187 + }
1.188 +
1.189 + /**
1.190 + * Return all classes and interfaces (including those inside
1.191 + * packages) to be documented.
1.192 + */
1.193 + public ClassDoc[] classes() {
1.194 + ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<ClassDocImpl>();
1.195 + for (ClassDocImpl cd : cmdLineClasses) {
1.196 + cd.addAllClasses(classesToDocument, true);
1.197 + }
1.198 + for (PackageDocImpl pd : cmdLinePackages) {
1.199 + pd.addAllClassesTo(classesToDocument);
1.200 + }
1.201 + return classesToDocument.toArray(new ClassDocImpl[classesToDocument.length()]);
1.202 + }
1.203 +
1.204 + /**
1.205 + * Return a ClassDoc for the specified class/interface name
1.206 + *
1.207 + * @param qualifiedName qualified class name
1.208 + * (i.e. includes package name).
1.209 + *
1.210 + * @return a ClassDocImpl holding the specified class, null if
1.211 + * this class is not referenced.
1.212 + */
1.213 + public ClassDoc classNamed(String qualifiedName) {
1.214 + return env.lookupClass(qualifiedName);
1.215 + }
1.216 +
1.217 + /**
1.218 + * Return a PackageDoc for the specified package name
1.219 + *
1.220 + * @param name package name
1.221 + *
1.222 + * @return a PackageDoc holding the specified package, null if
1.223 + * this package is not referenced.
1.224 + */
1.225 + public PackageDoc packageNamed(String name) {
1.226 + return env.lookupPackage(name);
1.227 + }
1.228 +
1.229 + /**
1.230 + * Return the name of this Doc item.
1.231 + *
1.232 + * @return the string <code>"*RootDocImpl*"</code>.
1.233 + */
1.234 + public String name() {
1.235 + return "*RootDocImpl*";
1.236 + }
1.237 +
1.238 + /**
1.239 + * Return the name of this Doc item.
1.240 + *
1.241 + * @return the string <code>"*RootDocImpl*"</code>.
1.242 + */
1.243 + public String qualifiedName() {
1.244 + return "*RootDocImpl*";
1.245 + }
1.246 +
1.247 + /**
1.248 + * Return true if this Doc is include in the active set.
1.249 + * RootDocImpl isn't even a program entity so it is always false.
1.250 + */
1.251 + public boolean isIncluded() {
1.252 + return false;
1.253 + }
1.254 +
1.255 + /**
1.256 + * Print error message, increment error count.
1.257 + *
1.258 + * @param msg message to print
1.259 + */
1.260 + public void printError(String msg) {
1.261 + env.printError(msg);
1.262 + }
1.263 +
1.264 + /**
1.265 + * Print error message, increment error count.
1.266 + *
1.267 + * @param msg message to print
1.268 + */
1.269 + public void printError(SourcePosition pos, String msg) {
1.270 + env.printError(pos, msg);
1.271 + }
1.272 +
1.273 + /**
1.274 + * Print warning message, increment warning count.
1.275 + *
1.276 + * @param msg message to print
1.277 + */
1.278 + public void printWarning(String msg) {
1.279 + env.printWarning(msg);
1.280 + }
1.281 +
1.282 + /**
1.283 + * Print warning message, increment warning count.
1.284 + *
1.285 + * @param msg message to print
1.286 + */
1.287 + public void printWarning(SourcePosition pos, String msg) {
1.288 + env.printWarning(pos, msg);
1.289 + }
1.290 +
1.291 + /**
1.292 + * Print a message.
1.293 + *
1.294 + * @param msg message to print
1.295 + */
1.296 + public void printNotice(String msg) {
1.297 + env.printNotice(msg);
1.298 + }
1.299 +
1.300 + /**
1.301 + * Print a message.
1.302 + *
1.303 + * @param msg message to print
1.304 + */
1.305 + public void printNotice(SourcePosition pos, String msg) {
1.306 + env.printNotice(pos, msg);
1.307 + }
1.308 +
1.309 + /**
1.310 + * Return the path of the overview file and null if it does not exist.
1.311 + * @return the path of the overview file and null if it does not exist.
1.312 + */
1.313 + private String getOverviewPath() {
1.314 + for (String[] opt : options) {
1.315 + if (opt[0].equals("-overview")) {
1.316 + return opt[1];
1.317 + }
1.318 + }
1.319 + return null;
1.320 + }
1.321 +
1.322 + /**
1.323 + * Do lazy initialization of "documentation" string.
1.324 + */
1.325 + protected String documentation() {
1.326 + if (documentation == null) {
1.327 + int cnt = options.length();
1.328 + String overviewPath = getOverviewPath();
1.329 + if (overviewPath == null) {
1.330 + // no doc file to be had
1.331 + documentation = "";
1.332 + } else {
1.333 + // read from file
1.334 + try {
1.335 + documentation = readHTMLDocumentation(
1.336 + new FileInputStream(overviewPath),
1.337 + overviewPath);
1.338 + } catch (IOException exc) {
1.339 + documentation = "";
1.340 + env.error(null, "javadoc.File_Read_Error", overviewPath);
1.341 + }
1.342 + }
1.343 + }
1.344 + return documentation;
1.345 + }
1.346 +
1.347 + /**
1.348 + * Return the source position of the entity, or null if
1.349 + * no position is available.
1.350 + */
1.351 + public SourcePosition position() {
1.352 + String path;
1.353 + return ((path = getOverviewPath()) == null) ?
1.354 + null :
1.355 + SourcePositionImpl.make(path, Position.NOPOS, null);
1.356 + }
1.357 +}
