harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r767477 [5/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
Modified: harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Constructor.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Constructor.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Constructor.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Constructor.java Wed Apr 22 12:04:10 2009
@@ -20,13 +20,18 @@
 import java.lang.annotation.Annotation;
 
 /**
- * This class must be implemented by the VM vendor. This class models a
- * constructor. Information about the constructor can be accessed, and the
- * constructor can be invoked dynamically.
- * 
+ * This class represents a constructor. Information about the constructor can be
+ * accessed, and the constructor can be invoked dynamically.
+ *
+ * @param <T> the class that declares this constructor
  */
 public final class Constructor<T> extends AccessibleObject implements GenericDeclaration,
         Member {
+
+    /*
+     * This class must be implemented by the VM vendor.
+     */
+
     /**
      * Prevent this class from being instantiated
      */
@@ -39,12 +44,10 @@
     }
 
     /**
-     * <p>
-     * Returns the String representation of the constructor's declaration,
+     * Returns the string representation of the constructor's declaration,
      * including the type parameters.
-     * </p>
-     * 
-     * @return An instance of String.
+     *
+     * @return the string representation of the constructor's declaration
      * @since 1.5
      */
     public String toGenericString() {
@@ -52,19 +55,18 @@
     }
 
     /**
-     * <p>
-     * Gets the parameter types as an array of {@link Type} instances, in
-     * declaration order. If the constructor has no parameters, then an empty
-     * array is returned.
-     * </p>
-     * 
-     * @return An array of {@link Type} instances.
-     * @throws GenericSignatureFormatError if the generic method signature is
-     *         invalid.
-     * @throws TypeNotPresentException if the component type points to a missing
-     *         type.
-     * @throws MalformedParameterizedTypeException if the component type points
-     *         to a type that can't be instantiated for some reason.
+     * Returns the generic parameter types as an array of {@code Type}
+     * instances, in declaration order. If this constructor has no generic
+     * parameters, an empty array is returned.
+     *
+     * @return the parameter types
+     * @throws GenericSignatureFormatError
+     *             if the generic constructor signature is invalid
+     * @throws TypeNotPresentException
+     *             if any parameter type points to a missing type
+     * @throws MalformedParameterizedTypeException
+     *             if any parameter type points to a type that cannot be
+     *             instantiated for some reason
      * @since 1.5
      */
     public Type[] getGenericParameterTypes() {
@@ -72,18 +74,18 @@
     }
 
     /**
-     * <p>
-     * Gets the exception types as an array of {@link Type} instances. If the
-     * constructor has no declared exceptions, then an empty array is returned.
-     * </p>
-     * 
-     * @return An array of {@link Type} instances.
-     * @throws GenericSignatureFormatError if the generic method signature is
-     *         invalid.
-     * @throws TypeNotPresentException if the component type points to a missing
-     *         type.
-     * @throws MalformedParameterizedTypeException if the component type points
-     *         to a type that can't be instantiated for some reason.
+     * Returns the exception types as an array of {@code Type} instances. If
+     * this constructor has no declared exceptions, an empty array will be
+     * returned.
+     *
+     * @return an array of generic exception types
+     * @throws GenericSignatureFormatError
+     *             if the generic constructor signature is invalid
+     * @throws TypeNotPresentException
+     *             if any exception type points to a missing type
+     * @throws MalformedParameterizedTypeException
+     *             if any exception type points to a type that cannot be
+     *             instantiated for some reason
      * @since 1.5
      */
     public Type[] getGenericExceptionTypes() {
@@ -91,14 +93,12 @@
     }
 
     /**
-     * <p>
-     * Gets an array of arrays that represent the annotations of the formal
+     * Returns an array of arrays that represent the annotations of the formal
      * parameters of this constructor. If there are no parameters on this
      * constructor, then an empty array is returned. If there are no annotations
-     * set, then and array of empty arrays is returned.
-     * </p>
-     * 
-     * @return An array of arrays of {@link Annotation} instances.
+     * set, then an array of empty arrays is returned.
+     *
+     * @return an array of arrays of {@code Annotation} instances
      * @since 1.5
      */
     public Annotation[][] getParameterAnnotations() {
@@ -106,31 +106,39 @@
     }
 
     /**
-     * <p>
-     * Indicates whether or not this constructor takes a variable number
-     * argument.
-     * </p>
-     * 
-     * @return A value of <code>true</code> if a vararg is declare, otherwise
-     *         <code>false</code>.
+     * Indicates whether or not this constructor takes a variable number of
+     * arguments.
+     *
+     * @return {@code true} if a vararg is declare, otherwise
+     *         {@code false}
      * @since 1.5
      */
     public boolean isVarArgs() {
         return false;
     }
 
+    /**
+     * Indicates whether or not this constructor is synthetic (artificially
+     * introduced by the compiler).
+     *
+     * @return {@code true} if this constructor is synthetic, {@code false}
+     *         otherwise
+     */
     public boolean isSynthetic() {
         return false;
     }
 
     /**
-     * Compares the specified object to this Constructor and answer if they are
-     * equal. The object must be an instance of Constructor with the same
-     * defining class and parameter types.
-     * 
-     * @param object the object to compare
-     * @return true if the specified object is equal to this Constructor, false
-     *         otherwise
+     * Indicates whether or not the specified {@code object} is equal to this
+     * constructor. To be equal, the specified object must be an instance
+     * of {@code Constructor} with the same declaring class and parameter types
+     * as this constructor.
+     *
+     * @param object
+     *            the object to compare
+     *
+     * @return {@code true} if the specified object is equal to this
+     *         constructor, {@code false} otherwise
      * @see #hashCode
      */
     @Override
@@ -139,9 +147,8 @@
     }
 
     /**
-     * Return the {@link Class} associated with the class that defined this
-     * constructor.
-     * 
+     * Returns the class that declares this constructor.
+     *
      * @return the declaring class
      */
     public Class<T> getDeclaringClass() {
@@ -149,11 +156,10 @@
     }
 
     /**
-     * Return an array of the {@link Class} objects associated with the
-     * exceptions declared to be thrown by this constructor. If the constructor
-     * was not declared to throw any exceptions, the array returned will be
-     * empty.
-     * 
+     * Returns the exception types as an array of {@code Class} instances. If
+     * this constructor has no declared exceptions, an empty array will be
+     * returned.
+     *
      * @return the declared exception classes
      */
     public Class<?>[] getExceptionTypes() {
@@ -161,31 +167,30 @@
     }
 
     /**
-     * Return the modifiers for the modeled constructor. The Modifier class
+     * Returns the modifiers for this constructor. The {@link Modifier} class
      * should be used to decode the result.
-     * 
-     * @return the modifiers
-     * @see java.lang.reflect.Modifier
+     *
+     * @return the modifiers for this constructor
+     * @see Modifier
      */
     public int getModifiers() {
         return 0;
     }
 
     /**
-     * Return the name of the modeled constructor. This is the name of the
-     * declaring class.
-     * 
-     * @return the name
+     * Returns the name of this constructor.
+     *
+     * @return the name of this constructor
      */
     public String getName() {
         return null;
     }
 
     /**
-     * Return an array of the {@link Class} objects associated with the
+     * Returns an array of the {@code Class} objects associated with the
      * parameter types of this constructor. If the constructor was declared with
-     * no parameters, the array returned will be empty.
-     * 
+     * no parameters, an empty array will be returned.
+     *
      * @return the parameter types
      */
     public Class<?>[] getParameterTypes() {
@@ -193,11 +198,11 @@
     }
 
     /**
-     * Answers an integer hash code for the receiver. Objects which are equal
-     * answer the same value for this method. The hash code for a Constructor is
-     * the hash code of the declaring class' name.
-     * 
-     * @return the receiver's hash
+     * Returns an integer hash code for this constructor. Constructors which are
+     * equal return the same value for this method. The hash code for a
+     * Constructor is the hash code of the name of the declaring class.
+     *
+     * @return the hash code
      * @see #equals
      */
     @Override
