001: /*
002: * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package com.sun.tools.javadoc;
027:
028: import java.io.IOException;
029: import java.io.FileInputStream;
030: import java.io.File;
031:
032: import com.sun.javadoc.*;
033:
034: import com.sun.tools.javac.tree.JCTree.JCClassDecl;
035: import com.sun.tools.javac.code.Symbol;
036: import com.sun.tools.javac.util.List;
037: import com.sun.tools.javac.util.ListBuffer;
038: import com.sun.tools.javac.util.Position;
039:
040: /**
041: * This class holds the information from one run of javadoc.
042: * Particularly the packages, classes and options specified
043: * by the user..
044: *
045: * @since 1.2
046: * @author Robert Field
047: * @author Atul M Dambalkar
048: * @author Neal Gafter (rewrite)
049: */
050: public class RootDocImpl extends DocImpl implements RootDoc {
051:
052: /**
053: * list of classes specified on the command line.
054: */
055: private List<ClassDocImpl> cmdLineClasses;
056:
057: /**
058: * list of packages specified on the command line.
059: */
060: private List<PackageDocImpl> cmdLinePackages;
061:
062: /**
063: * a collection of all options.
064: */
065: private List<String[]> options;
066:
067: /**
068: * Constructor used when reading source files.
069: *
070: * @param env the documentation environment, state for this javadoc run
071: * @param classes list of classes specified on the commandline
072: * @param packages list of package names specified on the commandline
073: * @param options list of options
074: */
075: public RootDocImpl(DocEnv env, List<JCClassDecl> classes,
076: List<String> packages, List<String[]> options) {
077: super (env, null);
078: this .options = options;
079: setPackages(env, packages);
080: setClasses(env, classes);
081: }
082:
083: /**
084: * Constructor used when reading class files.
085: *
086: * @param env the documentation environment, state for this javadoc run
087: * @param classes list of class names specified on the commandline
088: * @param options list of options
089: */
090: public RootDocImpl(DocEnv env, List<String> classes,
091: List<String[]> options) {
092: super (env, null);
093: this .options = options;
094: cmdLinePackages = List.nil();
095: ListBuffer<ClassDocImpl> classList = new ListBuffer<ClassDocImpl>();
096: for (String className : classes) {
097: ClassDocImpl c = env.loadClass(className);
098: if (c == null)
099: env.error(null, "javadoc.class_not_found", className);
100: else
101: classList = classList.append(c);
102: }
103: cmdLineClasses = classList.toList();
104: }
105:
106: /**
107: * Initialize classes information. Those classes are input from
108: * command line.
109: *
110: * @param env the compilation environment
111: * @param classes a list of ClassDeclaration
112: */
113: private void setClasses(DocEnv env, List<JCClassDecl> classes) {
114: ListBuffer<ClassDocImpl> result = new ListBuffer<ClassDocImpl>();
115: for (JCClassDecl def : classes) {
116: //### Do we want modifier check here?
117: if (env.shouldDocument(def.sym)) {
118: ClassDocImpl cd = env.getClassDoc(def.sym);
119: if (cd != null) {
120: cd.isIncluded = true;
121: result.append(cd);
122: } //else System.out.println(" (classdoc is null)");//DEBUG
123: } //else System.out.println(" (env.shouldDocument() returned false)");//DEBUG
124: }
125: cmdLineClasses = result.toList();
126: }
127:
128: /**
129: * Initialize packages information.
130: *
131: * @param env the compilation environment
132: * @param packages a list of package names (String)
133: */
134: private void setPackages(DocEnv env, List<String> packages) {
135: ListBuffer<PackageDocImpl> packlist = new ListBuffer<PackageDocImpl>();
136: for (String name : packages) {
137: PackageDocImpl pkg = env.lookupPackage(name);
138: if (pkg != null) {
139: pkg.isIncluded = true;
140: packlist.append(pkg);
141: } else {
142: env.warning(null, "main.no_source_files_for_package",
143: name);
144: }
145: }
146: cmdLinePackages = packlist.toList();
147: }
148:
149: /**
150: * Command line options.
151: *
152: * <pre>
153: * For example, given:
154: * javadoc -foo this that -bar other ...
155: *
156: * This method will return:
157: * options()[0][0] = "-foo"
158: * options()[0][1] = "this"
159: * options()[0][2] = "that"
160: * options()[1][0] = "-bar"
161: * options()[1][1] = "other"
162: * </pre>
163: *
164: * @return an array of arrays of String.
165: */
166: public String[][] options() {
167: return options.toArray(new String[options.length()][]);
168: }
169:
170: /**
171: * Packages specified on the command line.
172: */
173: public PackageDoc[] specifiedPackages() {
174: return (PackageDoc[]) cmdLinePackages
175: .toArray(new PackageDocImpl[cmdLinePackages.length()]);
176: }
177:
178: /**
179: * Classes and interfaces specified on the command line.
180: */
181: public ClassDoc[] specifiedClasses() {
182: ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<ClassDocImpl>();
183: for (ClassDocImpl cd : cmdLineClasses) {
184: cd.addAllClasses(classesToDocument, true);
185: }
186: return (ClassDoc[]) classesToDocument
187: .toArray(new ClassDocImpl[classesToDocument.length()]);
188: }
189:
190: /**
191: * Return all classes and interfaces (including those inside
192: * packages) to be documented.
193: */
194: public ClassDoc[] classes() {
195: ListBuffer<ClassDocImpl> classesToDocument = new ListBuffer<ClassDocImpl>();
196: for (ClassDocImpl cd : cmdLineClasses) {
197: cd.addAllClasses(classesToDocument, true);
198: }
199: for (PackageDocImpl pd : cmdLinePackages) {
200: pd.addAllClassesTo(classesToDocument);
201: }
202: return classesToDocument
203: .toArray(new ClassDocImpl[classesToDocument.length()]);
204: }
205:
206: /**
207: * Return a ClassDoc for the specified class/interface name
208: *
209: * @param qualifiedName qualified class name
210: * (i.e. includes package name).
211: *
212: * @return a ClassDocImpl holding the specified class, null if
213: * this class is not referenced.
214: */
215: public ClassDoc classNamed(String qualifiedName) {
216: return env.lookupClass(qualifiedName);
217: }
218:
219: /**
220: * Return a PackageDoc for the specified package name
221: *
222: * @param name package name
223: *
224: * @return a PackageDoc holding the specified package, null if
225: * this package is not referenced.
226: */
227: public PackageDoc packageNamed(String name) {
228: return env.lookupPackage(name);
229: }
230:
231: /**
232: * Return the name of this Doc item.
233: *
234: * @return the string <code>"*RootDocImpl*"</code>.
235: */
236: public String name() {
237: return "*RootDocImpl*";
238: }
239:
240: /**
241: * Return the name of this Doc item.
242: *
243: * @return the string <code>"*RootDocImpl*"</code>.
244: */
245: public String qualifiedName() {
246: return "*RootDocImpl*";
247: }
248:
249: /**
250: * Return true if this Doc is include in the active set.
251: * RootDocImpl isn't even a program entity so it is always false.
252: */
253: public boolean isIncluded() {
254: return false;
255: }
256:
257: /**
258: * Print error message, increment error count.
259: *
260: * @param msg message to print
261: */
262: public void printError(String msg) {
263: env.printError(msg);
264: }
265:
266: /**
267: * Print error message, increment error count.
268: *
269: * @param msg message to print
270: */
271: public void printError(SourcePosition pos, String msg) {
272: env.printError(pos, msg);
273: }
274:
275: /**
276: * Print warning message, increment warning count.
277: *
278: * @param msg message to print
279: */
280: public void printWarning(String msg) {
281: env.printWarning(msg);
282: }
283:
284: /**
285: * Print warning message, increment warning count.
286: *
287: * @param msg message to print
288: */
289: public void printWarning(SourcePosition pos, String msg) {
290: env.printWarning(pos, msg);
291: }
292:
293: /**
294: * Print a message.
295: *
296: * @param msg message to print
297: */
298: public void printNotice(String msg) {
299: env.printNotice(msg);
300: }
301:
302: /**
303: * Print a message.
304: *
305: * @param msg message to print
306: */
307: public void printNotice(SourcePosition pos, String msg) {
308: env.printNotice(pos, msg);
309: }
310:
311: /**
312: * Return the path of the overview file and null if it does not exist.
313: * @return the path of the overview file and null if it does not exist.
314: */
315: private String getOverviewPath() {
316: for (String[] opt : options) {
317: if (opt[0].equals("-overview")) {
318: return opt[1];
319: }
320: }
321: return null;
322: }
323:
324: /**
325: * Do lazy initialization of "documentation" string.
326: */
327: protected String documentation() {
328: if (documentation == null) {
329: int cnt = options.length();
330: String overviewPath = getOverviewPath();
331: if (overviewPath == null) {
332: // no doc file to be had
333: documentation = "";
334: } else {
335: // read from file
336: try {
337: documentation = readHTMLDocumentation(
338: new FileInputStream(overviewPath),
339: overviewPath);
340: } catch (IOException exc) {
341: documentation = "";
342: env.error(null, "javadoc.File_Read_Error",
343: overviewPath);
344: }
345: }
346: }
347: return documentation;
348: }
349:
350: /**
351: * Return the source position of the entity, or null if
352: * no position is available.
353: */
354: public SourcePosition position() {
355: String path;
356: return ((path = getOverviewPath()) == null) ? null
357: : SourcePositionImpl.make(path, Position.NOPOS, null);
358: }
359: }
|