Added javadoc comments. git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@86 8db76d5a-ed1c-0410-87a9-c151d255dfc7

diff --git a/dev/core/src/com/google/gwt/dev/jjs/ast/js/JsonArray.java b/dev/core/src/com/google/gwt/dev/jjs/ast/js/JsonArray.java
index 75cbe86..36f731a 100644
--- a/dev/core/src/com/google/gwt/dev/jjs/ast/js/JsonArray.java
+++ b/dev/core/src/com/google/gwt/dev/jjs/ast/js/JsonArray.java

@@ -22,6 +22,9 @@
 import com.google.gwt.dev.jjs.ast.JVisitor;
 import com.google.gwt.dev.jjs.ast.Mutator;
 
+/**
+ * A JSON-style list of JS expressions.
+ */
 public class JsonArray extends JExpression {
 
   public HolderList exprs = new HolderList();

diff --git a/dev/core/src/com/google/gwt/dev/jjs/ast/js/JsonObject.java b/dev/core/src/com/google/gwt/dev/jjs/ast/js/JsonObject.java
index 6aa52a2..e514c33 100644
--- a/dev/core/src/com/google/gwt/dev/jjs/ast/js/JsonObject.java
+++ b/dev/core/src/com/google/gwt/dev/jjs/ast/js/JsonObject.java

@@ -26,8 +26,14 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/**
+ * Represents a JS construct that should be emitted as a JSON-style object.
+ */
 public class JsonObject extends JExpression {
 
+  /**
+   * An individual property initializer within a JSON object initializer.
+   */
   public static class JsonPropInit extends JNode {
 
     public final Holder labelExpr = new Holder();

diff --git a/dev/core/src/com/google/gwt/dev/js/JsParserException.java b/dev/core/src/com/google/gwt/dev/js/JsParserException.java
index fd7a7bc..1ea3bed 100644
--- a/dev/core/src/com/google/gwt/dev/js/JsParserException.java
+++ b/dev/core/src/com/google/gwt/dev/js/JsParserException.java

@@ -16,10 +16,13 @@
 package com.google.gwt.dev.js;
 
 /**
- * Thrown due to a JavaScript parser exception.
+ * Indicates inability to parse JavaScript source.
  */
 public class JsParserException extends Exception {
 
+  /**
+   * Represents the location of a parser exception.
+   */
   public static class SourceDetail {
     private final int line;
 

diff --git a/dev/core/src/com/google/gwt/dev/shell/CheckForUpdates.java b/dev/core/src/com/google/gwt/dev/shell/CheckForUpdates.java
index f3022ef..1f9686e 100644
--- a/dev/core/src/com/google/gwt/dev/shell/CheckForUpdates.java
+++ b/dev/core/src/com/google/gwt/dev/shell/CheckForUpdates.java

@@ -45,6 +45,9 @@
  */
 public abstract class CheckForUpdates {
 
+  /**
+   * Abstract the action to take when an update is available.
+   */
   public static interface UpdateAvailableCallback {
     void onUpdateAvailable(String html);
   }

diff --git a/dev/core/src/com/google/gwt/dev/shell/DialogBase.java b/dev/core/src/com/google/gwt/dev/shell/DialogBase.java
index 28ccb3a..7cdbd9f 100644
--- a/dev/core/src/com/google/gwt/dev/shell/DialogBase.java
+++ b/dev/core/src/com/google/gwt/dev/shell/DialogBase.java

@@ -32,6 +32,9 @@
 import org.eclipse.swt.widgets.MessageBox;
 import org.eclipse.swt.widgets.Shell;
 
+/**
+ * Shared boilerplate for dialogs.
+ */
 public abstract class DialogBase extends Dialog implements DisposeListener {
 
   private class Buttons extends GridPanel {

diff --git a/dev/core/src/com/google/gwt/dev/shell/GridPanel.java b/dev/core/src/com/google/gwt/dev/shell/GridPanel.java
index fb06ab7..2a923cf 100644
--- a/dev/core/src/com/google/gwt/dev/shell/GridPanel.java
+++ b/dev/core/src/com/google/gwt/dev/shell/GridPanel.java

@@ -21,6 +21,9 @@
 import org.eclipse.swt.widgets.Composite;
 import org.eclipse.swt.widgets.Control;
 
+/**
+ * Shared boilerplate for grid-style UIs.
+ */
 public class GridPanel extends Composite {
 
   protected static final int FILL = GridData.FILL;

diff --git a/dev/core/src/com/google/gwt/dev/shell/Handle.java b/dev/core/src/com/google/gwt/dev/shell/Handle.java
index cb4ad56..1fb4871 100644
--- a/dev/core/src/com/google/gwt/dev/shell/Handle.java
+++ b/dev/core/src/com/google/gwt/dev/shell/Handle.java

@@ -21,6 +21,9 @@
 import java.util.Iterator;
 import java.util.Vector;
 
+/**
+ * Abstracts the concept of an opaque handle to a JavaScript object.
+ */
 public abstract class Handle {
 
   public static final String HANDLE_CLASS = "com.google.gwt.core.client.JavaScriptObject";

diff --git a/dev/core/src/com/google/gwt/dev/shell/JavaDispatch.java b/dev/core/src/com/google/gwt/dev/shell/JavaDispatch.java
index 1ef43e1..5832c94 100644
--- a/dev/core/src/com/google/gwt/dev/shell/JavaDispatch.java
+++ b/dev/core/src/com/google/gwt/dev/shell/JavaDispatch.java

@@ -18,6 +18,9 @@
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
 
+/**
+ * Abstracts the process of interacting with lazily-bound object manipulation.
+ */
 public interface JavaDispatch {
 
   Field getField(int dispId);

diff --git a/dev/core/src/com/google/gwt/dev/shell/Messages.java b/dev/core/src/com/google/gwt/dev/shell/Messages.java
index b13fc33..85e595b 100644
--- a/dev/core/src/com/google/gwt/dev/shell/Messages.java
+++ b/dev/core/src/com/google/gwt/dev/shell/Messages.java

@@ -21,36 +21,39 @@
 import com.google.gwt.dev.util.msg.Message1StringArray;
 import com.google.gwt.dev.util.msg.Message1ToString;
 
+/**
+ * End-user messages related to the shell.
+ */
 public final class Messages {
 
   public static final Message1String REBIND_RESULT_TYPE_IS_NOT_INSTANTIABLE = new Message1String(
-    TreeLogger.WARN,
-    "Deferred binding result type '$0' is not instantiable; expect subsequent failure");
+      TreeLogger.WARN,
+      "Deferred binding result type '$0' is not instantiable; expect subsequent failure");
 
   public static final Message1ToString TRACE_CHECKING_RULE = new Message1ToString(
-    TreeLogger.DEBUG, "Checking rule $0");
+      TreeLogger.DEBUG, "Checking rule $0");
 
   public static final Message0 TRACE_CONDITION_DID_NOT_MATCH = new Message0(
-    TreeLogger.DEBUG, "Condition was not satisfied");
+      TreeLogger.DEBUG, "Condition was not satisfied");
 
   public static final Message0 TRACE_CONDITION_MATCHED = new Message0(
-    TreeLogger.DEBUG, "Condition was satisfied");
+      TreeLogger.DEBUG, "Condition was satisfied");
 
   public static final Message0 TRACE_RULE_DID_NOT_MATCH = new Message0(
-    TreeLogger.DEBUG, "Rule did not match");
+      TreeLogger.DEBUG, "Rule did not match");
 
   public static final Message0 TRACE_RULE_MATCHED = new Message0(
-    TreeLogger.DEBUG, "Rule was a match and will be used");
+      TreeLogger.DEBUG, "Rule was a match and will be used");
 
   public static final Message1String TRACE_TOPLEVEL_REBIND = new Message1String(
-    TreeLogger.DEBUG, "Rebinding $0");
+      TreeLogger.DEBUG, "Rebinding $0");
 
   public static final Message1String TRACE_TOPLEVEL_REBIND_RESULT = new Message1String(
-    TreeLogger.DEBUG, "Rebind result was $0");
-  
+      TreeLogger.DEBUG, "Rebind result was $0");
+
   public static final Message1StringArray UNABLE_TO_REBIND_DUE_TO_CYCLE_IN_RULES = new Message1StringArray(
-    TreeLogger.WARN,
-    "The deferred binding request failed due to a cycle in the applicable rules: $0");
+      TreeLogger.WARN,
+      "The deferred binding request failed due to a cycle in the applicable rules: $0");
 
   // no instances
   private Messages() {

diff --git a/dev/core/src/com/google/gwt/dev/shell/ModuleSpaceHost.java b/dev/core/src/com/google/gwt/dev/shell/ModuleSpaceHost.java
index 61bbc32..6dd90eb 100644
--- a/dev/core/src/com/google/gwt/dev/shell/ModuleSpaceHost.java
+++ b/dev/core/src/com/google/gwt/dev/shell/ModuleSpaceHost.java

@@ -19,6 +19,12 @@
 import com.google.gwt.core.ext.UnableToCompleteException;
 import com.google.gwt.dev.jdt.RebindOracle;
 
+/**
+ * Defines the contract necessary to host a module space. "Hosting a module
+ * space" refers to supporting an isolated logical arena that can load a GWT
+ * module in hosted mode, execute JavaScript, and so on. The primary exmaple of
+ * this is the GWT shell.
+ */
 public interface ModuleSpaceHost extends RebindOracle {
   String[] getEntryPointTypeNames();
 

diff --git a/dev/core/src/com/google/gwt/dev/shell/ModuleSpacePropertyOracle.java b/dev/core/src/com/google/gwt/dev/shell/ModuleSpacePropertyOracle.java
index 1d89d94..702334b 100644
--- a/dev/core/src/com/google/gwt/dev/shell/ModuleSpacePropertyOracle.java
+++ b/dev/core/src/com/google/gwt/dev/shell/ModuleSpacePropertyOracle.java

@@ -25,6 +25,10 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Implements a {@link PropertyOracle} in terms of a module space, which makes
+ * it possible to execute property providers.
+ */
 public class ModuleSpacePropertyOracle implements PropertyOracle {
 
   private final Properties props;

diff --git a/dev/core/src/com/google/gwt/dev/shell/PlatformSpecific.java b/dev/core/src/com/google/gwt/dev/shell/PlatformSpecific.java
index 74f9033..2f6267e 100644
--- a/dev/core/src/com/google/gwt/dev/shell/PlatformSpecific.java
+++ b/dev/core/src/com/google/gwt/dev/shell/PlatformSpecific.java

@@ -24,17 +24,20 @@
 import java.lang.reflect.Constructor;
 import java.lang.reflect.InvocationTargetException;
 
+/**
+ * Performs platform-specific class selection.
+ */
 public class PlatformSpecific {
 
-  private static final String[] browserClassNames = new String[]{
-    "com.google.gwt.dev.shell.ie.BrowserWidgetIE6",
-    "com.google.gwt.dev.shell.moz.BrowserWidgetMoz",
-    "com.google.gwt.dev.shell.mac.BrowserWidgetSaf"};
+  private static final String[] browserClassNames = new String[] {
+      "com.google.gwt.dev.shell.ie.BrowserWidgetIE6",
+      "com.google.gwt.dev.shell.moz.BrowserWidgetMoz",
+      "com.google.gwt.dev.shell.mac.BrowserWidgetSaf"};
 
-  private static final String[] updaterClassNames = new String[]{
-    "com.google.gwt.dev.shell.ie.CheckForUpdatesIE6",
-    "com.google.gwt.dev.shell.moz.CheckForUpdatesMoz",
-    "com.google.gwt.dev.shell.mac.CheckForUpdatesSaf"};
+  private static final String[] updaterClassNames = new String[] {
+      "com.google.gwt.dev.shell.ie.CheckForUpdatesIE6",
+      "com.google.gwt.dev.shell.moz.CheckForUpdatesMoz",
+      "com.google.gwt.dev.shell.mac.CheckForUpdatesSaf"};
 
   public static BrowserWidget createBrowserWidget(TreeLogger logger,
       Composite parent, BrowserWidgetHost host)
@@ -45,17 +48,17 @@
         Class clazz = null;
         try {
           clazz = Class.forName(browserClassNames[i]);
-          Constructor ctor = clazz.getDeclaredConstructor(new Class[]{
-            Shell.class, BrowserWidgetHost.class});
-          BrowserWidget bw = (BrowserWidget) ctor.newInstance(new Object[]{
-            parent, host});
+          Constructor ctor = clazz.getDeclaredConstructor(new Class[] {
+              Shell.class, BrowserWidgetHost.class});
+          BrowserWidget bw = (BrowserWidget) ctor.newInstance(new Object[] {
+              parent, host});
           return bw;
         } catch (ClassNotFoundException e) {
           caught = e;
         }
       }
       logger.log(TreeLogger.ERROR,
-        "No instantiable browser widget class could be found", caught);
+          "No instantiable browser widget class could be found", caught);
       throw new UnableToCompleteException();
     } catch (SecurityException e) {
       caught = e;
@@ -73,7 +76,7 @@
       caught = e;
     }
     logger.log(TreeLogger.ERROR,
-      "The browser widget class could not be instantiated", caught);
+        "The browser widget class could not be instantiated", caught);
     throw new UnableToCompleteException();
   }
 
@@ -82,9 +85,8 @@
       for (int i = 0; i < updaterClassNames.length; i++) {
         try {
           Class clazz = Class.forName(updaterClassNames[i]);
-          Constructor ctor = clazz.getDeclaredConstructor(new Class[]{});
-          CheckForUpdates checker = (CheckForUpdates) ctor
-            .newInstance(new Object[]{});
+          Constructor ctor = clazz.getDeclaredConstructor(new Class[] {});
+          CheckForUpdates checker = (CheckForUpdates) ctor.newInstance(new Object[] {});
           return checker;
         } catch (ClassNotFoundException e) {
           // keep trying

diff --git a/dev/core/src/com/google/gwt/dev/util/Empty.java b/dev/core/src/com/google/gwt/dev/util/Empty.java
index 7ea0af4..8798ee0 100644
--- a/dev/core/src/com/google/gwt/dev/util/Empty.java
+++ b/dev/core/src/com/google/gwt/dev/util/Empty.java

@@ -15,6 +15,9 @@
  */
 package com.google.gwt.dev.util;
 
+/**
+ * Consolidates preallocated empty arrays for use with <code>toArray()</code>.
+ */
 public class Empty {
 
   public static final String[] STRINGS = new String[0];

diff --git a/dev/core/src/com/google/gwt/dev/util/FileOracleFactory.java b/dev/core/src/com/google/gwt/dev/util/FileOracleFactory.java
index 298a0fd..7c1246b 100644
--- a/dev/core/src/com/google/gwt/dev/util/FileOracleFactory.java
+++ b/dev/core/src/com/google/gwt/dev/util/FileOracleFactory.java

@@ -49,10 +49,11 @@
  * underlying URLClassLoader or file system. However, URLs returned from the
  * FileOracle may become invalid if the contents of the file system change.
  * 
- * Presently, only URLs beginning with* "file:" and "jar:file:" can be inspected
- * to index children. Any other types of URLs will generate a warning. The set
- * of children indexed by "jar:file:" type URLs is fixed at creation time, but
- * the set of children from "file:" type URLs will dynamically query the
+ * Presently, only URLs beginning with <code>file:</code> and
+ * <code>jar:file:</code> can be inspected to index children. Any other types
+ * of URLs will generate a warning. The set of children indexed by
+ * <code>jar:file:</code> type URLs is fixed at creation time, but the set of
+ * children from <code>file:</code> type URLs will dynamically query the
  * underlying file system.
  */
 public class FileOracleFactory {