@@ -206,45 +211,50 @@
     }
 
     /**
-     * Return a new instance of the declaring class, initialized by dynamically
-     * invoking the modeled constructor. This reproduces the effect of
-     * <code>new declaringClass(arg1, arg2, ... , argN)</code> This method
-     * performs the following:
+     * Returns a new instance of the declaring class, initialized by dynamically
+     * invoking the constructor represented by this {@code Constructor} object.
+     * This reproduces the effect of {@code new declaringClass(arg1, arg2, ... ,
+     * argN)} This method performs the following:
      * <ul>
      * <li>A new instance of the declaring class is created. If the declaring
      * class cannot be instantiated (i.e. abstract class, an interface, an array
-     * type, or a base type) then an InstantiationException is thrown.</li>
+     * type, or a primitive type) then an InstantiationException is thrown.</li>
      * <li>If this Constructor object is enforcing access control (see
-     * AccessibleObject) and the modeled constructor is not accessible from the
+     * {@link AccessibleObject}) and this constructor is not accessible from the
      * current context, an IllegalAccessException is thrown.</li>
-     * <li>If the number of arguments passed and the number of parameters do
-     * not match, an IllegalArgumentException is thrown.</li>
+     * <li>If the number of arguments passed and the number of parameters do not
+     * match, an IllegalArgumentException is thrown.</li>
      * <li>For each argument passed:
      * <ul>
-     * <li>If the corresponding parameter type is a base type, the argument is
-     * unwrapped. If the unwrapping fails, an IllegalArgumentException is
+     * <li>If the corresponding parameter type is a primitive type, the argument
+     * is unwrapped. If the unwrapping fails, an IllegalArgumentException is
      * thrown.</li>
      * <li>If the resulting argument cannot be converted to the parameter type
      * via a widening conversion, an IllegalArgumentException is thrown.</li>
      * </ul>
-     * <li>The modeled constructor is then invoked. If an exception is thrown
-     * during the invocation, it is caught and wrapped in an
-     * InvocationTargetException. This exception is then thrown. If the
-     * invocation completes normally, the newly initialized object is returned.
+     * <li>The constructor represented by this {@code Constructor} object is
+     * then invoked. If an exception is thrown during the invocation, it is
+     * caught and wrapped in an InvocationTargetException. This exception is
+     * then thrown. If the invocation completes normally, the newly initialized
+     * object is returned.
      * </ul>
-     * 
-     * @param args the arguments to the constructor
+     *
+     * @param args
+     *            the arguments to the constructor
+     *
      * @return the new, initialized, object
-     * @exception java.lang.InstantiationException if the class cannot be
-     *            instantiated
-     * @exception java.lang.IllegalAccessException if the modeled constructor
-     *            is not accessible
-     * @exception java.lang.IllegalArgumentException if an incorrect number of
-     *            arguments are passed, or an argument could not be converted by
-     *            a widening conversion
-     * @exception java.lang.reflect.InvocationTargetException if an exception
-     *            was thrown by the invoked constructor
-     * @see java.lang.reflect.AccessibleObject
+     *
+     * @exception InstantiationException
+     *                if the class cannot be instantiated
+     * @exception IllegalAccessException
+     *                if this constructor is not accessible
+     * @exception IllegalArgumentException
+     *                if an incorrect number of arguments are passed, or an
+     *                argument could not be converted by a widening conversion
+     * @exception InvocationTargetException
+     *                if an exception was thrown by the invoked constructor
+     *
+     * @see AccessibleObject
      */
     public T newInstance(Object... args) throws InstantiationException, IllegalAccessException,
             IllegalArgumentException, InvocationTargetException {
@@ -252,13 +262,22 @@
     }
 
     /**
-     * Answers a string containing a concise, human-readable description of the
-     * receiver. The format of the string is modifiers (if any) declaring class
-     * name '(' parameter types, separated by ',' ')' If the constructor throws
-     * exceptions, ' throws ' exception types, separated by ',' For example:
-     * <code>public String(byte[],String) throws UnsupportedEncodingException</code>
-     * 
-     * @return a printable representation for the receiver
+     * Returns a string containing a concise, human-readable description of this
+     * constructor. The format of the string is:
+     *
+     * <ol>
+     *   <li>modifiers (if any)
+     *   <li>declaring class name
+     *   <li>'('
+     *   <li>parameter types, separated by ',' (if any)
+     *   <li>')'
+     *   <li>'throws' plus exception types, separated by ',' (if any)
+     * </ol>
+     *
+     * For example:
+     * {@code public String(byte[],String) throws UnsupportedEncodingException}
+     *
+     * @return a printable representation for this constructor
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Field.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Field.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Field.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Field.java Wed Apr 22 12:04:10 2009
@@ -18,13 +18,15 @@
 package java.lang.reflect;
 
 /**
- * This class must be implemented by the VM vendor. This class models a field.
- * Information about the field can be accessed, and the field's value can be
- * accessed dynamically.
- * 
+ * This class represents a field. Information about the field can be accessed,
+ * and the field's value can be accessed dynamically.
  */
 public final class Field extends AccessibleObject implements Member {
-    
+
+    /*
+     * This class must be implemented by the VM vendor.
+     */
+
     /**
      * Prevent this class from being instantiated
      */
@@ -33,23 +35,28 @@
     }
 
     /**
-     * <p>TODO Document this method. Is it used?</p>
-     * @return
-     * @see java.lang.reflect.AccessibleObject#getSignature()
+     * Returns the field's signature in non-printable form. This is called
+     * (only) from IO native code and needed for deriving the serialVersionUID
+     * of the class
+     *
+     * @return the field's signature.
      */
     native String getSignature();
