001: package org.cougaar.tools.javadoc;
002:
003: /*
004: * <copyright>
005: *
006: * Copyright 2001-2004 BBNT Solutions, LLC
007: * under sponsorship of the Defense Advanced Research Projects
008: * Agency (DARPA).
009: *
010: * You can redistribute this software and/or modify it under the
011: * terms of the Cougaar Open Source License as published on the
012: * Cougaar Open Source Website (www.cougaar.org).
013: *
014: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
015: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
016: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
017: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
018: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
019: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
020: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
021: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
022: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
023: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
024: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
025: *
026: * </copyright>
027: */
028:
029: // note that this requires that the tools.jar from jdk be present at compile-time.
030: // basic packages
031: import java.io.IOException;
032: import java.util.ArrayList;
033: import java.util.Collections;
034: import java.util.Iterator;
035: import java.util.List;
036:
037: import com.sun.javadoc.*;
038: import com.sun.tools.doclets.formats.html.*;
039: import com.sun.tools.doclets.internal.toolkit.*;
040: import com.sun.tools.doclets.internal.toolkit.util.*;
041:
042: /**
043: * An extension of the "Standard" Doclet for generating files which
044: * additionally outputs a list of parameters (usually System Properties)
045: * that control behavior of various classes and methods.
046: *
047: * usage: javadoc -doclet org.cougaar.tools.javadoc.Cougaar foo.java ...
048: *
049: * @property org.cougaar.tools.javadoc.dummy An ignored property mentioned
050: * here only to illustrate the sort thing found by this doclet.
051: **/
052:
053: // javac -d . -g -classpath /usr/local/java/jdk/lib/tools.jar:. Cougaar.java
054: public class CougaarDoclet extends HtmlDoclet {
055:
056: /** just like Standard except creates a Cougaar instance instead of
057: * a Standard Doclet instance.
058: **/
059: public static boolean start(RootDoc root) {
060: CougaarDoclet doclet = new CougaarDoclet();
061: return doclet.start(doclet, root);
062: }
063:
064: protected void generateOtherFiles(RootDoc root, ClassTree classtree)
065: throws Exception {
066: super .generateOtherFiles(root, classtree);
067:
068: generateParameterList(root);
069: }
070:
071: protected void generateParameterList(RootDoc root) throws Exception {
072: ParameterListWriter packgen;
073: packgen = new ParameterListWriter(
074: (ConfigurationImpl) configuration,
075: ParameterListWriter.PARAMETERFILE);
076: packgen.generateParameterListFile(root);
077: packgen.close();
078: }
079:
080: private static class ParameterListWriter extends
081: com.sun.tools.doclets.formats.html.HtmlDocletWriter {
082: public final static String PARAMETERFILE = "Parameters.html";
083:
084: public ParameterListWriter(ConfigurationImpl cs, String filename)
085: throws IOException {
086: super (cs, filename);
087: this .cs = cs;
088: }
089:
090: protected Configuration cs;
091:
092: public Configuration configuration() {
093: return cs;
094: }
095:
096: protected void generateParameterListFile(RootDoc root) {
097: buildParameterInfo(root);
098:
099: // Note that this line includes some SCRIPT tags that the default Java HTML renderer
100: // can't handle. Ugly.
101: printFramesetHeader("Parameter List");
102: println("Catalog of System Properties");
103: p();
104:
105: ul();
106: int i = 0;
107: for (Iterator it = parameters.iterator(); it.hasNext(); i++) {
108: Tuple t = (Tuple) it.next();
109: //String text = t.tag.text();
110: Doc d = t.doc;
111: String param = t.param; // parse out param from text
112: String info = t.text; // remainder of text
113: li();
114: bold();
115: println(param);
116: boldEnd();
117: println(info);
118: print(" (See ");
119: if (d instanceof ClassDoc) {
120: print("class ");
121: printLink(new LinkInfoImpl(i, (ClassDoc) d));
122: } else if (d instanceof MemberDoc) {
123: MemberDoc md = (MemberDoc) d;
124: print(md.qualifiedName());
125: print(" in ");
126: printLink(new LinkInfoImpl(i, (ClassDoc) md
127: .containingClass()));
128: }
129: println(")");
130: //liEnd();
131: }
132: ulEnd();
133:
134: printBodyHtmlEnd();
135: }
136:
137: private List<Tuple> parameters = new ArrayList<Tuple>();
138:
139: @SuppressWarnings("unchecked")
140: private void buildParameterInfo(RootDoc root) {
141: ClassDoc[] classes = root.classes();
142: for (int i = 0; i < classes.length; i++) {
143: ClassDoc cd = classes[i];
144: collect(cd);
145: collect(cd.fields());
146: collect(cd.methods());
147: collect(cd.constructors());
148: }
149: Collections.sort(parameters);
150: }
151:
152: private void collect(Doc doc) {
153: Tag[] pts = doc.tags("property");
154: for (int i = 0; i < pts.length; i++) {
155: parameters.add(new Tuple(doc, pts[i]));
156: }
157: }
158:
159: private void collect(Doc[] docs) {
160: for (int i = 0; i < docs.length; i++) {
161: collect(docs[i]);
162: }
163: }
164: }
165:
166: private static class Tuple implements Comparable {
167: public Doc doc;
168: public Tag tag;
169: public String param = null;
170: public String text = null;
171: public final static String white = " \t\n\r"; // whitespace chars
172:
173: public Tuple(Doc doc, Tag tag) {
174: this .doc = doc;
175: this .tag = tag;
176:
177: String tt = tag.text();
178: int i;
179: int l = tt.length();
180: int state = 0; // what are we looking for?
181: int p0 = -1, p1 = -1, t0 = -1;
182:
183: // scan the tag text
184: for (i = 0; i < l; i++) {
185: char c = tt.charAt(i);
186: boolean isWhite = (white.indexOf(c) >= 0);
187: switch (state) {
188: case 0: // looking for param start
189: if (!isWhite) {
190: p0 = i;
191: state = 1;
192: }
193: break;
194: case 1: // looking for param end
195: if (isWhite) {
196: p1 = i;
197: state = 2;
198: }
199: break;
200: case 2: // looking for text start
201: if (!isWhite) {
202: t0 = i;
203: state = 3;
204: }
205: break;
206: default: // shouldn't get here
207: break;
208: }
209: if (state == 3)
210: break;
211: }
212:
213: if (t0 >= 0) {
214: param = tt.substring(p0, p1);
215: text = tt.substring(t0);
216: } else {
217: }
218: }
219:
220: public int compareTo(Object o) {
221: if (!(o instanceof Tuple))
222: return -1;
223: Tuple t = (Tuple) o;
224: int v = param.compareTo(t.param);
225: if (v != 0)
226: return v;
227:
228: return doc.compareTo(t.doc);
229: }
230: }
231: }
|