harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r767477 [1/5] - in /harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang: ./ ref/ reflect/
Date Wed, 22 Apr 2009 12:04:11 GMT
Author: tellison
Date: Wed Apr 22 12:04:10 2009
New Revision: 767477

URL: http://svn.apache.org/viewvc?rev=767477&view=rev
Log:
Apply patch for HARMONY-6164 (Javadocs for luni-kernel)
All documentation formatting / updates except once case, where the patch reorders the enum constants in Thread.State to match the RI.

Modified:
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Class.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ClassLoader.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Compiler.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Object.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Package.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Runtime.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/StackTraceElement.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/System.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Thread.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ThreadGroup.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Throwable.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/PhantomReference.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/Reference.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/SoftReference.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/ref/WeakReference.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/AccessibleObject.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Array.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Constructor.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Field.java
    harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Method.java

Modified: harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Class.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Class.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Class.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/Class.java Wed Apr 22 12:04:10 2009
@@ -32,52 +32,71 @@
 import java.security.ProtectionDomain;
 
 /**
- * This class must be implemented by the VM vendor. The documented natives must
- * be implemented to support other provided class implementations in this
- * package. An instance of class Class is the in-image representation of a Java
- * class. There are three basic types of Classes
- * <dl>
- * <dt><em>Classes representing object types (classes or interfaces)</em>
- * </dt>
- * <dd>These are Classes which represent the class of a simple instance as
- * found in the class hierarchy. The name of one of these Classes is simply the
- * fully qualified class name of the class or interface that it represents. Its
- * <em>signature</em> is the letter "L", followed by its name, followed by a
- * semi-colon (";").</dd>
- * <dt><em>Classes representing base types</em></dt>
- * <dd>These Classes represent the standard Java base types. Although it is not
- * possible to create new instances of these Classes, they are still useful for
- * providing reflection information, and as the component type of array classes.
- * There is one of these Classes for each base type, and their signatures are:
+ * The in-memory representation of a Java class. This representation serves as
+ * the starting point for querying class-related information, a process usually
+ * called "reflection". There are basically three types of {@code Class}
+ * instances: those representing real classes and interfaces, those representing
+ * primitive types, and those representing array classes.
+ *
+ * <h4>Class instances representing object types (classes or interfaces)</h4>
+ * <p>
+ * These represent an ordinary class or interface as found in the class
+ * hierarchy. The name associated with these {@code Class} instances is simply
+ * the fully qualified class name of the class or interface that it represents.
+ * In addition to this human-readable name, each class is also associated by a
+ * so-called <em>signature</em>, which is the letter "L", followed by the
+ * class name and a semicolon (";"). The signature is what the runtime system
+ * uses internally for identifying the class (for example in a DEX file).
+ * </p>
+ * <h4>Classes representing primitive types</h4>
+ * <p>
+ * These represent the standard Java primitive types and hence share their
+ * names (for example "int" for the {@code int} primitive type). Although it is
+ * not possible to create new instances based on these {@code Class} instances,
+ * they are still useful for providing reflection information, and as the
+ * component type of array classes. There is one {@code Class} instance for each
+ * primitive type, and their signatures are:
+ * </p>
  * <ul>
- * <li><code>B</code> representing the <code>byte</code> base type</li>
- * <li><code>S</code> representing the <code>short</code> base type</li>
- * <li><code>I</code> representing the <code>int</code> base type</li>
- * <li><code>J</code> representing the <code>long</code> base type</li>
- * <li><code>F</code> representing the <code>float</code> base type</li>
- * <li><code>D</code> representing the <code>double</code> base type</li>
- * <li><code>C</code> representing the <code>char</code> base type</li>
- * <li><code>Z</code> representing the <code>boolean</code> base type</li>
- * <li><code>V</code> representing void function return values</li>
+ * <li>{@code B} representing the {@code byte} primitive type</li>
+ * <li>{@code S} representing the {@code short} primitive type</li>
+ * <li>{@code I} representing the {@code int} primitive type</li>
+ * <li>{@code J} representing the {@code long} primitive type</li>
+ * <li>{@code F} representing the {@code float} primitive type</li>
+ * <li>{@code D} representing the {@code double} primitive type</li>
+ * <li>{@code C} representing the {@code char} primitive type</li>
+ * <li>{@code Z} representing the {@code boolean} primitive type</li>
+ * <li>{@code V} representing void function return values</li>
  * </ul>
- * The name of a Class representing a base type is the keyword which is used to
- * represent the type in Java source code (i.e. "int" for the <code>int</code>
- * base type.</dd>
- * <dt><em>Classes representing array classes</em></dt>
- * <dd>These are Classes which represent the classes of Java arrays. There is
- * one such Class for all array instances of a given arity (number of
- * dimensions) and leaf component type. In this case, the name of the class is
- * one or more left square brackets (one per dimension in the array) followed by
- * the signature ofP the class representing the leaf component type, which can
- * be either an object type or a base type. The signature of a Class
- * representing an array type is the same as its name.</dd>
- * </dl>
- * 
+ * <p>
+ * <h4>Classes representing array classes</h4>
+ * <p>
+ * These represent the classes of Java arrays. There is one such {@code Class}
+ * instance per combination of array leaf component type and arity (number of
+ * dimensions). In this case, the name associated with the {@code Class}
+ * consists of one or more left square brackets (one per dimension in the array)
+ * followed by the signature of the class representing the leaf component type,
+ * which can be either an object type or a primitive type. The signature of a
+ * {@code Class} representing an array type is the same as its name. Examples
+ * of array class signatures are:
+ * </p>
+ * <ul>
+ * <li>{@code [I} representing the {@code int[]} type</li>
+ * <li>{@code [Ljava/lang/String;} representing the {@code String[]} type</li>
+ * <li>{@code [[[C} representing the {@code char[][][]} type (three dimensions!)</li>
+ * </ul>
+ *
  * @since 1.0
  */
 public final class Class<T> implements Serializable, AnnotatedElement,
         GenericDeclaration, Type {
 
+    /*
+     * This class must be implemented by the VM vendor. The documented natives must
+     * be implemented to support other provided class implementations in this
+     * package.
+     */
+
     private static final long serialVersionUID = 3206093459760846163L;
 
     private Class() {
@@ -123,17 +142,26 @@
     }
 
     /**
-     * Answers a Class object which represents the class named by the argument.
-     * 
-     * The name should be the name of a class as described in the class
-     * definition of <code>Class</code>, however Classes representing base
-     * types can not be found using this method.
-     * 
+     * Returns a {@code Class} object which represents the class with the
+     * specified name. The name should be the name of a class as described in
+     * the {@link Class class definition}; however, {@code Class}es representing
+     * primitive types can not be found using this method.
+     * <p>
+     * If the class has not been loaded so far, it is being loaded and linked
+     * first. This is done through either the class loader of the calling class
+     * or one of its parent class loaders. The class is also being initialized,
+     * which means that a possible static initializer block is executed.
+     *
      * @param className
-     *            The name of the non-base type class to find
-     * @return the named Class
+     *            the name of the non-primitive-type class to find.
+     * @return the named {@code Class} instance.
      * @throws ClassNotFoundException
-     *             If the class could not be found
+     *             if the requested class can not be found.
+     * @throws LinkageError
+     *             if an error occurs during linkage
+     * @throws ExceptionInInitializerError
+     *             if an exception occurs during static initialization of a
+     *             class.
      */
     public static Class<?> forName(String className)
             throws ClassNotFoundException {
@@ -141,20 +169,32 @@
     }
 
     /**
-     * Answers a Class object which represents the class named by the argument.
-     * The name should be the name of a class as described in the class
-     * definition of <code>Class</code>, however Classes representing base
-     * types can not be found using this method. Security rules will be obeyed.
-     * 
+     * Returns a {@code Class} object which represents the class with the
+     * specified name. The name should be the name of a class as described in
+     * the {@link Class class definition}, however {@code Class}es representing
+     * primitive types can not be found using this method. Security rules will
+     * be obeyed.
+     * <p>
+     * If the class has not been loaded so far, it is being loaded and linked
+     * first. This is done through either the specified class loader or one of
+     * its parent class loaders. The caller can also request the class to be
+     * initialized, which means that a possible static initializer block is
+     * executed.
+     *
      * @param className
-     *            The name of the non-base type class to find
+     *            the name of the non-primitive-type class to find.
      * @param initializeBoolean
-     *            A boolean indicating whether the class should be initialized
+     *            indicates whether the class should be initialized.
      * @param classLoader
-     *            The class loader to use to load the class
-     * @return the named class.
+     *            the class loader to use to load the class.
+     * @return the named {@code Class} instance.
      * @throws ClassNotFoundException
-     *             If the class could not be found
+     *             if the requested class can not be found.
+     * @throws LinkageError
+     *             if an error occurs during linkage
+     * @throws ExceptionInInitializerError
+     *             if an exception occurs during static initialization of a
+     *             class.
      */
     public static Class<?> forName(String className, boolean initializeBoolean,
             ClassLoader classLoader) throws ClassNotFoundException {
@@ -162,12 +202,16 @@
     }
 
     /**
-     * Answers an array containing all public class members of the class which
-     * the receiver represents and its super classes and interfaces
-     * 
-     * @return the class' public class members
+     * Returns an array containing {@code Class} objects for all public classes
+     * and interfaces that are members of this class. This includes public
+     * members inherited from super classes and interfaces. If there are no such
+     * class members or if this object represents a primitive type then an array
+     * of length 0 is returned.
+     *
+     * @return the public class members of the class represented by this object.
      * @throws SecurityException
-     *             If member access is not allowed
+     *             if a security manager exists and it does not allow member
+     *             access.
      */
     @SuppressWarnings("unchecked") // According to spec
     public Class[] getClasses() {
@@ -185,12 +229,13 @@
     }
 
     /**
-     * Answers the annotation of the given type. If there is no annotation the
-     * method returns <code>null</code>.
-     * 
+     * Returns the annotation of the given type. If there is no such annotation
+     * then the method returns {@code null}.
+     *
      * @param annotationClass
      *            the annotation type.
-     * @return the annotation of the given type, or <code>null</code> if none.
+     * @return the annotation of the given type, or {@code null} if there is no
+     *         such annotation.
      * @since 1.5
      */
     public <A extends Annotation> A getAnnotation(Class<A> annotationClass) {
@@ -198,32 +243,38 @@
     }
 
     /**
-     * Answers all the annotations of the receiver. If there are no annotations
-     * then answers an empty array.
-     * 
-     * @return a copy of the array containing the receiver's annotations.
+     * Returns all the annotations of this class. If there are no annotations
+     * then an empty array is returned.
+     *
+     * @return a copy of the array containing this class' annotations.
+     * @see #getDeclaredAnnotations()
      */
     public Annotation[] getAnnotations() {
         return new Annotation[0];
     }
 
     /**
-     * Answers the canonical name of the receiver. If the receiver does not have
-     * a canonical name, as defined in the Java Language Specification, then the
-     * method returns <code>null</code>.
-     * 
-     * @return the receiver canonical name, or <code>null</code>.
+     * Returns the canonical name of this class. If this class does not have a
+     * canonical name as defined in the Java Language Specification, then the
+     * method returns {@code null}.
+     *
+     * @return this class' canonical name, or {@code null} if it does not have a
+     *         canonical name.
      */
     public String getCanonicalName() {
         return null;
     }
 
     /**
-     * Answers the class loader which was used to load the class represented by
-     * the receiver. Answer null if the class was loaded by the system class
-     * loader
-     * 
-     * @return the receiver's class loader or null
+     * Returns the class loader which was used to load the class represented by
+     * this {@code Class}. Implementations are free to return {@code null} for
+     * classes that were loaded by the bootstrap class loader.
+     *
+     * @return the class loader for the represented class.
+     * @throws SecurityException
+     *             if a security manager exists and it does not allow accessing
+     *             the class loader.
+     * @see ClassLoader
      */
     public ClassLoader getClassLoader() {
         return null;
@@ -246,28 +297,30 @@
     }
 
     /**
-     * Answers a Class object which represents the receiver's component type if
-     * the receiver represents an array type. Otherwise answers null. The
-     * component type of an array type is the type of the elements of the array.
-     * 
-     * @return the component type of the receiver.
+     * Returns a {@code Class} object which represents the component type if
+     * this class represents an array type. Returns {@code null} if this class
+     * does not represent an array type. The component type of an array type is
+     * the type of the elements of the array.
+     *
+     * @return the component type of this class.
      */
     public Class<?> getComponentType() {
         return null;
     }
 
     /**
-     * Answers a public Constructor object which represents the constructor
-     * described by the arguments.
-     * 
+     * Returns a {@code Constructor} object which represents the public
+     * constructor matching the specified parameter types.
+     *
      * @param parameterTypes
-     *            the types of the arguments.
-     * @return the constructor described by the arguments.
+     *            the parameter types of the requested constructor.
+     * @return the constructor described by {@code parameterTypes}.
      * @throws NoSuchMethodException
-     *             if the constructor could not be found.
+     *             if the constructor can not be found.
      * @throws SecurityException
-     *             if member access is not allowed
-     * @see #getConstructors
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getDeclaredConstructor(Class[])
      */
     public Constructor<T> getConstructor(Class... parameterTypes)
             throws NoSuchMethodException, SecurityException {
@@ -275,56 +328,67 @@
     }
 
     /**
-     * Answers an array containing Constructor objects describing all
-     * constructors which are visible from the current execution context.
-     * 
-     * @return all visible constructors starting from the receiver.
-     * @throws SecurityException
-     *             if member access is not allowed
-     * @see #getMethods
+     * Returns an array containing {@code Constructor} objects for all public
+     * constructors for the class represented by this {@code Class}. If there
+     * are no public constructors or if this {@code Class} represents an array
+     * class, a primitive type or void then an empty array is returned.
+     *
+     * @return an array with the public constructors of the class represented by
+     *         this {@code Class}.
+     * @throws SecurityException
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getDeclaredConstructors()
      */
     public Constructor[] getConstructors() throws SecurityException {
         return null;
     }
 
     /**
-     * Answers the annotations that are directly defined on this type.
-     * Annotations that are inherited are not included in the result. If there
-     * are no annotations, returns an empty array.
-     * 
-     * @return a copy of the array containing the receiver's defined
-     *         annotations.
-     * @since 1.5
+     * Returns the annotations that are directly defined on the class
+     * represented by this {@code Class}. Annotations that are inherited are not
+     * included in the result. If there are no annotations at all, an empty
+     * array is returned.
+     *
+     * @return a copy of the array containing the annotations defined for the
+     *         class that this {@code Class} represents.
+     * @see #getAnnotations()
      */
     public Annotation[] getDeclaredAnnotations() {
         return new Annotation[0];
     }
 
     /**
-     * Answers an array containing all class members of the class which the
-     * receiver represents. Note that some of the fields which are returned may
-     * not be visible in the current execution context.
-     * 
-     * @return the class' class members
+     * Returns an array containing {@code Class} objects for all classes and
+     * interfaces that are declared as members of the class which this {@code
+     * Class} represents. If there are no classes or interfaces declared or if
+     * this class represents an array class, a primitive type or void, then an
+     * empty array is returned.
+     *
+     * @return an array with {@code Class} objects for all the classes and
+     *         interfaces that are used in member declarations.
      * @throws SecurityException
-     *             if member access is not allowed
+     *             if a security manager exists and it does not allow member
+     *             access.
      */
     public Class[] getDeclaredClasses() throws SecurityException {
         return new Class[0];
     }
 
     /**
-     * Answers a Constructor object which represents the constructor described
-     * by the arguments.
-     * 
+     * Returns a {@code Constructor} object which represents the constructor
+     * matching the specified parameter types that is declared by the class
+     * represented by this {@code Class}.
+     *
      * @param parameterTypes
-     *            the types of the arguments.
-     * @return the constructor described by the arguments.
+     *            the parameter types of the requested constructor.
+     * @return the constructor described by {@code parameterTypes}.
      * @throws NoSuchMethodException
-     *             if the constructor could not be found.
+     *             if the requested constructor can not be found.
      * @throws SecurityException
-     *             if member access is not allowed
-     * @see #getConstructors
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getConstructor(Class[])
      */
     public Constructor<T> getDeclaredConstructor(Class... parameterTypes)
             throws NoSuchMethodException, SecurityException {
@@ -332,33 +396,36 @@
     }
 
     /**
-     * Answers an array containing Constructor objects describing all
-     * constructor which are defined by the receiver. Note that some of the
-     * fields which are returned may not be visible in the current execution
-     * context.
-     * 
-     * @return the receiver's constructors.
-     * @throws SecurityException
-     *             if member access is not allowed
-     * @see #getMethods
+     * Returns an array containing {@code Constructor} objects for all
+     * constructors declared in the class represented by this {@code Class}. If
+     * there are no constructors or if this {@code Class} represents an array
+     * class, a primitive type or void then an empty array is returned.
+     *
+     * @return an array with the constructors declared in the class represented
+     *         by this {@code Class}.
+     *
+     * @throws SecurityException
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getConstructors()
      */
     public Constructor[] getDeclaredConstructors() throws SecurityException {
         return new Constructor[0];
     }
 
     /**
-     * Answers a Field object describing the field in the receiver named by the
-     * argument. Note that the Constructor may not be visible from the current
-     * execution context.
-     * 
+     * Returns a {@code Field} object for the field with the specified name
+     * which is declared in the class represented by this {@code Class}.
+     *
      * @param name
-     *            The name of the field to look for.
-     * @return the field in the receiver named by the argument.
+     *            the name of the requested field.
+     * @return the requested field in the class represented by this class.
      * @throws NoSuchFieldException
-     *             if the requested field could not be found
+     *             if the requested field can not be found.
      * @throws SecurityException
-     *             if member access is not allowed
-     * @see #getDeclaredFields
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getField(String)
      */
     public Field getDeclaredField(String name) throws NoSuchFieldException,
             SecurityException {
@@ -366,36 +433,40 @@
     }
 
     /**
-     * Answers an array containing Field objects describing all fields which are
-     * defined by the receiver. Note that some of the fields which are returned
-     * may not be visible in the current execution context.
-     * 
-     * @return the receiver's fields.
-     * @throws SecurityException
-     *             If member access is not allowed
-     * @see #getFields
+     * Returns an array containing {@code Field} objects for all fields declared
+     * in the class represented by this {@code Class}. If there are no fields or
+     * if this {@code Class} represents an array class, a primitive type or void
+     * then an empty array is returned.
+     *
+     * @return an array with the fields declared in the class represented by
+     *         this class.
+     * @throws SecurityException
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getFields()
      */
     public Field[] getDeclaredFields() throws SecurityException {
         return new Field[0];
     }
 
     /**
-     * Answers a Method object which represents the method described by the
-     * arguments. Note that the associated method may not be visible from the
-     * current execution context.
-     * 
+     * Returns a {@code Method} object which represents the method matching the
+     * specified name and parameter types that is declared by the class
+     * represented by this {@code Class}.
+     *
      * @param name
-     *            the name of the method
+     *            the requested method's name.
      * @param parameterTypes
-     *            the types of the arguments.
-     * @return the method described by the arguments.
+     *            the parameter types of the requested method.
+     * @return the method described by {@code name} and {@code parameterTypes}.
      * @throws NoSuchMethodException
-     *             if the method could not be found.
-     * @throws SecurityException
-     *             If member access is not allowed
+     *             if the requested constructor can not be found.
      * @throws NullPointerException
-     *             if the name parameter is <code>null</code>.
-     * @see #getMethods
+     *             if {@code name} is {@code null}.
+     * @throws SecurityException
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getMethod(String, Class[])
      */
     public Method getDeclaredMethod(String name, Class... parameterTypes)
             throws NoSuchMethodException, SecurityException {
@@ -403,69 +474,69 @@
     }
 
     /**
-     * Answers an array containing Method objects describing all methods which
-     * are defined by the receiver. Note that some of the methods which are
-     * returned may not be visible in the current execution context.
-     * 
-     * @throws SecurityException
-     *             if member access is not allowed
-     * @return the receiver's methods.
-     * @see #getMethods
+     * Returns an array containing {@code Method} objects for all methods
+     * declared in the class represented by this {@code Class}. If there are no
+     * methods or if this {@code Class} represents an array class, a primitive
+     * type or void then an empty array is returned.
+     *
+     * @return an array with the methods declared in the class represented by
+     *         this {@code Class}.
+     * @throws SecurityException
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getMethods()
      */
     public Method[] getDeclaredMethods() throws SecurityException {
         return new Method[0];
     }
 
     /**
-     * Answers the class which declared the class represented by the receiver.
-     * This will return null if the receiver is a member of another class.
-     * 
-     * @return the declaring class of the receiver.
+     * Returns the declaring {@code Class} of this {@code Class}. Returns
+     * {@code null} if the class is not a member of another class or if this
+     * {@code Class} represents an array class, a primitive type or void.
+     *
+     * @return the declaring {@code Class} or {@code null}.
      */
     public Class<?> getDeclaringClass() {
         return null;
     }
 
     /**
-     * Answers the class that directly encloses the receiver. If there is no
-     * enclosing class the method returns <code>null</code>.
-     * 
-     * @return the enclosing class or <code>null</code>.
+     * Returns the enclosing {@code Class} of this {@code Class}. If there is no
+     * enclosing class the method returns {@code null}.
+     *
+     * @return the enclosing {@code Class} or {@code null}.
      */
     public Class<?> getEnclosingClass() {
         return null;
     }
 
     /**
-     * Gets the {@link Constructor}, which encloses the declaration of this
-     * class, if it is an anonymous or local/automatic class, otherwise
-     * <code>null</code>.
-     * 
-     * @return A {@link Constructor} instance or <code>null</code>.
-     * @since 1.5
+     * Gets the enclosing {@code Constructor} of this {@code Class}, if it is an
+     * anonymous or local/automatic class; otherwise {@code null}.
+     *
+     * @return the enclosing {@code Constructor} instance or {@code null}.
      */
     public Constructor<?> getEnclosingConstructor() {
         return null;
     }
 
     /**
-     * Gets the {@link Method}, which encloses the declaration of this class,
-     * if it is an anonymous or local/automatic class, otherwise
-     * <code>null</code>.
-     * 
-     * @return A {@link Method} instance or <code>null</code>.
-     * @since 1.5
+     * Gets the enclosing {@code Method} of this {@code Class}, if it is an
+     * anonymous or local/automatic class; otherwise {@code null}.
+     *
+     * @return the enclosing {@code Method} instance or {@code null}.
      */
     public Method getEnclosingMethod() {
         return null;
     }
 
     /**
-     * Gets the <code>enum</code> constants/fields associated with this class
-     * if it is an {@linkplain #isEnum() enum}, otherwise <code>null</code>.
-     * 
-     * @return An array of the <code>enum</code> constants for this class or
-     *         <code>null</code>.
+     * Gets the {@code enum} constants associated with this {@code Class}.
+     * Returns {@code null} if this {@code Class} does not represent an {@code
+     * enum} type.
+     *
+     * @return an array with the {@code enum} constants or {@code null}.
      * @since 1.5
      */
     public T[] getEnumConstants() {
@@ -473,17 +544,20 @@
     }
 
     /**
-     * Answers a Field object describing the field in the receiver named by the
-     * argument which must be visible from the current execution context.
-     * 
+     * Returns a {@code Field} object which represents the public field with the
+     * specified name. This method first searches the class C represented by
+     * this {@code Class}, then the interfaces implemented by C and finally the
+     * superclasses of C.
+     *
      * @param name
-     *            The name of the field to look for.
-     * @return the field in the receiver named by the argument.
+     *            the name of the requested field.
+     * @return the public field specified by {@code name}.
      * @throws NoSuchFieldException
-     *             If the given field does not exist
+     *             if the field can not be found.
      * @throws SecurityException
-     *             If access is denied
-     * @see #getDeclaredFields
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getDeclaredField(String)
      */
     public Field getField(String name) throws NoSuchFieldException,
             SecurityException {
@@ -491,33 +565,43 @@
     }
 
     /**
-     * Answers an array containing Field objects describing all fields which are
-     * visible from the current execution context.
-     * 
-     * @return all visible fields starting from the receiver.
-     * @throws SecurityException
-     *             If member access is not allowed
-     * @see #getDeclaredFields
+     * Returns an array containing {@code Field} objects for all public fields
+     * for the class C represented by this {@code Class}. Fields may be declared
+     * in C, the interfaces it implements or in the superclasses of C. The
+     * elements in the returned array are in no particular order.
+     * <p>
+     * If there are no public fields or if this class represents an array class,
+     * a primitive type or {@code void} then an empty array is returned.
+     * </p>
+     *
+     * @return an array with the public fields of the class represented by this
+     *         {@code Class}.
+     * @throws SecurityException
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getDeclaredFields()
      */
     public Field[] getFields() throws SecurityException {
         return new Field[0];
     }
 
     /**
-     * Gets the {@link Type types} of the interface that this class directly
-     * implements.
-     * 
-     * @return An array of {@link Type} instances.
-     * @since 1.5
+     * Gets the {@link Type}s of the interfaces that this {@code Class} directly
+     * implements. If the {@code Class} represents a primitive type or {@code
+     * void} then an empty array is returned.
+     *
+     * @return an array of {@link Type} instances directly implemented by the
+     *         class represented by this {@code class}.
      */
     public Type[] getGenericInterfaces() {
         return new Type[0];
     }
 
     /**
-     * Gets the {@link Type} that represents the super class of this class.
-     * 
-     * @return An instance of {@link Type}
+     * Gets the {@code Type} that represents the superclass of this {@code
+     * class}.
+     *
+     * @return an instance of {@code Type} representing the superclass.
      * @since 1.5
      */
     public Type getGenericSuperclass() {
@@ -525,29 +609,37 @@
     }
 
     /**
-     * Answers an array of Class objects which match the interfaces specified in
-     * the receiver classes <code>implements</code> declaration
-     * 
-     * @return Class[] the interfaces the receiver claims to implement.
+     * Returns an array of {@code Class} objects that match the interfaces
+     * specified in the {@code implements} declaration of the class represented
+     * by this {@code Class}. The order of the elements in the array is
+     * identical to the order in the original class declaration. If the class
+     * does not implement any interfaces, an empty array is returned.
+     *
+     * @return an array with the interfaces of the class represented by this
+     *         class.
      */
     public Class[] getInterfaces() {
         return new Class[0];
     }
 
     /**
-     * Answers a Method object which represents the method described by the
-     * arguments.
-     * 
+     * Returns a {@code Method} object which represents the public method with
+     * the specified name and parameter types. This method first searches the
+     * class C represented by this {@code Class}, then the superclasses of C and
+     * finally the interfaces implemented by C and finally the superclasses of C
+     * for a method with matching name.
+     *
      * @param name
-     *            String the name of the method
+     *            the requested method's name.
      * @param parameterTypes
-     *            Class[] the types of the arguments.
-     * @return Method the method described by the arguments.
+     *            the parameter types of the requested method.
+     * @return the public field specified by {@code name}.
      * @throws NoSuchMethodException
-     *             if the method could not be found.
+     *             if the method can not be found.
      * @throws SecurityException
-     *             if member access is not allowed
-     * @see #getMethods
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getDeclaredMethod(String, Class[])
      */
     public Method getMethod(String name, Class... parameterTypes)
             throws NoSuchMethodException, SecurityException {
@@ -555,62 +647,77 @@
     }
 
     /**
-     * Answers an array containing Method objects describing all methods which
-     * are visible from the current execution context.
-     * 
-     * @return Method[] all visible methods starting from the receiver.
-     * @throws SecurityException
-     *             if member access is not allowed
-     * @see #getDeclaredMethods
+     * Returns an array containing {@code Method} objects for all public methods
+     * for the class C represented by this {@code Class}. Methods may be
+     * declared in C, the interfaces it implements or in the superclasses of C.
+     * The elements in the returned array are in no particular order.
+     * <p>
+     * If there are no public methods or if this {@code Class} represents a
+     * primitive type or {@code void} then an empty array is returned.
+     * </p>
+     *
+     * @return an array with the methods of the class represented by this
+     *         {@code Class}.
+     * @throws SecurityException
+     *             if a security manager exists and it does not allow member
+     *             access.
+     * @see #getDeclaredMethods()
      */
     public Method[] getMethods() throws SecurityException {
         return new Method[0];
     }
 
     /**
-     * Answers an integer which which is the receiver's modifiers. Note that the
-     * constants which describe the bits which are returned are implemented in
-     * class {@link Modifier} which may not be available on the target.
-     * 
-     * @return the receiver's modifiers
+     * Returns an integer that represents the modifiers of the class represented
+     * by this {@code Class}. The returned value is a combination of bits
+     * defined by constants in the {@link Modifier} class.
+     *
+     * @return the modifiers of the class represented by this {@code Class}.
      */
     public int getModifiers() {
         return 0;
     }
 
     /**
-     * Answers the name of the class which the receiver represents. For a
+     * Returns the name of the class represented by this {@code Class}. For a
      * description of the format which is used, see the class definition of
-     * <code>Class</code>.
-     * 
-     * @return the receiver's name.
+     * {@link Class}.
+     *
+     * @return the name of the class represented by this {@code Class}.
      */
     public String getName() {
         return null;
     }
 
     /**
-     * Answers the simple name of the receiver as defined in the source code. If
-     * there is no name (the class is anonymous) returns an empty string, and if
-     * the receiver is an array returns the name of the underlying type with
-     * square braces appended (e.g. <code>&quot;Integer[]&quot;</code>).
-     * 
-     * @return the simple name of the receiver.
+     * Returns the simple name of the class represented by this {@code Class} as
+     * defined in the source code. If there is no name (that is, the class is
+     * anonymous) then an empty string is returned. If the receiver is an array
+     * then the name of the underlying type with square braces appended (for
+     * example {@code &quot;Integer[]&quot;}) is returned.
+     *
+     * @return the simple name of the class represented by this {@code Class}.
      */
     public String getSimpleName() {
         return null;
     }
 
     /**
-     * Answers the ProtectionDomain of the receiver.
-     * 
-     * Note: In order to conserve space in embedded targets, we allow this
-     * method to answer null for classes in the system protection domain (i.e.
-     * for system classes). System classes are always given full permissions
-     * (i.e. AllPermission). This is not changeable via the
-     * java.security.Policy.
-     * 
-     * @return ProtectionDomain the receiver's ProtectionDomain.
+     * Returns the {@code ProtectionDomain} of the class represented by this
+     * class.
+     * <p>
+     * Note: In order to conserve space in an embedded target like Android, we
+     * allow this method to return {@code null} for classes in the system
+     * protection domain (that is, for system classes). System classes are
+     * always given full permissions (that is, AllPermission). This can not be
+     * changed through the {@link java.security.Policy} class.
+     * </p>
+     *
+     * @return the {@code ProtectionDomain} of the class represented by this
+     *         class.
+     * @throws SecurityException
+     *             if a security manager exists and it does not allow member
+     *             access.
      */
     public ProtectionDomain getProtectionDomain() {
         return null;
@@ -628,13 +735,14 @@
     }
 
     /**
-     * Answers a read-only stream on the contents of the resource specified by
-     * resName. The mapping between the resource name and the stream is managed
-     * by the class' class loader.
-     * 
+     * Returns the URL of the resource specified by {@code resName}. The mapping
+     * between the resource name and the URL is managed by the class' class
+     * loader.
+     *
      * @param resName
      *            the name of the resource.
-     * @return a stream on the resource.
+     * @return the requested resource's {@code URL} object or {@code null} if
+     *         the resource can not be found.
      * @see ClassLoader
      */
     public URL getResource(String resName) {
@@ -642,13 +750,14 @@
     }
 
     /**
-     * Answers a read-only stream on the contents of the resource specified by
-     * resName. The mapping between the resource name and the stream is managed
-     * by the class' class loader.
-     * 
+     * Returns a read-only stream for the contents of the resource specified by
+     * {@code resName}. The mapping between the resource name and the stream is
+     * managed by the class' class loader.
+     *
      * @param resName
      *            the name of the resource.
-     * @return a stream on the resource.
+     * @return a stream for the requested resource or {@code null} if no
+     *         resource with the specified name can be found.
      * @see ClassLoader
      */
     public InputStream getResourceAsStream(String resName) {
@@ -656,31 +765,36 @@
     }
 
     /**
-     * Answers the signers for the class represented by the receiver, or null if
-     * there are no signers.
-     * 
-     * @return the signers of the receiver.
-     * @see #getMethods
+     * Returns the signers for the class represented by this {@code Class} or
+     * {@code null} if either there are no signers or this {@code Class}
+     * represents a primitive type or void.
+     *
+     * @return the signers of the class represented by this {@code Class}.
      */
     public Object[] getSigners() {
         return new Object[0];
     }
 
     /**
-     * Answers the Class which represents the receiver's superclass. For Classes
-     * which represent base types, interfaces, and for {@link Object} the method
-     * answers null.
-     * 
-     * @return the receiver's superclass.
+     * Returns the {@code Class} object which represents the superclass of the
+     * class represented by this {@code Class}. If this {@code Class} represents
+     * the {@code Object} class, a primitive type, an interface or void then the
+     * method returns {@code null}. If this {@code Class} represents an array
+     * class then the {@code Object} class is returned.
+     *
+     * @return the superclass of the class represented by this {@code Class}.
      */
     public Class<? super T> getSuperclass() {
         return null;
     }
 
     /**
-     * Gets the type variables associated with this class.
-     * 
-     * @return An array of {@link TypeVariable} instances.
+     * Returns an array containing {@code TypeVariable} objects for type
+     * variables declared by the generic class represented by this {@code
+     * Class}. Returns an empty array if the class is not generic.
+     *
+     * @return an array with the type variables of the class represented by this
+     *         class.
      * @since 1.5
      */
     @SuppressWarnings("unchecked")
@@ -689,23 +803,23 @@
     }
 
     /**
-     * Indicates whether or not this class is an annotation.
-     * 
-     * @return A value of <code>true</code> if this class is an annotation,
-     *         otherwise <code>false</code>.
-     * @since 1.5
+     * Indicates whether this {@code Class} represents an annotation class.
+     *
+     * @return {@code true} if this {@code Class} represents an annotation
+     *         class; {@code false} otherwise.
      */
     public boolean isAnnotation() {
         return false;
     }
 
     /**
-     * Indicates whether or not the given annotation is present for this class.
-     * 
+     * Indicates whether the specified annotation is present for the class
+     * represented by this {@code Class}.
+     *
      * @param annotationClass
-     *            The annotation to look for in this class.
-     * @return A value of <code>true</code> if the annotation is present,
-     *         otherwise <code>false</code>.
+     *            the annotation to look for.
+     * @return {@code true} if the class represented by this {@code Class} is
+     *         annotated with {@code annotationClass}; {@code false} otherwise.
      * @since 1.5
      */
     public boolean isAnnotationPresent(
@@ -714,10 +828,11 @@
     }
 
     /**
-     * Indicates whether or not this class was anonymously declared.
-     * 
-     * @return A value of <code>true</code> if this class is anonymous,
-     *         otherwise <code>false</code>.
+     * Indicates whether the class represented by this {@code Class} is
+     * anonymously declared.
+     *
+     * @return {@code true} if the class represented by this {@code Class} is
+     *         anonymous; {@code false} otherwise.
      * @since 1.5
      */
     public boolean isAnonymousClass() {
@@ -725,185 +840,188 @@
     }
 
     /**
-     * Answers true if the receiver represents an array class.
-     * 
-     * @return <code>true</code> if the receiver represents an array class
-     *         <code>false</code> if it does not represent an array class
+     * Indicates whether the class represented by this {@code Class} is an array
+     * class.
+     *
+     * @return {@code true} if the class represented by this {@code Class} is an
+     *         array class; {@code false} otherwise.
      */
     public boolean isArray() {
         return false;
     }
 
     /**
-     * Answers true if the type represented by the argument can be converted via
-     * an identity conversion or a widening reference conversion (i.e. if either
-     * the receiver or the argument represent primitive types, only the identity
-     * conversion applies).
-     * 
-     * @return <code>true</code> the argument can be assigned into the
-     *         receiver <code>false</code> the argument cannot be assigned
-     *         into the receiver
+     * Indicates whether the specified class type can be converted to the class
+     * represented by this {@code Class}. Conversion may be done via an identity
+     * conversion or a widening reference conversion (if either the receiver or
+     * the argument represent primitive types, only the identity conversion
+     * applies).
+     *
      * @param cls
-     *            Class the class to test
+     *            the class to check.
+     * @return {@code true} if {@code cls} can be converted to the class
+     *         represented by this {@code Class}; {@code false} otherwise.
      * @throws NullPointerException
-     *             if the parameter is null
+     *             if {@code cls} is {@code null}.
      */
     public boolean isAssignableFrom(Class<?> cls) {
         return false;
     }
 
     /**
-     * Indicates whether or not this class is an <code>enum</code>.
-     * 
-     * @return A value of <code>true</code> if this class is an {@link Enum},
-     *         otherwise <code>false</code>.
-     * @since 1.5
+     * Indicates whether the class represented by this {@code Class} is an
+     * {@code enum}.
+     *
+     * @return {@code true} if the class represented by this {@code Class} is an
+     *         {@code enum}; {@code false} otherwise.
      */
     public boolean isEnum() {
         return false;
     }
 
     /**
-     * Answers true if the argument is non-null and can be cast to the type of
-     * the receiver. This is the runtime version of the <code>instanceof</code>
-     * operator.
-     * 
-     * @return <code>true</code> the argument can be cast to the type of the
-     *         receiver <code>false</code> the argument is null or cannot be
-     *         cast to the type of the receiver
+     * Indicates whether the specified object can be cast to the class
+     * represented by this {@code Class}. This is the runtime version of the
+     * {@code instanceof} operator.
+     *
      * @param object
-     *            Object the object to test
+     *            the object to check.
+     * @return {@code true} if {@code object} can be cast to the type
+     *         represented by this {@code Class}; {@code false} if {@code
+     *         object} is {@code null} or cannot be cast.
      */
     public boolean isInstance(Object object) {
         return false;
     }
 
     /**
-     * Answers true if the receiver represents an interface.
-     * 
-     * @return <code>true</code> if the receiver represents an interface
-     *         <code>false</code> if it does not represent an interface
+     * Indicates whether this {@code Class} represents an interface.
+     *
+     * @return {@code true} if this {@code Class} represents an interface;
+     *         {@code false} otherwise.
      */
     public boolean isInterface() {
         return false;
     }
 
     /**
-     * Answers whether the receiver is defined locally.
-     * 
-     * @return <code>true</code> if the class is local, otherwise
-     *         <code>false</code>.
+     * Indicates whether the class represented by this {@code Class} is defined
+     * locally.
+     *
+     * @return {@code true} if the class represented by this {@code Class} is
+     *         defined locally; {@code false} otherwise.
      */
     public boolean isLocalClass() {
         return false;
     }
 
     /**
-     * Answers whether the receiver is a member class.
-     * 
-     * @return <code>true</code> if the class is a member class, otherwise
-     *         <code>false</code>.
+     * Indicates whether the class represented by this {@code Class} is a member
+     * class.
+     *
+     * @return {@code true} if the class represented by this {@code Class} is a
+     *         member class; {@code false} otherwise.
      */
     public boolean isMemberClass() {
         return false;
     }
 
     /**
-     * Answers true if the receiver represents a base type.
-     * 
-     * @return <code>true</code> if the receiver represents a base type
-     *         <code>false</code> if it does not represent a base type
+     * Indicates whether this {@code Class} represents a primitive type.
+     *
+     * @return {@code true} if this {@code Class} represents a primitive type;
+     *         {@code false} otherwise.
      */
     public boolean isPrimitive() {
         return false;
     }
 
     /**
-     * Answers whether the receiver is a synthetic type.
-     * 
-     * @return <code>true</code> if the receiver is a synthetic type and
-     *         <code>false</code> otherwise.
+     * Indicates whether this {@code Class} represents a synthetic type.
+     *
+     * @return {@code true} if this {@code Class} represents a synthetic type;
+     *         {@code false} otherwise.
      */
     public boolean isSynthetic() {
         return false;
     }
 
     /**
-     * Answers a new instance of the class represented by the receiver, created
-     * by invoking the default (i.e. zero-argument) constructor. If there is no
-     * such constructor, or if the creation fails (either because of a lack of
-     * available memory or because an exception is thrown by the constructor),
-     * an InstantiationException is thrown. If the default constructor exists,
-     * but is not accessible from the context where this message is sent, an
-     * IllegalAccessException is thrown.
-     * 
-     * @return a new instance of the class represented by the receiver.
+     * Returns a new instance of the class represented by this {@code Class},
+     * created by invoking the default (that is, zero-argument) constructor. If
+     * there is no such constructor, or if the creation fails (either because of
+     * a lack of available memory or because an exception is thrown by the
+     * constructor), an {@code InstantiationException} is thrown. If the default
+     * constructor exists but is not accessible from the context where this
+     * method is invoked, an {@code IllegalAccessException} is thrown.
+     *
+     * @return a new instance of the class represented by this {@code Class}.
      * @throws IllegalAccessException
-     *             if the constructor is not visible to the sender.
+     *             if the default constructor is not visible.
      * @throws InstantiationException
-     *             if the instance could not be created.
+     *             if the instance can not be created.
+     * @throws SecurityException
+     *             if a security manager exists and it does not allow creating
+     *             new instances.
      */
     public T newInstance() throws IllegalAccessException,
             InstantiationException {
         return null;
     }
 