-    
+
+    /**
+     * Indicates whether or not this field is synthetic.
+     *
+     * @return {@code true} if this field is synthetic, {@code false} otherwise
+     */
     public boolean isSynthetic() {
         return false;
     }
 
     /**
-     * <p>
-     * Returns the String representation of the field's declaration, including
-     * the type parameters.
-     * </p>
-     * 
-     * @return An instance of String.
+     * Returns the string representation of this field, including the field's
+     * generic type.
+     *
+     * @return the string representation of this field
      * @since 1.5
      */
     public String toGenericString() {
@@ -57,12 +64,10 @@
     }
 
     /**
-     * <p>
      * Indicates whether or not this field is an enumeration constant.
-     * </p>
-     * 
-     * @return A value of <code>true</code> if this field is an enumeration
-     *         constant, otherwise <code>false</code>.
+     *
+     * @return {@code true} if this field is an enumeration constant, {@code
+     *         false} otherwise
      * @since 1.5
      */
     public boolean isEnumConstant() {
@@ -70,31 +75,31 @@
     }
 
     /**
-     * <p>
-     * Gets the declared type of this field.
-     * </p>
-     * 
-     * @return An instance of {@link Type}.
-     * @throws GenericSignatureFormatError if the generic method signature is
-     *         invalid.
-     * @throws TypeNotPresentException if the component type points to a missing
-     *         type.
-     * @throws MalformedParameterizedTypeException if the component type points
-     *         to a type that can't be instantiated for some reason.
+     * Returns the generic type of this field.
+     *
+     * @return the generic type
+     * @throws GenericSignatureFormatError
+     *             if the generic field signature is invalid
+     * @throws TypeNotPresentException
+     *             if the generic type points to a missing type
+     * @throws MalformedParameterizedTypeException
+     *             if the generic type points to a type that cannot be
+     *             instantiated for some reason
      * @since 1.5
      */
     public Type getGenericType() {
         return null;
     }
-    
-	/**
-     * Compares the specified object to this Field and answer if they are equal.
-     * The object must be an instance of Field with the same defining class and
-     * name.
-     * 
-     * @param object the object to compare
-     * @return true if the specified object is equal to this Field, false
-     *         otherwise
+
+    /**
+     * Indicates whether or not the specified {@code object} is equal to this
+     * field. To be equal, the specified object must be an instance of
+     * {@code Field} with the same declaring class, type and name as this field.
+     *
+     * @param object
+     *            the object to compare
+     * @return {@code true} if the specified object is equal to this method,
+     *         {@code false} otherwise
      * @see #hashCode
      */
 	@Override
@@ -102,585 +107,587 @@
 		return false;
 	}
 
