Added javadoc and removed @throws that made checkstyle barf git-svn-id: https://google-web-toolkit.googlecode.com/svn/trunk@76 8db76d5a-ed1c-0410-87a9-c151d255dfc7

diff --git a/dev/core/src/com/google/gwt/core/ext/Generator.java b/dev/core/src/com/google/gwt/core/ext/Generator.java
index 39fea20..1e5e470 100644
--- a/dev/core/src/com/google/gwt/core/ext/Generator.java
+++ b/dev/core/src/com/google/gwt/core/ext/Generator.java

@@ -23,8 +23,9 @@
 
   /**
    * Escapes string content to be a valid string literal.
-   * @return an escaped version of <code>unescaped</code>, suitable for being 
-   * enclosed in double quotes in Java source
+   * 
+   * @return an escaped version of <code>unescaped</code>, suitable for being
+   *         enclosed in double quotes in Java source
    */
   public static String escape(String unescaped) {
     int extra = 0;
@@ -72,13 +73,14 @@
   }
 
   /**
-   * Generate a default constructible subclass of the requested type.
+   * Generate a default constructible subclass of the requested type. The
+   * generator throws <code>UnableToCompleteException</code> if for any reason
+   * it cannot provide a substitute class
    * 
    * @return the name of a subclass to substitute for the requested class, or
    *         return <code>null</code> to cause the requested type itself to be
    *         used
-   * @throws UnableToCompleteException if for any reason the generator cannot
-   *           provide a substitute class
+   * 
    */
   public abstract String generate(TreeLogger logger, GeneratorContext context,
       String typeName) throws UnableToCompleteException;

diff --git a/dev/core/src/com/google/gwt/core/ext/PropertyOracle.java b/dev/core/src/com/google/gwt/core/ext/PropertyOracle.java
index 57c5653..35dda73 100644
--- a/dev/core/src/com/google/gwt/core/ext/PropertyOracle.java
+++ b/dev/core/src/com/google/gwt/core/ext/PropertyOracle.java

