Use Java to generate the list of packages for javadoc
Review at http://gwt-code-reviews.appspot.com/980803
Review by: jat@google.com
git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@9040 8db76d5a-ed1c-0410-87a9-c151d255dfc7
diff --git a/build-tools/doctool/src/com/google/doctool/custom/FindPackages.java b/build-tools/doctool/src/com/google/doctool/custom/FindPackages.java
new file mode 100644
index 0000000..e37046e
--- /dev/null
+++ b/build-tools/doctool/src/com/google/doctool/custom/FindPackages.java
@@ -0,0 +1,212 @@
+/*
+ * Copyright 2010 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 java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.PrintStream;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+import java.util.regex.Pattern;
+
+/**
+ * Used by trunk/doc/build.xml to generate the packages.properties file.
+ */
+public class FindPackages {
+
+ /**
+ * A list of regular expressions to exclude. For readability, a '.' character
+ * will be interpreted literally (i.e., it will be transformed into '\.'
+ * before being compiled). Add rules here as needed.
+ */
+ private static final String[] EXCLUSIONS = {
+ "^com.example.", "^com.google.gwt.dev(.|$)", "^com.google.gwt.emul.",
+ "^com.google.gwt.examples(.|$)", "^com.google.gwt.i18n.server(.|$)",
+ "^com.google.gwt.i18n.tools", "^com.google.gwt.lang",
+ "^com.google.gwt.junit(.|$)", "^com.google.gwt.resources.css(.|$)",
+ "^com.google.gwt.resources.rg(.|$)",
+ "^com.google.gwt.rpc.client.ast(.|$)", "^com.google.gwt.soyc(.|$)",
+ "^com.google.gwt.validation(.|$)",
+ "^com.google.gwt.user.client.rpc.core.", "^javax.", "^junit.", "^org.",
+ ".impl(.|$)", ".rebind(.|$)"
+ };
+
+ /**
+ * A list of emulated packages under java.lang, to be emitted as
+ * the LANG_PKGS property. Add packages here as needed.
+ */
+ private static final String[] LANG_PKGS = {
+ "java.lang", "java.lang.annotation", "java.io", "java.sql", "java.util"};
+
+ /**
+ * User packages to include, regardless of exclusions. Add packages here
+ * as needed.
+ */
+ private static final String[] PACKAGE_WHITELIST = {
+ "com.google.gwt.i18n.rebind.format", "com.google.gwt.i18n.rebind.keygen",
+ "com.google.gwt.junit.client"};
+
+ /**
+ * Source directories under the root directory to traverse. Add directories
+ * here as needed.
+ */
+ private static final String[] SOURCE_DIRS = {
+ "user/src", "user/javadoc", "user/super", "dev/core/src",
+ "dev/core/super"};
+
+ /**
+ * Individual user classes to include, even if the rest of their packages
+ * is not included. Add classes here as needed.
+ */
+ private static final String[] USER_CLASSES = {
+ "user/src/com/google/gwt/junit/tools/GWTTestSuite.java",
+ "user/src/com/google/gwt/i18n/rebind/LocaleUtils.java",
+ "user/src/com/google/gwt/i18n/server/GwtLocaleFactoryImpl.java",
+ "user/src/com/google/gwt/i18n/server/GwtLocaleImpl.java"};
+
+ private static Pattern exclusions;
+ static {
+ StringBuilder sb = new StringBuilder();
+ for (int i = 0; i < EXCLUSIONS.length; i++) {
+ String ex = EXCLUSIONS[i];
+ ex = ex.replace(".", "\\.");
+ if (i < EXCLUSIONS.length - 1) {
+ sb.append(ex + "|");
+ } else {
+ sb.append(ex);
+ }
+ }
+ exclusions = Pattern.compile(sb.toString());
+ }
+
+ public static void main(String[] args) {
+ if (args.length < 1) {
+ System.err.println("usage: java com.google.doctool.custom.FindPackages <root dir>");
+ System.exit(1);
+ }
+
+ try {
+ File rootDir = new File(args[0]);
+ // Output to <root>/doc/packages.properties
+ File build = new File(rootDir, "build");
+ File buildOut = new File(build, "out");
+ File outFile = new File(buildOut, "packages.properties");
+ PrintStream out = new PrintStream(new FileOutputStream(outFile), false, "UTF-8");
+
+ out.println("# THIS FILE IS AUTOMATICALLY GENERATED BY");
+ out.println("# com.google.doctool.custom.FindPackages");
+ out.println("#");
+ out.println("# This file contains all of the user javadoc packages");
+ out.println("#");
+ out.println("# JRE emulation packages");
+ out.println("LANG_PKGS=\\");
+ for (int i = 0; i < LANG_PKGS.length; i++) {
+ if (i < LANG_PKGS.length - 1) {
+ out.println(LANG_PKGS[i] + ";\\");
+ } else {
+ out.println(LANG_PKGS[i]);
+ }
+ }
+ out.println("# The last package should not have a trailing semicolon");
+ out.println("");
+ out.println("# Individual classes to include when we don't want to include an entire package");
+ out.println("USER_CLASSES=\\");
+ for (int i = 0; i < USER_CLASSES.length; i++) {
+ if (i < USER_CLASSES.length - 1) {
+ out.println("${gwt.root}/" + USER_CLASSES[i] + ":\\");
+ } else {
+ out.println("${gwt.root}/" + USER_CLASSES[i]);
+ }
+ }
+ out.println("");
+ out.println("# Packages to include");
+ out.println("USER_PKGS=\\");
+
+ Set<String> packages = new HashSet<String>();
+ for (String dir : SOURCE_DIRS) {
+ File f = new File(rootDir, dir);
+ findPackages(f, null, packages);
+ }
+ for (String s : PACKAGE_WHITELIST) {
+ packages.add(s);
+ }
+
+ ArrayList<String> packageList = new ArrayList<String>(packages);
+ Collections.sort(packageList);
+
+ for (int i = 0; i < packages.size(); i++) {
+ if (i < packages.size() - 1) {
+ out.println(packageList.get(i) + ";\\");
+ } else {
+ out.println(packageList.get(i));
+ }
+ }
+ out.println("# The last package should not have a trailing semicolon");
+ out.close();
+ } catch (IOException e) {
+ System.err.println("Got I/O Exception: " + e);
+ System.exit(2);
+ }
+ }
+
+ /**
+ * Recursively find java packages under the given directory.
+ *
+ * @param dir the root directory
+ * @param packageName the package name so far
+ * @param packages the set of packages to output to
+ */
+ private static void findPackages(File dir, String packageName,
+ Set<String> packages) {
+ File[] files = dir.listFiles();
+ if (files == null) {
+ return;
+ }
+ boolean hasJava = false;
+ for (File f : files) {
+ String name = f.getName();
+ if (f.isDirectory()) {
+ String subPackage = packageName == null ? name : packageName + "."
+ + name;
+ findPackages(f, subPackage, packages);
+ } else {
+ // If there is a java file in the directory, include the package
+ // for further processing.
+ if (!hasJava && name.endsWith(".java")) {
+ hasJava = true;
+ }
+ }
+ }
+
+ // Clean up translatable/ and super/ paths
+ // Emit the package name if not excluded
+ if (hasJava && packageName != null) {
+ int index;
+ if ((index = packageName.indexOf(".translatable.")) != -1) {
+ packageName = packageName.substring(index + 14);
+ }
+ if ((index = packageName.indexOf(".super.")) != -1) {
+ packageName = packageName.substring(index + 7);
+ }
+ if (!exclusions.matcher(packageName).find()) {
+ packages.add(packageName);
+ }
+ }
+ }
+}
diff --git a/doc/build.xml b/doc/build.xml
index 20c94c1..d318f11 100644
--- a/doc/build.xml
+++ b/doc/build.xml
@@ -23,13 +23,14 @@
</path>
<path id="USER_CLASS_PATH">
- <pathelement location="${gwt.user.jar}" />
<pathelement location="${gwt.dev.jar}" />
- <pathelement location="${gwt.tools.lib}/junit/junit-3.8.1.jar" />
+ <pathelement location="${gwt.user.jar}" />
<pathelement location="${gwt.tools}/redist/json/r2_20080312/json-1.5.jar" />
+ <pathelement location="${gwt.tools.lib}/junit/junit-3.8.1.jar" />
<pathelement location="${gwt.tools.lib}/javax/validation/validation-api-1.0.0.GA.jar" />
- <pathelement location="${gwt.tools.lib}/javax/validation/validation-api-1.0.0.GA-sources.jar" />
+ <pathelement location="${gwt.tools.lib}/javax/validation/validation-api-1.0.0.GA-sources.jar" />
<pathelement location="${gwt.tools.lib}/jfreechart/jfreechart-1.0.3.jar" />
+ <pathelement location="${gwt.tools.lib}/selenium/selenium-java-client-driver.jar" />
</path>
<path id="DOC_PATH">
@@ -75,13 +76,16 @@
</target>
<!-- Really rebuild the javadoc -->
- <target name="makeJavadoc">
- <exec executable="${gwt.root}/doc/find-packages.sh" />
- <property file="packages.properties" />
+ <target name="makeJavadoc">
+ <java classpathref="DOC_PATH" classname="com.google.doctool.custom.FindPackages" fork="yes" failonerror="true">
+ <arg value="${gwt.root}" />
+ </java>
+ <property file="${gwt.root}/build/out/packages.properties" />
<java classpathref="DOC_PATH" classname="com.google.doctool.custom.GWTJavaDoclet" fork="yes" failonerror="true">
<jvmarg value="-Xmx1024m" />
<arg value="-quiet" />
<arg value="-notimestamp" />
+ <arg value="-use" />
<arg value="-source" />
<arg value="1.5" />
<arg value="-windowtitle" />
@@ -97,8 +101,9 @@
<arg value="-linkoffline" />
<arg value="http://download.oracle.com/javaee/6/api/" />
<arg value="validation-package-list" />
- <arg value="-link" />
+ <arg value="-linkoffline" />
<arg value="http://www.json.org/javadoc" />
+ <arg value="json-package-list" />
<arg value="-classpath" />
<arg pathref="USER_CLASS_PATH" />
<arg value="-sourcepath" />
@@ -122,8 +127,10 @@
</targetfiles>
<sequential>
<echo>Building JRE emulation EZT</echo>
- <exec executable="${gwt.root}/doc/find-packages.sh" />
- <property file="packages.properties" />
+ <java classpathref="DOC_PATH" classname="com.google.doctool.custom.FindPackages" fork="yes" failonerror="true">
+ <arg value="${gwt.root}" />
+ </java>
+ <property file="${gwt.root}/build/out/packages.properties" />
<java classpathref="DOC_PATH" classname="com.google.doctool.JreDocTool" fork="yes" failonerror="true">
<arg value="-out" />
<arg value="${project.build}/emul-ezt/fragment.html" />
diff --git a/doc/find-packages.sh b/doc/find-packages.sh
deleted file mode 100755
index 9383271..0000000
--- a/doc/find-packages.sh
+++ /dev/null
@@ -1,93 +0,0 @@
-#!/bin/bash
-set noglob
-
-OUTFILE=packages.properties
-TMPFILE=/tmp/gwt-javadoc-packages$$
-
-# Regex patterns to exclude from the list of packages
-EXCLUSIONS="\
-^com\.example\.|\
-^com\.google\.gwt\.dev(\.|$)|\
-^com\.google\.gwt\.emul\.|\
-^com\.google\.gwt\.examples(\.|$)|\
-^com\.google\.gwt\.i18n\.server(\.|$)|\
-^com\.google\.gwt\.i18n\.tools|\
-^com\.google\.gwt\.lang|\
-^com\.google\.gwt\.junit(\.|$)|\
-^com\.google\.gwt\.resources\.css(\.|$)|\
-^com\.google\.gwt\.resources\.rg(\.|$)|\
-^com\.google\.gwt\.rpc\.client\.ast(\.|$)|\
-^com\.google\.gwt\.soyc(\.|$)|\
-^com\.google\.gwt\.validation(.|$)|\
-^com\.google\.gwt\.user\.client\.rpc\.core\.|\
-^javax\.|\
-^junit\.|\
-^org\.|\
-\.impl(\.|$)|\
-\.rebind(\.|$)"
-
-# Generate the packages.properties file
-# Changes to LANG_PKGS and USER_CLASSES go here
-# Note that line continuation backslashes must be escaped
-cat > ${OUTFILE} <<EOF
-# THIS FILE IS AUTOMATICALLY GENERATED
-#
-# This file contains all of the user javadoc packages
-#
-# JRE emulation packages
-LANG_PKGS=\\
-java.lang;\\
-java.lang.annotation;\\
-java.io;\\
-java.sql;\\
-java.util
-# The last package should not have a trailing semicolon
-
-# Individual classes to include when we don't want to include an entire package
-USER_CLASSES=\\
-\${gwt.root}/user/src/com/google/gwt/junit/tools/GWTTestSuite.java:\\
-\${gwt.root}/user/src/com/google/gwt/i18n/rebind/LocaleUtils.java:\\
-\${gwt.root}/user/src/com/google/gwt/i18n/server/GwtLocaleFactoryImpl.java:\\
-\${gwt.root}/user/src/com/google/gwt/i18n/server/GwtLocaleImpl.java
-
-# Packages to include
-USER_PKGS=\\
-EOF
-
-rm -f ${TMPFILE}
-
-# Create a list of all packages with at least one Java source file
-# List all source files
-for dir in ../user/src ../user/javadoc ../user/super ../dev/core/src ../dev/core/super
-do
-(cd ${dir}; find . -name '*.java') >> ${TMPFILE}
-done
-
-cat ${TMPFILE} | \
-# Remove source file names
-sed 's@/[-A-Za-z0-9_]*\.java$@@'| \
-# Removce initial './'
-sed s@^\./@@ | \
-# Remove .../super/ and .../translatable prefixes
-sed s@^.*/super/@@ | \
-sed s@^.*/translatable/@@ | \
-# Change slashes to dots
-sed s@/@.@g | \
-# Remove excluded patters
-egrep -v ${EXCLUSIONS} > ${TMPFILE}-2
-mv ${TMPFILE}-2 ${TMPFILE}
-
-# Re-add whitelisted packages that would otherwise be excluded
-echo com.google.gwt.i18n.rebind.format >> ${TMPFILE}
-echo com.google.gwt.i18n.rebind.keygen >> ${TMPFILE}
-echo com.google.gwt.junit.client >> ${TMPFILE}
-
-# Sort, uniqify, and add ';\' to each line except the last
-cat ${TMPFILE} | \
-sort | \
-uniq | \
-sed '$q;s@$@;\\@' >> ${OUTFILE}
-echo '# The last package should not have a trailing semicolon' >> ${OUTFILE}
-
-# Clean up
-rm -f ${TMPFILE}
diff --git a/user/src/com/google/gwt/event/logical/shared/ValueChangeEvent.java b/user/src/com/google/gwt/event/logical/shared/ValueChangeEvent.java
index 551063d..d3c9e86 100644
--- a/user/src/com/google/gwt/event/logical/shared/ValueChangeEvent.java
+++ b/user/src/com/google/gwt/event/logical/shared/ValueChangeEvent.java
@@ -33,7 +33,7 @@
* Fires a value change event on all registered handlers in the handler
* manager. If no such handlers exist, this method will do nothing.
*
- * @param <I> the old value type
+ * @param <T> the old value type
* @param source the source of the handlers
* @param value the value
*/