-	/**
-	 * Return the value of the field in the specified object. This reproduces
-	 * the effect of <code>object.fieldName</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * The value of the field is returned. If the type of this field is a base
-	 * type, the field value is automatically wrapped.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @return the field value, possibly wrapped
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Returns the value of the field in the specified object. This reproduces
+     * the effect of {@code object.fieldName}
+     * <p>
+     * If the type of this field is a primitive type, the field value is
+     * automatically wrapped.
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is null, a NullPointerException is thrown. If
+     * the object is not an instance of the declaring class of the method, an
+     * IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @return the field value, possibly wrapped
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native Object get(Object object) throws IllegalAccessException,
 			IllegalArgumentException;
 
-	/**
-	 * Return the value of the field in the specified object as a boolean. This
-	 * reproduces the effect of <code>object.fieldName</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @return the field value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Returns the value of the field in the specified object as a {@code
+     * boolean}. This reproduces the effect of {@code object.fieldName}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @return the field value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native boolean getBoolean(Object object)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Return the value of the field in the specified object as a byte. This
-	 * reproduces the effect of <code>object.fieldName</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @return the field value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Returns the value of the field in the specified object as a {@code byte}.
+     * This reproduces the effect of {@code object.fieldName}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @return the field value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native byte getByte(Object object) throws IllegalAccessException,
 			IllegalArgumentException;
 
-	/**
-	 * Return the value of the field in the specified object as a char. This
-	 * reproduces the effect of <code>object.fieldName</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @return the field value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Returns the value of the field in the specified object as a {@code char}.
+     * This reproduces the effect of {@code object.fieldName}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @return the field value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native char getChar(Object object) throws IllegalAccessException,
 			IllegalArgumentException;
 
-	/**
-	 * Return the {@link Class} associated with the class that defined this
-	 * field.
-	 * 
-	 * @return the declaring class
-	 */
+    /**
+     * Returns the class that declares this field.
+     *
+     * @return the declaring class
+     */
 	public Class<?> getDeclaringClass() {
 		return null;
 	}
 
-	/**
-	 * Return the value of the field in the specified object as a double. This
-	 * reproduces the effect of <code>object.fieldName</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @return the field value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Returns the value of the field in the specified object as a {@code
+     * double}. This reproduces the effect of {@code object.fieldName}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @return the field value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native double getDouble(Object object)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Return the value of the field in the specified object as a float. This
-	 * reproduces the effect of <code>object.fieldName</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @return the field value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Returns the value of the field in the specified object as a {@code float}.
+     * This reproduces the effect of {@code object.fieldName}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @return the field value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native float getFloat(Object object) throws IllegalAccessException,
 			IllegalArgumentException;
 
-	/**
-	 * Return the value of the field in the specified object as an int. This
-	 * reproduces the effect of <code>object.fieldName</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @return the field value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Returns the value of the field in the specified object as an {@code int}.
+     * This reproduces the effect of {@code object.fieldName}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @return the field value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native int getInt(Object object) throws IllegalAccessException,
 			IllegalArgumentException;
 
-	/**
-	 * Return the value of the field in the specified object as a long. This
-	 * reproduces the effect of <code>object.fieldName</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @return the field value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Returns the value of the field in the specified object as a {@code long}.
+     * This reproduces the effect of {@code object.fieldName}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @return the field value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native long getLong(Object object) throws IllegalAccessException,
 			IllegalArgumentException;
 
-	/**
-	 * Return the modifiers for the modeled field. The Modifier class should be
-	 * used to decode the result.
-	 * 
-	 * @return the modifiers
-	 * @see java.lang.reflect.Modifier
-	 */
+    /**
+     * Returns the modifiers for this field. The {@link Modifier} class should
+     * be used to decode the result.
+     *
+     * @return the modifiers for this field
+     * @see Modifier
+     */
 	public native int getModifiers();
 
-	/**
-	 * Return the name of the modeled field.
-	 * 
-	 * @return the name
-	 */
+    /**
+     * Returns the name of this field.
+     *
+     * @return the name of this field
+     */
 	public String getName() {
 		return null;
 	}
 
-	/**
-	 * Return the value of the field in the specified object as a short. This
-	 * reproduces the effect of <code>object.fieldName</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @return the field value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Returns the value of the field in the specified object as a {@code short}
+     * . This reproduces the effect of {@code object.fieldName}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @return the field value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native short getShort(Object object) throws IllegalAccessException,
 			IllegalArgumentException;
 
-	/**
-	 * Return the {@link Class} associated with the type of this field.
-	 * 
-	 * @return the type
-	 */
+    /**
+     * Return the {@link Class} associated with the type of this field.
+     *
+     * @return the type of this field
+     */
 	public Class<?> getType() {
 		return null;
 	}
 
-	/**
-	 * Answers an integer hash code for the receiver. Objects which are equal
-	 * answer the same value for this method.
-	 * <p>
-	 * The hash code for a Field is the hash code of the field's name.
-	 * 
-	 * @return the receiver's hash
-	 * @see #equals
-	 */
+    /**
+     * Returns an integer hash code for this field. Objects which are equal
+     * return the same value for this method.
+     * <p>
+     * The hash code for a Field is the exclusive-or combination of the hash
+     * code of the field's name and the hash code of the name of its declaring
+     * class.
+     *
+     * @return the hash code for this field
+     * @see #equals
+     */
 	@Override
     public int hashCode() {
 		return 0;
 	}
 