@@ -21,11 +21,13 @@
 public interface PropertyOracle {
 
   /**
+   * Attempts to get a named deferred binding property. Throws
+   * <code>BadPropertyValueException</code> if the property is either
+   * undefined or has a value that is unsupported.
+   * 
    * @param logger the current logger
    * @param propertyName the name of the property
    * @return a value for the property
-   * @throws BadPropertyValueException if the property is either undefined or
-   *           has a value that is unsupported
    */
   String getPropertyValue(TreeLogger logger, String propertyName)
       throws BadPropertyValueException;

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/JConstructor.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/JConstructor.java
index 46a5d22..a3e2a25 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/JConstructor.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/JConstructor.java

@@ -15,6 +15,9 @@
  */
 package com.google.gwt.core.ext.typeinfo;
 
+/**
+ * Represents a constructor declaration.
+ */
 public class JConstructor extends JAbstractMethod {
   private final JClassType enclosingType;
 

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/JField.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/JField.java
index 096551b..a594477 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/JField.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/JField.java

@@ -15,6 +15,9 @@
  */
 package com.google.gwt.core.ext.typeinfo;
 
+/**
+ * Represents a field declaration.
+ */
 public class JField implements HasMetaData {
 
   private final JClassType enclosingType;

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/JMethod.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/JMethod.java
index 263cc9c..c786f38 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/JMethod.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/JMethod.java

@@ -15,6 +15,9 @@
  */
 package com.google.gwt.core.ext.typeinfo;
 
+/**
+ * Represents a method declaration.
+ */
 public class JMethod extends JAbstractMethod {
 
   private final JClassType enclosingType;

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/JPackage.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/JPackage.java
index 26bd1f1..acbc326 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/JPackage.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/JPackage.java

@@ -18,6 +18,9 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Represents a logical package.
+ */
 public class JPackage {
 
   private final String name;

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/JParameter.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/JParameter.java
index 41d8a9d..c1a897b 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/JParameter.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/JParameter.java

@@ -15,6 +15,9 @@
  */
 package com.google.gwt.core.ext.typeinfo;
 
+/**
+ * Represents a parameter in a declaration.
+ */
 public class JParameter implements HasMetaData {
 
   private final HasMetaData metaData = new MetaData();

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/JParameterizedType.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/JParameterizedType.java
index a0e5374..b4bf9fb 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/JParameterizedType.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/JParameterizedType.java

@@ -19,6 +19,9 @@
 import java.util.Iterator;
 import java.util.List;
 
+/**
+ * Represents a parameterized type in a declaration.
+ */
 public class JParameterizedType extends JType {
 
   private final JClassType parameterized;

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/JPrimitiveType.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/JPrimitiveType.java
index 3244e73..f80ca72 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/JPrimitiveType.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/JPrimitiveType.java

@@ -18,6 +18,9 @@
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Represents a primitive type in a declaration.
+ */
 public class JPrimitiveType extends JType {
 
   public static final JPrimitiveType BOOLEAN = create("boolean", "Z");

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/JType.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/JType.java
index 0b949d4..fd7806a 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/JType.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/JType.java

@@ -15,6 +15,9 @@
  */
 package com.google.gwt.core.ext.typeinfo;
 
+/**
+ * Abstract superclass for types.
+ */
 public abstract class JType {
   public abstract String getJNISignature();
 

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/NotFoundException.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/NotFoundException.java
index c0e6209..7d0986e 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/NotFoundException.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/NotFoundException.java

@@ -15,6 +15,9 @@
  */
 package com.google.gwt.core.ext.typeinfo;
 
+/**
+ * Indicates that the requested type info element could not be found.
+ */
 public class NotFoundException extends TypeOracleException {
 
   public NotFoundException() {

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/ParseException.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/ParseException.java
index 02ce296..e67f03d 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/ParseException.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/ParseException.java

@@ -15,6 +15,9 @@
  */
 package com.google.gwt.core.ext.typeinfo;
 
+/**
+ * Indicates that a source declaration was not parsed successfully.
+ */
 public class ParseException extends TypeOracleException {
 
   public ParseException() {

diff --git a/dev/core/src/com/google/gwt/core/ext/typeinfo/TypeOracle.java b/dev/core/src/com/google/gwt/core/ext/typeinfo/TypeOracle.java
index 4cad1a5..ff471b6 100644
--- a/dev/core/src/com/google/gwt/core/ext/typeinfo/TypeOracle.java
+++ b/dev/core/src/com/google/gwt/core/ext/typeinfo/TypeOracle.java

@@ -47,6 +47,7 @@
  * JParameterizedType ls = typeOracle.parse(&quot;java.util.List&lt;java.lang.String&gt;&quot;);
  * assert(ls.getTypeArgs()[0] == s1);
  * </pre>
+ * 
  * </p>
  */
 public class TypeOracle {
@@ -123,7 +124,7 @@
     if (0 != (bits & MOD_TRANSIENT)) {
       strings.add("transient");
     }
-    
+
     if (0 != (bits & MOD_VOLATILE)) {
       strings.add("volatile");
     }
@@ -206,7 +207,7 @@
     }
     return null;
   }
-  
+
   /**
    * Gets the type object that represents an array of the specified type. The
    * returned type always has a stable identity so as to guarantee that all
@@ -257,7 +258,6 @@
    * Gets a package by name. All requests for the same package return the same
    * package object.
    * 
-   * @throws NotFoundException if the specified package name is not available
    * @return the package object associated with the specified name
    */
   public JPackage getPackage(String pkgName) throws NotFoundException {
@@ -298,8 +298,7 @@
       parameterized.addTypeArg(typeArgs[i]);
     }
     String sig = parameterized.getQualifiedSourceName();
-    JParameterizedType existing =
-        (JParameterizedType) parameterizedTypes.get(sig);
+    JParameterizedType existing = (JParameterizedType) parameterizedTypes.get(sig);
     if (existing == null) {
       parameterizedTypes.put(sig, parameterized);
       existing = parameterized;
@@ -316,8 +315,6 @@
    * source name rather than its binary name (that is, use a "." rather than a
    * "$").
    * 
-   * @throws NotFoundException thrown if the specified package or type could not
-   *           be found
    * @return the specified type
    */
   public JClassType getType(String name) throws NotFoundException {
@@ -333,8 +330,6 @@
    * source name rather than its binary name (that is, use a "." rather than a
    * "$").
    * 
-   * @throws NotFoundException thrown if the specified package or type could not
-   *           be found
    * @return the specified type
    */
   public JClassType getType(String pkgName, String topLevelTypeSimpleName)
@@ -394,7 +389,6 @@
    * 
    * @param type a type signature to be parsed
    * @return the type object corresponding to the parse type
-   * @throws TypeOracleException
    */
   public JType parse(String type) throws TypeOracleException {
     // Remove all internal and external whitespace.
@@ -491,7 +485,7 @@
   void recordTypeInCompilationUnit(CompilationUnitProvider cup, JClassType type) {
     JClassType[] types = (JClassType[]) typesByCup.get(cup);
     if (types == null) {
-      types = new JClassType[]{type};
+      types = new JClassType[] {type};
     } else {
       JClassType[] temp = new JClassType[types.length + 1];
       System.arraycopy(types, 0, temp, 0, types.length);
@@ -505,11 +499,13 @@
    * Updates relationships within this type oracle. Should be called after any
    * changes are made.
    * 
-   * @throws TypeOracleException thrown if fundamental baseline correctness
-   *           criteria are violated, most notably the absence of
-   *           "java.lang.Object"
+   * <p>
+   * Throws <code>TypeOracleException</code> thrown if fundamental baseline
+   * correctness criteria are violated, most notably the absence of
+   * "java.lang.Object"
+   * </p>
    */
-    void refresh(TreeLogger logger) throws NotFoundException {
+  void refresh(TreeLogger logger) throws NotFoundException {
     if (javaLangObject == null) {
       javaLangObject = findType("java.lang.Object");
       if (javaLangObject == null) {
@@ -542,9 +538,8 @@
   }
 
   private void consumeTypeArgMetaData(TreeLogger logger) {
-    logger =
-        logger.branch(TreeLogger.DEBUG, "Examining " + TAG_TYPEARGS + " tags",
-          null);
+    logger = logger.branch(TreeLogger.DEBUG, "Examining " + TAG_TYPEARGS
+        + " tags", null);
     consumeTypeArgMetaData(logger, getTypes());
   }
 
@@ -553,14 +548,14 @@
       JClassType type = types[i];
       // CTORS not supported yet
 
-      TreeLogger branch =
-          logger.branch(TreeLogger.DEBUG, "Type "
-            + type.getQualifiedSourceName(), null);
+      TreeLogger branch = logger.branch(TreeLogger.DEBUG, "Type "
+          + type.getQualifiedSourceName(), null);
 
       consumeTypeArgMetaData(branch, type.getMethods());
       consumeTypeArgMetaData(branch, type.getFields());
     }
   }
+
   private void consumeTypeArgMetaData(TreeLogger logger, JField[] fields) {
     TreeLogger branch;
     for (int i = 0; i < fields.length; i++) {
@@ -579,9 +574,9 @@
         if (tokensArray.length > 1) {
           // Too many.
           branch.log(TreeLogger.WARN, "Metadata error on field '"
-            + field.getName() + "' in type '" + field.getEnclosingType()
-            + "': expecting at most one " + TAG_TYPEARGS
-            + " (the last one will be used)", null);
+              + field.getName() + "' in type '" + field.getEnclosingType()
+              + "': expecting at most one " + TAG_TYPEARGS
+              + " (the last one will be used)", null);
         }
 
         // (1) Parse it.
@@ -598,6 +593,7 @@
       }
     }
   }
+
   private void consumeTypeArgMetaData(TreeLogger logger, JMethod[] methods) {
     TreeLogger branch;
     for (int i = 0; i < methods.length; i++) {
@@ -624,7 +620,7 @@
             // Expecting at least something.
             //
             branch.log(TreeLogger.WARN,
-              "Metadata error: expecting tokens after " + TAG_TYPEARGS, null);
+                "Metadata error: expecting tokens after " + TAG_TYPEARGS, null);
             throw new UnableToCompleteException();
           }
 
@@ -635,16 +631,15 @@
             if (!paramsAlreadySet.contains(param)) {
               // These are type args for a param.
               //
-              JType resultingType =
-                  determineActualType(branch, param.getType(), tokens, 1);
+              JType resultingType = determineActualType(branch,
+                  param.getType(), tokens, 1);
               param.setType(resultingType);
               paramsAlreadySet.add(param);
             } else {
               // This parameter type has already been set.
               //
-              msg =
-                  "Metadata error: duplicate attempt to specify type args for parameter '"
-                    + param.getName() + "'";
+              msg = "Metadata error: duplicate attempt to specify type args for parameter '"
+                  + param.getName() + "'";
               branch.log(TreeLogger.WARN, msg, null);
               throw new UnableToCompleteException();
             }
@@ -652,15 +647,14 @@
             // It's either referring to the return type or a bad param name.
             //
             if (!returnTypeHandled) {
-              JType resultingType =
-                  determineActualType(branch, method.getReturnType(), tokens, 0);
+              JType resultingType = determineActualType(branch,
+                  method.getReturnType(), tokens, 0);
               method.setReturnType(resultingType);
               returnTypeHandled = true;
             } else {
               // The return type has already been set.
               //
-              msg =
-                  "Metadata error: duplicate attempt to specify type args for the return type";
+              msg = "Metadata error: duplicate attempt to specify type args for the return type";
               branch.log(TreeLogger.WARN, msg, null);
             }
           }
@@ -671,11 +665,10 @@
       }
     }
   }
+
   /*
    * Given a declared type and some number of type arguments determine what the
-   * actual type should be. 
-   * 
-   * @throws UnableToCompleteException
+   * actual type should be.
    */
   private JType determineActualType(TreeLogger logger, JType declType,
       String[] tokens, int startIndex) throws UnableToCompleteException {
@@ -683,8 +676,8 @@
     //
     JType leafType = declType.getLeafType();
     String typeName = leafType.getQualifiedSourceName();
-    JType resultingType =
-        parseTypeArgTokens(logger, typeName, tokens, startIndex);
+    JType resultingType = parseTypeArgTokens(logger, typeName, tokens,
+        startIndex);
     JArrayType arrayType = declType.isArray();
     if (arrayType != null) {
       arrayType.setLeafType(resultingType);
@@ -694,6 +687,7 @@
 
     return resultingType;
   }
+
   private JType parseImpl(String type) throws NotFoundException,
       ParseException, BadTypeArgsException {
     if (type.endsWith("[]")) {
@@ -706,7 +700,7 @@
       int bracket = type.indexOf('<');
       if (bracket == -1) {
         throw new ParseException(
-          "Mismatched brackets; expected '<' to match subsequent '>'");
+            "Mismatched brackets; expected '<' to match subsequent '>'");
       }
 
       // Resolve the raw type.
@@ -717,15 +711,15 @@
         // The raw type cannot itself be parmeterized.
         //
         throw new BadTypeArgsException(
-          "Only non-parameterized classes and interface can be parameterized");
+            "Only non-parameterized classes and interface can be parameterized");
       } else if (rawType.isClassOrInterface() == null) {
         // The raw type must be a class or interface
         // (not an array or primitive).
         //
         throw new BadTypeArgsException(
-          "Only classes and interface can be parameterized, so "
-            + rawType.getQualifiedSourceName()
-            + " cannot be used in this context");
+            "Only classes and interface can be parameterized, so "
+                + rawType.getQualifiedSourceName()
+                + " cannot be used in this context");
       }
 
       // Resolve each type argument.
@@ -739,9 +733,9 @@
           // Cannot be primitive.
           //
           throw new BadTypeArgsException(
-            "Type arguments cannot be primitive, so "
-              + typeArgs[i].getQualifiedSourceName()
-              + " cannot be used in this context");
+              "Type arguments cannot be primitive, so "
+                  + typeArgs[i].getQualifiedSourceName()
+                  + " cannot be used in this context");
         }
       }
 
@@ -762,6 +756,7 @@
 
     throw new NotFoundException(type);
   }
+
   private JType parseTypeArgTokens(TreeLogger logger, String maybeRawType,
       String[] tokens, int startIndex) throws UnableToCompleteException {
     String munged = combine(tokens, startIndex).trim();
@@ -770,9 +765,8 @@
     try {
       parameterizedType = parse(toParse);
     } catch (TypeOracleException e) {
-      String msg =
-          "Unable to recognize '" + toParse
-            + "' as a type name (is it fully qualified?)";
+      String msg = "Unable to recognize '" + toParse
+          + "' as a type name (is it fully qualified?)";
       logger.log(TreeLogger.WARN, msg, null);
       throw new UnableToCompleteException();
     }