-    /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver.
-     * 
-     * @return a printable representation for the receiver.
-     */
     @Override
     public String toString() {
         return null;
     }
 
     /**
-     * Returns the Package of which this class is a member. A class has a
-     * Package if it was loaded from a SecureClassLoader
-     * 
-     * @return Package the Package of which this class is a member or null
+     * Returns the {@code Package} of which the class represented by this
+     * {@code Class} is a member. Returns {@code null} if no {@code Package}
+     * object was created by the class loader of the class.
+     *
+     * @return Package the {@code Package} of which this {@code Class} is a
+     *         member or {@code null}.
      */
     public Package getPackage() {
         return null;
     }
 
     /**
-     * Returns the assertion status for this class. Assertion is
-     * enabled/disabled based on class loader default, package or class default
-     * at runtime
-     * 
-     * @return the assertion status for this class
+     * Returns the assertion status for the class represented by this {@code
+     * Class}. Assertion is enabled / disabled based on the class loader,
+     * package or class default at runtime.
+     *
+     * @return the assertion status for the class represented by this {@code
+     *         Class}.
      */
     public boolean desiredAssertionStatus() {
         return false;
     }
 
     /**
-     * Casts the receiver to a subclass of the given class. If successful
-     * answers the receiver, otherwise if the cast cannot be made throws a
-     * <code>ClassCastException</code>.
-     * 
+     * Casts this {@code Class} to represent a subclass of the specified class.
+     * If successful, this {@code Class} is returned; otherwise a {@code
+     * ClassCastException} is thrown.
+     *
      * @param clazz
      *            the required type.
-     * @return this class cast as a subclass of the given type.
+     * @return this {@code Class} cast as a subclass of the given type.
      * @throws ClassCastException
-     *             if the class cannot be cast to the given type.
+     *             if this {@code Class} cannot be cast to the specified type.
      */
     public <U> Class<? extends U> asSubclass(Class<U> clazz) {
         return null;
     }
 
     /**
-     * Cast the given object to the type <code>T</code>. If the object is
-     * <code>null</code> the result is also <code>null</code>.
-     * 
+     * Casts the specified object to the type represented by this {@code Class}.
+     * If the object is {@code null} then the result is also {@code null}.
+     *
      * @param obj
-     *            the object to cast
-     * @return The object that has been cast.
+     *            the object to cast.
+     * @return the object that has been cast.
      * @throws ClassCastException
-     *             if the object cannot be cast to the given type.
+     *             if the object cannot be cast to the specified type.
      */
     public T cast(Object obj) {
         return null;



Mime
View raw message