-	/**
-	 * Set the value of the field in the specified object to the boolean value.
-	 * This reproduces the effect of <code>object.fieldName = value</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * If the field type is a base type, the value is automatically unwrapped.
-	 * If the unwrap fails, an IllegalArgumentException is thrown. If the value
-	 * cannot be converted to the field type via a widening conversion, an
-	 * IllegalArgumentException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @param value
-	 *            the new value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Sets the value of the field in the specified object to the value. This
+     * reproduces the effect of {@code object.fieldName = value}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     * <p>
+     * If the field type is a primitive type, the value is automatically
+     * unwrapped. If the unwrap fails, an IllegalArgumentException is thrown. If
+     * the value cannot be converted to the field type via a widening
+     * conversion, an IllegalArgumentException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native void set(Object object, Object value)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Set the value of the field in the specified object to the boolean value.
-	 * This reproduces the effect of <code>object.fieldName = value</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * If the value cannot be converted to the field type via a widening
-	 * conversion, an IllegalArgumentException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @param value
-	 *            the new value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Sets the value of the field in the specified object to the {@code
+     * boolean} value. This reproduces the effect of {@code object.fieldName =
+     * value}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     * <p>
+     * If the value cannot be converted to the field type via a widening
+     * conversion, an IllegalArgumentException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native void setBoolean(Object object, boolean value)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Set the value of the field in the specified object to the byte value.
-	 * This reproduces the effect of <code>object.fieldName = value</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * If the value cannot be converted to the field type via a widening
-	 * conversion, an IllegalArgumentException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @param value
-	 *            the new value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Sets the value of the field in the specified object to the {@code byte}
+     * value. This reproduces the effect of {@code object.fieldName = value}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     * <p>
+     * If the value cannot be converted to the field type via a widening
+     * conversion, an IllegalArgumentException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native void setByte(Object object, byte value)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Set the value of the field in the specified object to the char value.
-	 * This reproduces the effect of <code>object.fieldName = value</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * If the value cannot be converted to the field type via a widening
-	 * conversion, an IllegalArgumentException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @param value
-	 *            the new value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Sets the value of the field in the specified object to the {@code char}
+     * value. This reproduces the effect of {@code object.fieldName = value}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     * <p>
+     * If the value cannot be converted to the field type via a widening
+     * conversion, an IllegalArgumentException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native void setChar(Object object, char value)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Set the value of the field in the specified object to the double value.
-	 * This reproduces the effect of <code>object.fieldName = value</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * If the value cannot be converted to the field type via a widening
-	 * conversion, an IllegalArgumentException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @param value
-	 *            the new value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Sets the value of the field in the specified object to the {@code double}
+     * value. This reproduces the effect of {@code object.fieldName = value}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     * <p>
+     * If the value cannot be converted to the field type via a widening
+     * conversion, an IllegalArgumentException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native void setDouble(Object object, double value)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Set the value of the field in the specified object to the float value.
-	 * This reproduces the effect of <code>object.fieldName = value</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * If the value cannot be converted to the field type via a widening
-	 * conversion, an IllegalArgumentException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @param value
-	 *            the new value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Sets the value of the field in the specified object to the {@code float}
+     * value. This reproduces the effect of {@code object.fieldName = value}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     * <p>
+     * If the value cannot be converted to the field type via a widening
+     * conversion, an IllegalArgumentException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native void setFloat(Object object, float value)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Set the value of the field in the specified object to the int value. This
-	 * reproduces the effect of <code>object.fieldName = value</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * If the value cannot be converted to the field type via a widening
-	 * conversion, an IllegalArgumentException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @param value
-	 *            the new value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Set the value of the field in the specified object to the {@code int}
+     * value. This reproduces the effect of {@code object.fieldName = value}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     * <p>
+     * If the value cannot be converted to the field type via a widening
+     * conversion, an IllegalArgumentException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native void setInt(Object object, int value)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Set the value of the field in the specified object to the long value.
-	 * This reproduces the effect of <code>object.fieldName = value</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * If the value cannot be converted to the field type via a widening
-	 * conversion, an IllegalArgumentException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @param value
-	 *            the new value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Sets the value of the field in the specified object to the {@code long}
+     * value. This reproduces the effect of {@code object.fieldName = value}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     * <p>
+     * If the value cannot be converted to the field type via a widening
+     * conversion, an IllegalArgumentException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native void setLong(Object object, long value)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Set the value of the field in the specified object to the short value.
-	 * This reproduces the effect of <code>object.fieldName = value</code>
-	 * <p>
-	 * If the modeled field is static, the object argument is ignored.
-	 * Otherwise, if the object is null, a NullPointerException is thrown. If
-	 * the object is not an instance of the declaring class of the method, an
-	 * IllegalArgumentException is thrown.
-	 * <p>
-	 * If this Field object is enforcing access control (see AccessibleObject)
-	 * and the modeled field is not accessible from the current context, an
-	 * IllegalAccessException is thrown.
-	 * <p>
-	 * If the value cannot be converted to the field type via a widening
-	 * conversion, an IllegalArgumentException is thrown.
-	 * 
-	 * @param object
-	 *            the object to access
-	 * @param value
-	 *            the new value
-	 * @throws NullPointerException
-	 *             if the object is null and the field is non-static
-	 * @throws IllegalArgumentException
-	 *             if the object is not compatible with the declaring class
-	 * @throws IllegalAccessException
-	 *             if modeled field is not accessible
-	 */
+    /**
+     * Sets the value of the field in the specified object to the {@code short}
+     * value. This reproduces the effect of {@code object.fieldName = value}
+     * <p>
+     * If this field is static, the object argument is ignored.
+     * Otherwise, if the object is {@code null}, a NullPointerException is
+     * thrown. If the object is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.
+     * <p>
+     * If this Field object is enforcing access control (see AccessibleObject)
+     * and this field is not accessible from the current context, an
+     * IllegalAccessException is thrown.
+     * <p>
+     * If the value cannot be converted to the field type via a widening
+     * conversion, an IllegalArgumentException is thrown.
+     *
+     * @param object
+     *            the object to access
+     * @param value
+     *            the new value
+     * @throws NullPointerException
+     *             if the object is {@code null} and the field is non-static
+     * @throws IllegalArgumentException
+     *             if the object is not compatible with the declaring class
+     * @throws IllegalAccessException
+     *             if this field is not accessible
+     */
 	public native void setShort(Object object, short value)
 			throws IllegalAccessException, IllegalArgumentException;
 
-	/**
-	 * Answers a string containing a concise, human-readable description of the
-	 * receiver.
-	 * <p>
-	 * The format of the string is:
-	 * <ul>
-	 * <li>modifiers (if any)
-	 * <li>return type
-	 * <li>declaring class name
-	 * <li>'.'
-	 * <li>field name
-	 * </ul>
-	 * <p>
-	 * For example:
-	 * <code>public static java.io.InputStream java.lang.System.in</code>
-	 * 
-	 * @return a printable representation for the receiver
-	 */
+    /**
+     * Returns a string containing a concise, human-readable description of this
+     * field.
+     * <p>
+     * The format of the string is:
+     * <ol>
+     *   <li>modifiers (if any)
+     *   <li>type
+     *   <li>declaring class name
+     *   <li>'.'
+     *   <li>field name
+     * </ol>
+     * <p>
+     * For example: {@code public static java.io.InputStream
+     * java.lang.System.in}
+     *
+     * @return a printable representation for this field
+     */
+    @Override
 	public String toString() {
 		return null;
 	}

