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("java.util.List<java.lang.String>");
* 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();
}
