Implements a new Doclet to generate .wiki output for the JRE emulation documentation. This Doclet generates a RefJreEmulation.wiki, which can then be imported into the code site svn to update the JRE emulation doc. This was created to replace the existing Doclet that produces HTML documentation for the JRE emul types.
Patch by: kplatfoot
Review by: me
git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@1815 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/build-tools/doctool/src/com/google/doctool/JreDocTool.java b/build-tools/doctool/src/com/google/doctool/JreDocTool.java
new file mode 100644
index 0000000..d98b9a2
--- /dev/null
+++ b/build-tools/doctool/src/com/google/doctool/JreDocTool.java
@@ -0,0 +1,171 @@
+/*
+ * Copyright 2008 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+package com.google.doctool;
+
+import com.google.doctool.custom.WikiDoclet;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Uses the Javadoc tool to produce wiki output documenting the JRE emulation
+ * classes in GWT.
+ */
+public class JreDocTool {
+
+ public static void main(String[] args) {
+ JreDocToolFactory factory = new JreDocToolFactory();
+ String arg;
+
+ for (int i = 0; i < args.length; i++) {
+ if (tryParseFlag(args, i, "-help")) {
+ printHelp();
+ return;
+ } else if (null != (arg = tryParseArg(args, i, "-classpath"))) {
+ i++;
+ factory.setClasspath(arg);
+ } else if (null != (arg = tryParseArg(args, i, "-out"))) {
+ i++;
+ factory.setOutputFile(arg);
+ } else if (null != (arg = tryParseArg(args, i, "-packages"))) {
+ i++;
+ factory.setPackages(arg);
+ } else if (null != (arg = tryParseArg(args, i, "-sourcepath"))) {
+ i++;
+ factory.setSourcepath(arg);
+ } else if (null != (arg = tryParseArg(args, i, "-header"))) {
+ i++;
+ factory.setHeaderFile(arg);
+ }
+ }
+
+ JreDocTool docTool = factory.create(System.err);
+ if (docTool != null) {
+ docTool.process();
+ }
+ }
+
+ /**
+ * Prints help for using JreDocTool.
+ */
+ private static void printHelp() {
+ String s = "";
+ s += "JreDocTool\n";
+ s += " Creates wiki format member listing from Java source";
+ s += " for emulated JRE classes.\n";
+ s += "\n";
+ s += "Required arguments:\n";
+ s += " -classpath\n";
+ s += " The path to find imported classes for this doc set\n";
+ s += " -sourcepath\n";
+ s += " The path to find Java source for this doc set\n";
+ s += " -out\n";
+ s += " The path and filename of the wiki output\n";
+ s += " -packages\n";
+ s += " A semicolon-separated list of fully-qualified package names\n";
+ s += "\n";
+ s += "Optional arguments:\n";
+ s += " -header\n";
+ s += " The path and filename of the content to use at the top of the";
+ s += " output wiki file\n";
+ System.out.println(s);
+ }
+
+ /**
+ * Parse a flag with a argument.
+ */
+ private static String tryParseArg(String[] args, int i, String name) {
+ if (i < args.length) {
+ if (args[i].equals(name)) {
+ if (i + 1 < args.length) {
+ String arg = args[i + 1];
+ if (arg.startsWith("-")) {
+ System.out.println("Warning: arg to " + name
+ + " looks more like a flag: " + arg);
+ }
+ return arg;
+ } else {
+ throw new IllegalArgumentException("Expecting an argument after "
+ + name);
+ }
+ }
+ }
+ return null;
+ }
+
+ /**
+ * Parse just a flag with no subsequent argument.
+ */
+ private static boolean tryParseFlag(String[] args, int i, String name) {
+ if (i < args.length) {
+ if (args[i].equals(name)) {
+ return true;
+ }
+ }
+ return false;
+ }
+
+ private String classpath;
+
+ private String headerFile;
+
+ private String outputFile;
+
+ private String packages;
+
+ private String sourcepath;
+
+ JreDocTool(String classpath, String outputFile, String packages,
+ String sourcepath, String headerFile) {
+ this.classpath = classpath;
+ this.outputFile = outputFile;
+ this.packages = packages;
+ this.sourcepath = sourcepath;
+ this.headerFile = headerFile;
+ }
+
+ private void process() {
+ List<String> args = new ArrayList<String>();
+
+ args.add("-public");
+
+ args.add("-quiet");
+
+ args.add("-source");
+ args.add("1.5");
+
+ args.add("-doclet");
+ args.add(WikiDoclet.class.getName());
+
+ args.add("-classpath");
+ args.add(this.classpath);
+
+ args.add("-wkout");
+ args.add(this.outputFile);
+
+ args.add("-sourcepath");
+ args.add(this.sourcepath);
+
+ args.add("-wkhead");
+ args.add(this.headerFile);
+
+ args.addAll(Arrays.asList(this.packages.split(";")));
+
+ com.sun.tools.javadoc.Main.execute(args.toArray(new String[0]));
+ }
+}
diff --git a/build-tools/doctool/src/com/google/doctool/JreDocToolFactory.java b/build-tools/doctool/src/com/google/doctool/JreDocToolFactory.java
new file mode 100644
index 0000000..7704f96
--- /dev/null
+++ b/build-tools/doctool/src/com/google/doctool/JreDocToolFactory.java
@@ -0,0 +1,80 @@
+/*
+ * Copyright 2008 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+package com.google.doctool;
+
+import java.io.PrintStream;
+
+/**
+ * Supports two-phase creation of {@link JreDocTool} objects.
+ */
+public class JreDocToolFactory {
+
+ private String classpath;
+
+ private String headerFile;
+
+ private String outputFile;
+
+ private String packages;
+
+ private String sourcepath;
+
+ public JreDocTool create(PrintStream err) {
+ if (this.classpath == null) {
+ err.println("You must specify the -classpath");
+ return null;
+ }
+
+ if (this.outputFile == null) {
+ err.println("You must specify the output file (-out)");
+ return null;
+ }
+
+ if (this.packages == null) {
+ err.println("You must specify the -packages");
+ return null;
+ }
+
+ if (this.sourcepath == null) {
+ err.println("You must specify the -sourcepath");
+ return null;
+ }
+
+ return new JreDocTool(classpath, outputFile, packages, sourcepath,
+ headerFile);
+ }
+
+ public void setClasspath(String classpath) {
+ this.classpath = classpath;
+ }
+
+ public void setHeaderFile(String headerFile) {
+ this.headerFile = headerFile;
+ }
+
+ public void setOutputFile(String outputFile) {
+ this.outputFile = outputFile;
+ }
+
+ public void setPackages(String packages) {
+ this.packages = packages;
+ }
+
+ public void setSourcepath(String sourcePath) {
+ this.sourcepath = sourcePath;
+ }
+}
diff --git a/build-tools/doctool/src/com/google/doctool/custom/WikiDoclet.java b/build-tools/doctool/src/com/google/doctool/custom/WikiDoclet.java
new file mode 100644
index 0000000..db0f078
--- /dev/null
+++ b/build-tools/doctool/src/com/google/doctool/custom/WikiDoclet.java
@@ -0,0 +1,169 @@
+/*
+ * Copyright 2008 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+package com.google.doctool.custom;
+
+import com.sun.javadoc.ClassDoc;
+import com.sun.javadoc.DocErrorReporter;
+import com.sun.javadoc.ExecutableMemberDoc;
+import com.sun.javadoc.PackageDoc;
+import com.sun.javadoc.RootDoc;
+
+import java.io.File;
+import java.io.FileReader;
+import java.io.FileWriter;
+import java.io.IOException;
+import java.io.OutputStreamWriter;
+import java.io.PrintWriter;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collection;
+import java.util.Comparator;
+import java.util.Iterator;
+
+/**
+ * A doclet for using producing wiki output listing the specified classes and
+ * their methods and constructors.
+ */
+public class WikiDoclet {
+
+ private static final String OPT_WKHEADER = "-wkhead";
+ private static final String OPT_WKOUT = "-wkout";
+ private static final String JAVADOC_URL = "http://java.sun.com/j2se/1.5.0/docs/api/";
+
+ private static WikiDoclet sWikiDoclet;
+
+ public static int optionLength(String option) {
+ if (option.equals(OPT_WKOUT)) {
+ return 2;
+ }
+ if (option.equals(OPT_WKHEADER)) {
+ return 2;
+ }
+
+ return 0;
+ }
+
+ public static boolean start(RootDoc root) {
+ getDoclet().process(root);
+ return true;
+ }
+
+ public static boolean validOptions(String[][] options,
+ DocErrorReporter reporter) {
+ return getDoclet().analyzeOptions(options, reporter);
+ }
+
+ private static WikiDoclet getDoclet() {
+ if (sWikiDoclet == null) {
+ sWikiDoclet = new WikiDoclet();
+ }
+ return sWikiDoclet;
+ }
+
+ private String headerFile;
+
+ private String outputFile;
+
+ private boolean analyzeOptions(String[][] options, DocErrorReporter reporter) {
+ for (int i = 0; i < options.length; i++) {
+ if (options[i][0] == OPT_WKOUT) {
+ outputFile = options[i][1];
+ } else if (options[i][0] == OPT_WKHEADER) {
+ headerFile = options[i][1];
+ }
+ }
+
+ if (outputFile == null) {
+ reporter.printError("You must specify an output path/filename with "
+ + OPT_WKOUT);
+ return false;
+ }
+
+ return true;
+ }
+
+ private String createMemberList(Collection<ExecutableMemberDoc> members) {
+ StringBuffer buffer = new StringBuffer();
+ Iterator<ExecutableMemberDoc> iter = members.iterator();
+ while (iter.hasNext()) {
+ ExecutableMemberDoc member = iter.next();
+ buffer.append(member.name() + member.flatSignature());
+ if (iter.hasNext()) {
+ buffer.append(", ");
+ }
+ }
+ return buffer.toString();
+ }
+
+ private void importHeader(OutputStreamWriter writer) throws IOException {
+ FileReader fr = new FileReader(headerFile);
+
+ char[] cbuf = new char[4096];
+ int len;
+ while ((len = fr.read(cbuf)) != -1) {
+ writer.write(cbuf, 0, len);
+ }
+
+ fr.close();
+ }
+
+ private void process(RootDoc root) {
+ try {
+ File outFile = new File(outputFile);
+ outFile.getParentFile().mkdirs();
+ FileWriter fw = new FileWriter(outFile);
+ PrintWriter pw = new PrintWriter(fw, true);
+
+ if (headerFile != null) {
+ importHeader(fw);
+ }
+
+ for (PackageDoc pack : root.specifiedPackages()) {
+ pw.println("==Package " + pack.name() + "==\n");
+
+ String packURL = JAVADOC_URL + pack.name().replace(".", "/") + "/";
+
+ // Sort the classes alphabetically
+ ClassDoc[] classes = pack.allClasses(true);
+ Arrays.sort(classes, new Comparator<ClassDoc>() {
+ public int compare(ClassDoc arg0, ClassDoc arg1) {
+ return arg0.name().compareTo(arg1.name());
+ }
+ });
+
+ for (ClassDoc cls : classes) {
+ // Each class links to Sun's main JavaDoc (brackets indicate wiki
+ // link)
+ pw.format("[%s%s.html %s]\n", packURL, cls.name(), cls.name());
+
+ // Print out all constructors and methods
+ Collection<ExecutableMemberDoc> members = new ArrayList<ExecutableMemberDoc>();
+ members.addAll(Arrays.asList(cls.constructors(true)));
+ members.addAll(Arrays.asList(cls.methods(true)));
+
+ pw.print(" " + createMemberList(members));
+
+ pw.print("\n\n");
+ }
+ }
+ pw.close();
+
+ } catch (IOException e) {
+ throw new RuntimeException(e);
+ }
+ }
+}
diff --git a/doc/build.xml b/doc/build.xml
index a79ba55..ece64a1 100644
--- a/doc/build.xml
+++ b/doc/build.xml
@@ -10,6 +10,7 @@
<property.ensure name="gwt.dev.jar" location="${gwt.build.lib}/gwt-dev-linux.jar" />
<property name="USER_PKGS" value="com.google.gwt.core.client;com.google.gwt.core.ext;com.google.gwt.core.ext.typeinfo;com.google.gwt.i18n.client;com.google.gwt.json.client;com.google.gwt.junit.client;com.google.gwt.user.client;com.google.gwt.user.client.rpc;com.google.gwt.user.client.ui;com.google.gwt.user.server.rpc;com.google.gwt.xml.client;com.google.gwt.http.client;com.google.gwt.junit.viewer.client" />
+ <property name="LANG_PKGS" value="java.lang;java.lang.annotation;java.util;java.io" />
<!--
*** Note that if the USER_SOURCE_PATH paths are updated,
@@ -84,5 +85,33 @@
</outofdate>
</target>
- <target name="build" depends="javadoc" />
+ <target name="wiki-lang">
+ <outofdate>
+ <sourcefiles>
+ <fileset file="./src/RefJreHeader.wiki" />
+ <fileset dir="${gwt.root}/user/super/com/google/gwt/emul">
+ <include name="**/*.java" />
+ </fileset>
+ </sourcefiles>
+ <targetfiles>
+ <pathelement path="${project.build}/wiki/RefJreEmulation.wiki" />
+ </targetfiles>
+ <sequential>
+ <java classpathref="DOC_PATH" classname="com.google.doctool.JreDocTool" fork="yes" failonerror="true">
+ <arg value="-out" />
+ <arg value="${project.build}/wiki/RefJreEmulation.wiki" />
+ <arg value="-header" />
+ <arg value="./src/RefJreHeader.wiki" />
+ <arg value="-classpath" />
+ <arg pathref="USER_CLASS_PATH" />
+ <arg value="-sourcepath" />
+ <arg path="${gwt.root}/user/super/com/google/gwt/emul" />
+ <arg value="-packages" />
+ <arg value="${LANG_PKGS}" />
+ </java>
+ </sequential>
+ </outofdate>
+ </target>
+
+ <target name="build" depends="javadoc, wiki-lang" />
</project>
diff --git a/doc/src/RefJreHeader.wiki b/doc/src/RefJreHeader.wiki
new file mode 100644
index 0000000..f264043
--- /dev/null
+++ b/doc/src/RefJreHeader.wiki
@@ -0,0 +1,5 @@
+#summary JRE Emulation Library
+
+=JRE Emulation=
+
+Google Web Toolkit includes a library that emulates a subset of the Java runtime library. The list below shows the set of JRE types and methods that GWT can translate automatically. Note that in some cases, only a subset of methods is supported for a given type.