Modified: harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Method.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Method.java?rev=767477&r1=767476&r2=767477&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Method.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni-kernel/src/main/java/java/lang/reflect/Method.java Wed Apr 22 12:04:10 2009
@@ -20,13 +20,15 @@
 import java.lang.annotation.Annotation;
 
 /**
- * This class must be implemented by the VM vendor. This class models a method.
- * Information about the method can be accessed, and the method can be invoked
- * dynamically.
- * 
+ * This class represents a method. Information about the method can be accessed,
+ * and the method can be invoked dynamically.
  */
 public final class Method extends AccessibleObject implements GenericDeclaration, Member {
-    
+
+    /*
+     * This class must be implemented by the VM vendor.
+     */
+
     /**
      * Prevent this class from being instantiated
      */
@@ -39,12 +41,10 @@
     }
 
     /**
-     * <p>
-     * Returns the String representation of the method's declaration, including
+     * Returns the string representation of the method's declaration, including
      * the type parameters.
-     * </p>
-     * 
-     * @return An instance of String.
+     *
+     * @return the string representation of this method
      * @since 1.5
      */
     public String toGenericString() {
@@ -52,19 +52,19 @@
     }
 
     /**
-     * <p>
-     * Gets the parameter types as an array of {@link Type} instances, in
-     * declaration order. If the method has no parameters, then an empty array
-     * is returned.
-     * </p>
-     * 
-     * @return An array of {@link Type} instances.
-     * @throws GenericSignatureFormatError if the generic method signature is
-     *         invalid.
-     * @throws TypeNotPresentException if the component type points to a missing
-     *         type.
-     * @throws MalformedParameterizedTypeException if the component type points
-     *         to a type that can't be instantiated for some reason.
+     * Returns the parameter types as an array of {@code Type} instances, in
+     * declaration order. If this method has no parameters, an empty array is
+     * returned.
+     *
+     * @return the parameter types
+     *
+     * @throws GenericSignatureFormatError
+     *             if the generic method signature is invalid
+     * @throws TypeNotPresentException
+     *             if any parameter type points to a missing type
+     * @throws MalformedParameterizedTypeException
+     *             if any parameter type points to a type that cannot be
+     *             instantiated for some reason
      * @since 1.5
      */
     public Type[] getGenericParameterTypes() {
@@ -72,18 +72,18 @@
     }
 
     /**
-     * <p>
-     * Gets the exception types as an array of {@link Type} instances. If the
-     * method has no declared exceptions, then an empty array is returned.
-     * </p>
-     * 
-     * @return An array of {@link Type} instances.
-     * @throws GenericSignatureFormatError if the generic method signature is
-     *         invalid.
-     * @throws TypeNotPresentException if the component type points to a missing
-     *         type.
-     * @throws MalformedParameterizedTypeException if the component type points
-     *         to a type that can't be instantiated for some reason.
+     * Returns the exception types as an array of {@code Type} instances. If
+     * this method has no declared exceptions, an empty array will be returned.
+     *
+     * @return an array of generic exception types
+     *
+     * @throws GenericSignatureFormatError
+     *             if the generic method signature is invalid
+     * @throws TypeNotPresentException
+     *             if any exception type points to a missing type
+     * @throws MalformedParameterizedTypeException
+     *             if any exception type points to a type that cannot be
+     *             instantiated for some reason
      * @since 1.5
      */
     public Type[] getGenericExceptionTypes() {
@@ -91,17 +91,17 @@
     }
 
     /**
-     * <p>
-     * Gets the return type as a {@link Type} instance.
-     * </p>
-     * 
-     * @return A {@link Type} instance.
-     * @throws GenericSignatureFormatError if the generic method signature is
-     *         invalid.
-     * @throws TypeNotPresentException if the component type points to a missing
-     *         type.
-     * @throws MalformedParameterizedTypeException if the component type points
-     *         to a type that can't be instantiated for some reason.
+     * Returns the return type of this method as a {@code Type} instance.
+     *
+     * @return the return type of this method
+     *
+     * @throws GenericSignatureFormatError
+     *             if the generic method signature is invalid
+     * @throws TypeNotPresentException
+     *             if the return type points to a missing type
+     * @throws MalformedParameterizedTypeException
+     *             if the return type points to a type that cannot be
+     *             instantiated for some reason
      * @since 1.5
      */
     public Type getGenericReturnType() {
@@ -109,14 +109,12 @@
     }
 
     /**
-     * <p>
-     * Gets an array of arrays that represent the annotations of the formal
+     * Returns an array of arrays that represent the annotations of the formal
      * parameters of this method. If there are no parameters on this method,
      * then an empty array is returned. If there are no annotations set, then
      * and array of empty arrays is returned.
-     * </p>
-     * 
-     * @return An array of arrays of {@link Annotation} instances.
+     *
+     * @return an array of arrays of {@code Annotation} instances
      * @since 1.5
      */
     public Annotation[][] getParameterAnnotations() {
@@ -124,12 +122,9 @@
     }
 
     /**
-     * <p>
      * Indicates whether or not this method takes a variable number argument.
-     * </p>
-     * 
-     * @return A value of <code>true</code> if a vararg is declare, otherwise
-     *         <code>false</code>.
+     *
+     * @return {@code true} if a vararg is declared, {@code false} otherwise
      * @since 1.5
      */
     public boolean isVarArgs() {
@@ -137,197 +132,214 @@
     }
 
     /**
-     * <p>
      * Indicates whether or not this method is a bridge.
-     * </p>
-     * 
-     * @return A value of <code>true</code> if this method's a bridge,
-     *         otherwise <code>false</code>.
+     *
+     * @return {@code true} if this method is a bridge, {@code false} otherwise
      * @since 1.5
      */
     public boolean isBridge() {
         return false;
     }
 
+    /**
+     * Indicates whether or not this method is synthetic.
+     *
+     * @return {@code true} if this method is synthetic, {@code false} otherwise
+     */
     public boolean isSynthetic() {
         return false;
     }
-    
+
     /**
-     * <p>Gets the default value for the annotation member represented by
-     * this method.</p>
-     * @return The default value or <code>null</code> if none.
-     * @throws TypeNotPresentException if the annotation is of type {@link Class}
-     * and no definition can be found.
+     * Returns the default value for the annotation member represented by this
+     * method.
+     *
+     * @return the default value, or {@code null} if none
+     *
+     * @throws TypeNotPresentException
+     *             if this annotation member is of type {@code Class} and no
+     *             definition can be found
      * @since 1.5
      */
     public Object getDefaultValue() {
         return null;
     }
-    
-	/**
-	 * Compares the specified object to this Method and answer if they are
-	 * equal. The object must be an instance of Method with the same defining
-	 * class and parameter types.
-	 * 
-	 * @param object
-	 *            the object to compare
-	 * @return true if the specified object is equal to this Method, false
-	 *         otherwise
-	 * @see #hashCode
-	 */
-	@Override
+
+    /**
+     * Indicates whether or not the specified {@code object} is equal to this
+     * method. To be equal, the specified object must be an instance
+     * of {@code Method} with the same declaring class and parameter types
+     * as this method.
+     *
+     * @param object
+     *            the object to compare
+     * @return {@code true} if the specified object is equal to this
+     *         method, {@code false} otherwise
+     * @see #hashCode
+     */
+    @Override
     public boolean equals(Object object) {
 		return false;
 	}
 
-	/**
-	 * Return the {@link Class} associated with the class that defined this
-	 * method.
-	 * 
-	 * @return the declaring class
-	 */
+    /**
+     * Returns the class that declares this method.
+     *
+     * @return the declaring class
+     */
 	public Class<?> getDeclaringClass() {
 		return null;
 	}
 
-	/**
-	 * Return an array of the {@link Class} objects associated with the
-	 * exceptions declared to be thrown by this method. If the method was not
-	 * declared to throw any exceptions, the array returned will be empty.
-	 * 
-	 * @return the declared exception classes
-	 */
+    /**
+     * Returns the exception types as an array of {@code Class} instances. If
+     * this method has no declared exceptions, an empty array is returned.
+     *
+     * @return the declared exception classes
+     */
 	public Class<?>[] getExceptionTypes() {
 		return null;
 	}
 
-	/**
-	 * Return the modifiers for the modeled method. The Modifier class
-	 * should be used to decode the result.
-	 * 
-	 * @return the modifiers
-	 * @see java.lang.reflect.Modifier
-	 */
+    /**
+     * Returns the modifiers for this method. The {@link Modifier} class should
+     * be used to decode the result.
+     *
+     * @return the modifiers for this method
+     *
+     * @see Modifier
+     */
     public int getModifiers() {
 		return 0;
 	}
 
-	/**
-	 * Return the name of the modeled method.
-	 * 
-	 * @return the name
-	 */
+    /**
+     * Returns the name of the method represented by this {@code Method}
+     * instance.
+     *
+     * @return the name of this method
+     */
 	public String getName() {
 		return null;
 	}
 
-	/**
-	 * Return an array of the {@link Class} objects associated with the
-	 * parameter types of this method. If the method was declared with no
-	 * parameters, the array returned will be empty.
-	 * 
-	 * @return the parameter types
-	 */
+    /**
+     * Returns an array of {@code Class} objects associated with the parameter
+     * types of this method. If the method was declared with no parameters, an
+     * empty array will be returned.
+     *
+     * @return the parameter types
+     */
 	public Class<?>[] getParameterTypes() {
 		return null;
 	}
 
-	/**
-	 * Return the {@link Class} associated with the return type of this
-	 * method.
-	 * 
-	 * @return the return type
-	 */
+    /**
+     * Returns the {@code Class} associated with the return type of this
+     * method.
+     *
+     * @return the return type
+     */
 	public Class<?> getReturnType() {
 		return null;
 	}
 
-	/**
-	 * Answers an integer hash code for the receiver. Objects which are equal
-	 * answer the same value for this method. The hash code for a Method is the
-	 * hash code of the method's name.
-	 * 
-	 * @return the receiver's hash
-	 * @see #equals
-	 */
+    /**
+     * Returns an integer hash code for this method. Objects which are equal
+     * return the same value for this method. The hash code for this Method is
+     * the hash code of the name of this method.
+     *
+     * @return hash code for this method
+     *
+     * @see #equals
+     */
 	@Override
     public int hashCode() {
 		return 0;
 	}
 
-	/**
-	 * Return the result of dynamically invoking the modeled method. This
-	 * reproduces the effect of
-	 * <code>receiver.methodName(arg1, arg2, ... , argN)</code> This method
-	 * performs the following:
-	 * <ul>
-	 * <li>If the modeled method is static, the receiver argument is ignored.
-	 * </li>
-	 * <li>Otherwise, if the receiver is null, a NullPointerException is
-	 * thrown.</li>
-	 * If the receiver is not an instance of the declaring class of the method,
-	 * an IllegalArgumentException is thrown.
-	 * <li>If this Method object is enforcing access control (see
-	 * AccessibleObject) and the modeled method is not accessible from the
-	 * current context, an IllegalAccessException is thrown.</li>
-	 * <li>If the number of arguments passed and the number of parameters do
-	 * not match, an IllegalArgumentException is thrown.</li>
-	 * <li>For each argument passed:
-	 * <ul>
-	 * <li>If the corresponding parameter type is a base type, the argument is
-	 * unwrapped. If the unwrapping fails, an IllegalArgumentException is
-	 * thrown.</li>
-	 * <li>If the resulting argument cannot be converted to the parameter type
-	 * via a widening conversion, an IllegalArgumentException is thrown.</li>
-	 * </ul>
-	 * <li>If the modeled method is static, it is invoked directly. If it is
-	 * non-static, the modeled method and the receiver are then used to perform
-	 * a standard dynamic method lookup. The resulting method is then invoked.
-	 * </li>
-	 * <li>If an exception is thrown during the invocation it is caught and
-	 * wrapped in an InvocationTargetException. This exception is then thrown.
-	 * </li>
-	 * <li>If the invocation completes normally, the return value is itself
-	 * returned. If the method is declared to return a base type, the return
-	 * value is first wrapped. If the return type is void, null is returned.
-	 * </li>
-	 * </ul>
-	 * 
-	 * @param receiver
-	 * 	          The object on which to call the modeled method
-	 * @param args
-	 *            the arguments to the method
-	 * @return the new, initialized, object
-	 * @throws java.lang.NullPointerException
-	 *                if the receiver is null for a non-static method
-	 * @throws java.lang.IllegalAccessException
-	 *                if the modeled method is not accessible
-	 * @throws java.lang.IllegalArgumentException
-	 *                if an incorrect number of arguments are passed, the
-	 *                receiver is incompatible with the declaring class, or an
-	 *                argument could not be converted by a widening conversion
-	 * @throws java.lang.reflect.InvocationTargetException
-	 *                if an exception was thrown by the invoked method
-	 * @see java.lang.reflect.AccessibleObject
-	 */
+    /**
+     * Returns the result of dynamically invoking this method. This reproduces
+     * the effect of {@code receiver.methodName(arg1, arg2, ... , argN)} This
+     * method performs the following:
+     * <ul>
+     * <li>If this method is static, the receiver argument is ignored.</li>
+     * <li>Otherwise, if the receiver is null, a NullPointerException is thrown.
+     * </li>
+     * <li>If the receiver is not an instance of the declaring class of the
+     * method, an IllegalArgumentException is thrown.</li>
+     * <li>If this Method object is enforcing access control (see
+     * AccessibleObject) and this method is not accessible from the current
+     * context, an IllegalAccessException is thrown.</li>
+     * <li>If the number of arguments passed and the number of parameters do not
+     * match, an IllegalArgumentException is thrown.</li>
+     * <li>For each argument passed:
+     * <ul>
+     * <li>If the corresponding parameter type is a primitive type, the argument
+     * is unwrapped. If the unwrapping fails, an IllegalArgumentException is
+     * thrown.</li>
+     * <li>If the resulting argument cannot be converted to the parameter type
+     * via a widening conversion, an IllegalArgumentException is thrown.</li>
+     * </ul>
+     * <li>If this method is static, it is invoked directly. If it is
+     * non-static, this method and the receiver are then used to perform a
+     * standard dynamic method lookup. The resulting method is then invoked.</li>
+     * <li>If an exception is thrown during the invocation it is caught and
+     * wrapped in an InvocationTargetException. This exception is then thrown.</li>
+     * <li>If the invocation completes normally, the return value itself is
+     * returned. If the method is declared to return a primitive type, the
+     * return value is first wrapped. If the return type is void, null is
+     * returned.</li>
+     * </ul>
+     *
+     * @param receiver
+     *            the object on which to call this method
+     * @param args
+     *            the arguments to the method
+     *
+     * @return the new, initialized, object
+     *
+     * @throws NullPointerException
+     *             if the receiver is null for a non-static method
+     * @throws IllegalAccessException
+     *             if this method is not accessible
+     * @throws IllegalArgumentException
+     *             if an incorrect number of arguments are passed, the receiver
+     *             is incompatible with the declaring class, or an argument
+     *             could not be converted by a widening conversion
+     * @throws InvocationTargetException
+     *             if an exception was thrown by the invoked method
+     *
+     * @see AccessibleObject
+     */
 	public Object invoke(Object receiver, Object... args)
 			throws IllegalAccessException, IllegalArgumentException,
 			InvocationTargetException {
 		return null;
 	}
 
-	/**
-	 * Answers a string containing a concise, human-readable description of the
-	 * receiver. The format of the string is modifiers (if any) return type
-	 * declaring class name '.' method name '(' parameter types, separated by
-	 * ',' ')' If the method throws exceptions, ' throws ' exception types,
-	 * separated by ',' For example:
-	 * <code>public native Object java.lang.Method.invoke(Object,Object) throws IllegalAccessException,IllegalArgumentException,InvocationTargetException</code>
-	 * 
-	 * @return a printable representation for the receiver
-	 */
-	@Override
+    /**
+     * Returns a string containing a concise, human-readable description of this
+     * method. The format of the string is:
+     *
+     * <ol>
+     *   <li>modifiers (if any)
+     *   <li>return type or 'void'
+     *   <li>declaring class name
+     *   <li>'('
+     *   <li>parameter types, separated by ',' (if any)
+     *   <li>')'
+     *   <li>'throws' plus exception types, separated by ',' (if any)
+     * </ol>
+     *
+     * For example: {@code public native Object
+     * java.lang.Method.invoke(Object,Object) throws
+     * IllegalAccessException,IllegalArgumentException
+     * ,InvocationTargetException}
+     *
+     * @return a printable representation for this method
+     */
+    @Override
     public String toString() {
 		return null;
 	}



Mime
View raw message