harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r770909 [10/10] - in /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang: ./ ref/ reflect/
Date Sat, 02 May 2009 08:09:57 GMT
Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/TypeNotPresentException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/TypeNotPresentException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/TypeNotPresentException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/TypeNotPresentException.java Sat May  2 08:09:50 2009
@@ -17,29 +17,27 @@
 package java.lang;
 
 /**
- * <p>
- * Indicates that a class, interface, enum or annotation type cannot be found.
- * This exception is an unchecked alternative to
+ * Thrown when a program tries to access a class, interface, enum or annotation
+ * type through a string that contains the type's name and the type cannot be
+ * found. This exception is an unchecked alternative to
  * {@link java.lang.ClassNotFoundException}.
- * </p>
- * 
+ *
  * @since 1.5
- * @author Nathan Beyer (Harmony)
  */
 public class TypeNotPresentException extends RuntimeException {
-	private static final long serialVersionUID = -5101214195716534496L;
+    private static final long serialVersionUID = -5101214195716534496L;
 
     private String typeName;
 
     /**
-     * <p>
-     * Constructs an instance will a fully qualified type name and an optional
-     * cause.
-     * </p>
+     * Constructs a new {@code TypeNotPresentException} with the current stack
+     * trace, a detail message that includes the name of the type that could not
+     * be found and the {@code Throwable} that caused this exception.
      * 
-     * @param typeName The fully qualified type name.
-     * @param cause The <code>Throwable</code> that caused this exception or
-     *        <code>null</code>.
+     * @param typeName
+     *            the fully qualified name of the type that could not be found.
+     * @param cause
+     *            the optional cause of this exception, may be {@code null}.
      */
     public TypeNotPresentException(String typeName, Throwable cause) {
         super("Type " + typeName + " not present", cause);
@@ -47,11 +45,9 @@
     }
 
     /**
-     * <p>
-     * The fully qualified type name.
-     * </p>
+     * Gets the fully qualified name of the type that could not be found.
      * 
-     * @return A String instance.
+     * @return the name of the type that caused this exception.
      */
     public String typeName() {
         return typeName;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnknownError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnknownError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnknownError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnknownError.java Sat May  2 08:09:50 2009
@@ -17,30 +17,30 @@
 
 package java.lang;
 
-
 /**
- * This error is thrown when the virtual machine must throw an error which does
- * not match any known exceptional condition.
+ * Thrown when the virtual machine must throw an error which does not match any
+ * known exceptional condition.
  */
 public class UnknownError extends VirtualMachineError {
 
     private static final long serialVersionUID = 2524784860676771849L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public UnknownError() {
-		super();
-	}
+     * Constructs a new {@code UnknownError} that includes the current stack
+     * trace.
+     */
+    public UnknownError() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public UnknownError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code UnknownError} with the current stack trace and
+     * the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public UnknownError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsatisfiedLinkError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsatisfiedLinkError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsatisfiedLinkError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsatisfiedLinkError.java Sat May  2 08:09:50 2009
@@ -17,30 +17,30 @@
 
 package java.lang;
 
-
 /**
- * This error is thrown when an attempt is made to invoke a native for which an
- * implementation could not be found.
+ * Thrown when an attempt is made to invoke a native for which an implementation
+ * could not be found.
  */
 public class UnsatisfiedLinkError extends LinkageError {
 
     private static final long serialVersionUID = -4019343241616879428L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public UnsatisfiedLinkError() {
-		super();
-	}
+     * Constructs a new {@code UnsatisfiedLinkError} that includes the current
+     * stack trace.
+     */
+    public UnsatisfiedLinkError() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public UnsatisfiedLinkError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code UnsatisfiedLinkError} with the current stack
+     * trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public UnsatisfiedLinkError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsupportedClassVersionError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsupportedClassVersionError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsupportedClassVersionError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsupportedClassVersionError.java Sat May  2 08:09:50 2009
@@ -17,30 +17,30 @@
 
 package java.lang;
 
-
 /**
- * This error is thrown when an attempt is made to load a class with a format
- * version that is not supported by the VM.
+ * Thrown when an attempt is made to load a class with a format version that is
+ * not supported by the virtual machine.
  */
 public class UnsupportedClassVersionError extends ClassFormatError {
 
     private static final long serialVersionUID = -7123279212883497373L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public UnsupportedClassVersionError() {
-		super();
-	}
+     * Constructs a new {@code UnsupportedClassVersionError} that includes the
+     * current stack trace.
+     */
+    public UnsupportedClassVersionError() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public UnsupportedClassVersionError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code UnsupportedClassVersionError} with the current
+     * stack trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public UnsupportedClassVersionError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsupportedOperationException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsupportedOperationException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsupportedOperationException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/UnsupportedOperationException.java Sat May  2 08:09:50 2009
@@ -17,35 +17,39 @@
 
 package java.lang;
 
-
 /**
- * This runtime exception is thrown when an unsupported operation is attempted.
+ * Thrown when an unsupported operation is attempted.
  */
 public class UnsupportedOperationException extends RuntimeException {
 
-	private static final long serialVersionUID = -1242599979055084673L;
+    private static final long serialVersionUID = -1242599979055084673L;
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public UnsupportedOperationException() {
-	}
+    /**
+     * Constructs a new {@code UnsupportedOperationException} that includes the
+     * current stack trace.
+     */
+    public UnsupportedOperationException() {
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public UnsupportedOperationException(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code UnsupportedOperationException} with the current
+     * stack trace and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public UnsupportedOperationException(String detailMessage) {
+        super(detailMessage);
+    }
     
     /**
-     * <p>Constructs a new instance with a message and cause.</p>
-     * @param message The message to assign to this exception.
-     * @param cause The optional cause of this exception; may be <code>null</code>.
+     * Constructs a new {@code UnsupportedOperationException} with the current
+     * stack trace, the specified detail message and the specified cause.
+     * 
+     * @param message
+     *            the detail message for this exception.
+     * @param cause
+     *            the optional cause of this exception, may be {@code null}.
      * @since 1.5
      */
     public UnsupportedOperationException(String message, Throwable cause) {
@@ -53,8 +57,11 @@
     }
     
     /**
-     * <p>Constructs a new instance with a cause.</p>
-     * @param cause The optional cause of this exception; may be <code>null</code>.
+     * Constructs a new {@code UnsupportedOperationException} with the current
+     * stack trace and the specified cause.
+     * 
+     * @param cause
+     *            the optional cause of this exception, may be {@code null}.
      * @since 1.5
      */
     public UnsupportedOperationException(Throwable cause) {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/VerifyError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/VerifyError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/VerifyError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/VerifyError.java Sat May  2 08:09:50 2009
@@ -17,9 +17,8 @@
 
 package java.lang;
 
-
 /**
- * This error is thrown when the VM notices that an attempt is made to load a
+ * Thrown when the virtual machine notices that an attempt is made to load a
  * class which does not pass the class verification phase.
  */
 public class VerifyError extends LinkageError {
@@ -27,20 +26,21 @@
     private static final long serialVersionUID = 7001962396098498785L;
 
     /**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public VerifyError() {
-		super();
-	}
+     * Constructs a new {@code VerifyError} that includes the current stack
+     * trace.
+     */
+    public VerifyError() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public VerifyError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code VerifyError} with the current stack trace and the
+     * specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public VerifyError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/VirtualMachineError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/VirtualMachineError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/VirtualMachineError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/VirtualMachineError.java Sat May  2 08:09:50 2009
@@ -19,7 +19,7 @@
 
 
 /**
- * This class is the superclass of all classes which represent errors that occur
+ * {@code VirtualMachineError} is the superclass of all error classes that occur
  * during the operation of the virtual machine.
  * 
  * @see Error
@@ -28,21 +28,22 @@
 
     private static final long serialVersionUID = 4161983926571568670L;
 
-	/**
-	 * Constructs a new instance of this class with its walkback filled in.
-	 */
-	public VirtualMachineError() {
-		super();
-	}
+    /**
+     * Constructs a new {@code VirtualMachineError} that includes the current
+     * stack trace.
+     */
+    public VirtualMachineError() {
+        super();
+    }
 
-	/**
-	 * Constructs a new instance of this class with its walkback and message
-	 * filled in.
-	 * 
-	 * @param detailMessage
-	 *            String The detail message for the exception.
-	 */
-	public VirtualMachineError(String detailMessage) {
-		super(detailMessage);
-	}
+    /**
+     * Constructs a new {@code VirtualMachineError} with the current stack trace
+     * and the specified detail message.
+     * 
+     * @param detailMessage
+     *            the detail message for this exception.
+     */
+    public VirtualMachineError(String detailMessage) {
+        super(detailMessage);
+    }
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Void.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Void.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Void.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Void.java Sat May  2 08:09:50 2009
@@ -20,14 +20,14 @@
 import java.lang.reflect.Method;
 
 /**
- * This class is a placeholder class for the Java keyword <code>void</code>
+ * Placeholder class for the Java keyword {@code void}.
+ *
  * @since 1.1
  */
 public final class Void extends Object {
     
-	/**
-     * The {@link Class} instance that represents primitive type
-     * <code>void</code>.
+    /**
+     * The {@link Class} object that represents the primitive type {@code void}.
      */
     public static final Class<Void> TYPE = lookupType();
 

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ref/ReferenceQueue.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ref/ReferenceQueue.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ref/ReferenceQueue.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/ref/ReferenceQueue.java Sat May  2 08:09:50 2009
@@ -18,13 +18,11 @@
 package java.lang.ref;
 
 /**
- * The implementation of this class is provided. The non-public implementation
- * details are documented so the VM vendor can use the implementation.
- * 
- * ReferenceQueue is the container on which reference objects are enqueued when
- * their reachability type is detected for the referent.
- * 
- * @since JDK1.2
+ * The {@code ReferenceQueue} is the container on which reference objects are
+ * enqueued when the garbage collector detects the reachability type specified
+ * for the referent.
+ *
+ * @since 1.2
  */
 public class ReferenceQueue<T> {
     
@@ -55,10 +53,11 @@
     }
 
 	/**
-	 * Returns the next available reference from the queue if one is enqueued,
-	 * null otherwise. Does not wait for a reference to become available.
-	 * 
-	 * @return Reference next available Reference or NULL.
+     * Returns the next available reference from the queue, removing it in the
+     * process. Does not wait for a reference to become available.
+     *
+     * @return the next available reference, or {@code null} if no reference is
+     *         immediately available
 	 */
 	public Reference<? extends T> poll() {
 		Reference<? extends T> ref;
@@ -80,29 +79,33 @@
 	}
 
 	/**
-	 * Return the next available enqueued reference on the queue, blocking
-	 * indefinitely until one is available.
-	 * 
-	 * @return Reference a Reference object if one is available, null otherwise.
-	 * @exception InterruptedException
-	 *                to interrupt the wait.
+     * Returns the next available reference from the queue, removing it in the
+     * process. Waits indefinitely for a reference to become available.
+     *
+     * @return the next available reference
+     *
+     * @throws InterruptedException
+     *             if the blocking call was interrupted for some reason
 	 */
 	public Reference<? extends T> remove() throws InterruptedException {
 		return remove(0L);
 	}
 
 	/**
-	 * Return the next available enqueued reference on the queue, blocking up to
-	 * the time given until one is available. Return null if no reference became
-	 * available.
-	 * 
-	 * @param timeout
-	 *            maximum time spent waiting for a reference object to become
-	 *            available.
-	 * @return Reference a Reference object if one is available, null otherwise.
-	 * @exception IllegalArgumentException
-	 *                if the wait period is negative. InterruptedException to
-	 *                interrupt the wait.
+     * Returns the next available reference from the queue, removing it in the
+     * process. Waits for a reference to become available or the given timeout
+     * period to elapse, whichever happens first.
+     *
+     * @param timeout
+     *            maximum time (in ms) to spend waiting for a reference object
+     *            to become available. A value of zero results in the method
+     *            waiting indefinitely.
+     * @return the next available reference, or {@code null} if no reference
+     *         becomes available within the timeout period
+     * @throws IllegalArgumentException
+     *             if the wait period is negative.
+     * @throws InterruptedException
+     *             if the blocking call was interrupted for some reason
 	 */
 	public Reference<? extends T> remove(long timeout) throws IllegalArgumentException,
 			InterruptedException {
@@ -134,7 +137,7 @@
 
 	/**
 	 * Enqueue the reference object on the receiver.
-	 * 
+	 *
 	 * @param reference
 	 *            reference object to be enqueued.
 	 * @return boolean true if reference is enqueued. false if reference failed

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/AnnotatedElement.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/AnnotatedElement.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/AnnotatedElement.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/AnnotatedElement.java Sat May  2 08:09:50 2009
@@ -20,52 +20,52 @@
 import java.lang.annotation.Annotation;
 
 /**
- * An interface implemented an annotated element to enable reflective access to
- * annotation information.
- * 
+ * This interface provides reflective access to annotation information.
+ *
  * @since 1.5
  */
 public interface AnnotatedElement {
 
     /**
-     * Gets the {@link Annotation} for this element for the annotation type
-     * passed, if it exists.
+     * Returns, for this element, the annotation with the specified type, or
+     * {@code null} if no annotation with the specified type is present
+     * (including inherited annotations).
      * 
      * @param annotationType
-     *            The Class instance of the annotation to search for.
-     * @return The {@link Annotation} for this element or <code>null</code>.
+     *            the type of the annotation to search for
+     * @return the annotation with the specified type or {@code null}
      * @throws NullPointerException
-     *             if <code>annotationType</code> is <code>null</code>.
+     *             if {@code annotationType} is {@code null}
      */
     <T extends Annotation> T getAnnotation(Class<T> annotationType);
 
     /**
-     * Gets all {@link Annotation}s for this element.
+     * Returns, for this element, an array containing all annotations (including
+     * inherited annotations). If there are no annotations present, this method
+     * returns a zero length array.
      * 
-     * @return An array of {@link Annotation}s, which may be empty, but never
-     *         <code>null</code>.
+     * @return an array of all annotations for this element
      */
     Annotation[] getAnnotations();
 
     /**
-     * Gets all {@link Annotation}s that are explicitly declared by this
-     * element (not inherited).
+     * Returns, for this element, all annotations that are explicitly declared
+     * (not inherited). If there are no declared annotations present, this
+     * method returns a zero length array.
      * 
-     * @return An array of {@link Annotation}s, which may be empty, but never
-     *         <code>null</code>.
+     * @return an array of annotations declared for this element
      */
     Annotation[] getDeclaredAnnotations();
 
     /**
-     * Determines if this element has an annotation for the annotation type
-     * passed.
+     * Indicates whether or not this element has an annotation with the
+     * specified annotation type (including inherited annotations).
      * 
      * @param annotationType
-     *            The class instance of the annotation to search for.
-     * @return <code>true</code> if the annotation exists, otherwise
-     *         <code>false</code>.
+     *            the type of the annotation to search for
+     * @return {@code true} if the annotation exists, {@code false} otherwise
      * @throws NullPointerException
-     *             if <code>annotationType</code> is <code>null</code>.
+     *             if {@code annotationType} is {@code null}
      */
     boolean isAnnotationPresent(Class<? extends Annotation> annotationType);
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericArrayType.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericArrayType.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericArrayType.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericArrayType.java Sat May  2 08:09:50 2009
@@ -18,21 +18,22 @@
 package java.lang.reflect;
 
 /**
- * Represents an array type with a component type that is parameterized or a
- * type variable.
+ * This interface represents an array type with a component type that is either
+ * a parameterized type or a type variable.
  * 
  * @since 1.5
  */
 public interface GenericArrayType extends Type {
     /**
-     * The {@link Type} that represents the component type of the array.
-     * 
-     * @return A {@link Type} instance.
+     * Returns the component type of this array.
+     *
+     * @return the component type of this array
+     *
      * @throws TypeNotPresentException
-     *             if the component type points to a missing type.
+     *             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.
+     *             if the component type points to a type that cannot be
+     *             instantiated for some reason
      */
     Type getGenericComponentType();
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericDeclaration.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericDeclaration.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericDeclaration.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericDeclaration.java Sat May  2 08:09:50 2009
@@ -17,19 +17,19 @@
 package java.lang.reflect;
 
 /**
- * Common interface for entities that have type variables.
- * 
+ * Common interface for language constructs that declare type parameters.
+ *
  * @since 1.5
  */
 public interface GenericDeclaration {
 
     /**
-     * Answers the generic declared types in declaration order. If there are no
-     * generic types this method returns a zero length array.
+     * Returns the declared type parameters in declaration order. If there are
+     * no type parameters, this method returns a zero length array.
      * 
-     * @return array of generic declared type variables.
+     * @return the declared type parameters in declaration order
      * @throws GenericSignatureFormatError
-     *             if the signature is malformed.
+     *             if the signature is malformed
      */
     TypeVariable<?>[] getTypeParameters();
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericSignatureFormatError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericSignatureFormatError.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericSignatureFormatError.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/GenericSignatureFormatError.java Sat May  2 08:09:50 2009
@@ -27,6 +27,9 @@
 
     private static final long serialVersionUID = 6709919147137911034L;
 
+    /**
+     * Constructs a new {@code GenericSignatureFormatError} instance.
+     */
     public GenericSignatureFormatError() {
         super();
     }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/InvocationHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/InvocationHandler.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/InvocationHandler.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/InvocationHandler.java Sat May  2 08:09:50 2009
@@ -18,32 +18,44 @@
 package java.lang.reflect;
 
 /**
- * Implementors of this interface decode and dispatch methods sent to proxy
- * instances.
+ * Implementors of this interface dispatch methods invoked on proxy instances.
  * 
  * @see Proxy
  */
 public interface InvocationHandler {
 
     /**
-     * Return the result of decoding and dispatching the method which was
-     * originally sent to the proxy instance.
+     * Handles the method which was originally invoked on the proxy instance. A
+     * typical usage pattern follows below:
+     * 
+     * <pre>
+     * public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
+     *     //do some processing before the method invocation
+     * 
+     *     //invoke the method
+     *     Object result = method.invoke(proxy, args);
+     * 
+     *     //do some processing after the method invocation
+     *     return result;
+     * }</pre>
      * 
      * @param proxy
-     *            the proxy instance which was the receiver of the method.
+     *            the proxy instance on which the method was invoked
      * @param method
-     *            the Method invoked on the proxy instance.
+     *            the method invoked on the proxy instance
      * @param args
      *            an array of objects containing the parameters passed to the
-     *            method, or null if no arguments are expected. primitive types
-     *            are wrapped in the appropriate class.
-     * @return the result of executing the method
-     * 
+     *            method, or {@code null} if no arguments are expected.
+     *            Primitive types are wrapped in the appropriate wrapper type
+     *            
+     * @return the result of executing the method. Primitive types need to be
+     *         wrapped in the appropriate wrapper type
+     *         
      * @throws Throwable
-     *             if an exception was thrown by the invoked method. The
-     *             exception must match one of the declared exception types for
-     *             the invoked method or any unchecked exception type. If not
-     *             then an UndeclaredThrowableException is thrown.
+     *             the exception to throw from the invoked method on the proxy.
+     *             The exception must match one of the declared exception types
+     *             of the invoked method or any unchecked exception type. If not
+     *             then an {@code UndeclaredThrowableException} is thrown
      */
     public Object invoke(Object proxy, Method method, Object[] args)
             throws Throwable;

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/InvocationTargetException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/InvocationTargetException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/InvocationTargetException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/InvocationTargetException.java Sat May  2 08:09:50 2009
@@ -18,8 +18,8 @@
 package java.lang.reflect;
 
 /**
- * This class provides a wrapper for an exception thrown by a Method or
- * Constructor invocation.
+ * This class provides a wrapper for an exception thrown by a {@code Method} or
+ * {@code Constructor} invocation.
  * 
  * @see Method#invoke
  * @see Constructor#newInstance
@@ -31,19 +31,20 @@
     private Throwable target;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
+     * Constructs a new {@code InvocationTargetException} instance with a
+     * {@code null} cause / target exception.
      */
     protected InvocationTargetException() {
         super((Throwable) null);
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and target
-     * exception filled in.
+     * Constructs a new {@code InvocationTargetException} instance with its
+     * cause / target exception filled in.
      * 
      * @param exception
-     *            Throwable The exception which occurred while running the
-     *            Method or Constructor.
+     *            the exception which occurred while running the Method or
+     *            Constructor
      */
     public InvocationTargetException(Throwable exception) {
         super(null, exception);
@@ -51,14 +52,14 @@
     }
 
     /**
-     * Constructs a new instance of this class with its walkback, target
-     * exception and message filled in.
+     * Constructs a new {@code InvocationTargetException} instance with its
+     * cause / target exception and message filled in.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for the exception
      * @param exception
-     *            Throwable The exception which occurred while running the
-     *            Method or Constructor.
+     *            the exception which occurred while running the Method or
+     *            Constructor
      */
     public InvocationTargetException(Throwable exception, String detailMessage) {
         super(detailMessage, exception);
@@ -66,16 +67,18 @@
     }
 
     /**
-     * Answers the exception which caused the receiver to be thrown.
+     * Returns the target exception, which may be {@code null}.
+     * 
+     * @return the target exception
      */
     public Throwable getTargetException() {
         return target;
     }
 
     /**
-     * Answers the cause of this Throwable, or null if there is no cause.
+     * Returns the cause of this exception, which may be {@code null}.
      * 
-     * @return Throwable The receiver's cause.
+     * @return the cause of this exception
      */
     @Override
     public Throwable getCause() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/MalformedParameterizedTypeException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/MalformedParameterizedTypeException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/MalformedParameterizedTypeException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/MalformedParameterizedTypeException.java Sat May  2 08:09:50 2009
@@ -18,8 +18,8 @@
 package java.lang.reflect;
 
 /**
- * Indicates that a malformed parameterized type has been accessed by a
- * reflected method.
+ * Indicates that a malformed parameterized type has been encountered by a
+ * reflective method.
  * 
  * @since 1.5
  */
@@ -28,7 +28,7 @@
     private static final long serialVersionUID = -5696557788586220964L;
 
     /**
-     * Constructs an instance.
+     * Constructs a new {@code MalformedParameterizedTypeException} instance.
      */
     public MalformedParameterizedTypeException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Member.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Member.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Member.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Member.java Sat May  2 08:09:50 2009
@@ -18,7 +18,7 @@
 package java.lang.reflect;
 
 /**
- * Implementors of this interface model a class member.
+ * Common interface providing access to reflective information on class members.
  * 
  * @see Field
  * @see Constructor
@@ -26,32 +26,44 @@
  */
 public interface Member {
 
+    /**
+     * Designates all public members of a class or interface (including
+     * inherited members).
+     *
+     * @see java.lang.SecurityManager#checkMemberAccess
+     */
     public static final int PUBLIC = 0;
 
+    /**
+     * Designates all declared members of a class or interface (without
+     * inherited members).
+     *
+     * @see java.lang.SecurityManager#checkMemberAccess
+     */
     public static final int DECLARED = 1;
 
     /**
-     * Return the {@link Class} associated with the class that defined this
-     * member.
-     * 
+     * Returns the class that declares this member.
+     *
      * @return the declaring class
      */
     @SuppressWarnings("unchecked")
     Class getDeclaringClass();
 
     /**
-     * Return the modifiers for the member. The Modifier class should be used to
-     * decode the result.
-     * 
-     * @return the modifiers
-     * @see java.lang.reflect.Modifier
+     * Returns the modifiers for this member. The {@link Modifier} class should
+     * be used to decode the result.
+     *
+     * @return the modifiers for this member
+     *
+     * @see Modifier
      */
     int getModifiers();
 
     /**
-     * Return the name of the member.
-     * 
-     * @return the name
+     * Returns the name of this member.
+     *
+     * @return the name of this member
      */
     String getName();
 
@@ -59,8 +71,7 @@
      * Indicates whether or not this member is synthetic (artificially
      * introduced by the compiler).
      * 
-     * @return A value of <code>true</code> if synthetic, otherwise
-     *         <code>false</code>.
+     * @return {@code true} if this member is synthetic, {@code false} otherwise
      */
     boolean isSynthetic();
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Modifier.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Modifier.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Modifier.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Modifier.java Sat May  2 08:09:50 2009
@@ -18,35 +18,79 @@
 package java.lang.reflect;
 
 /**
- * This class provides methods to decode class and member modifiers.
- * 
+ * This class provides static methods to decode class and member modifiers.
+ *
  * @see Class#getModifiers()
  * @see Member#getModifiers()
  */
 public class Modifier {
 
+    /**
+     * The {@code int} value representing the {@code public}
+     * modifier.
+     */
     public static final int PUBLIC = 0x1;
 
+    /**
+     * The {@code int} value representing the {@code private}
+     * modifier.
+     */
     public static final int PRIVATE = 0x2;
 
+    /**
+     * The {@code int} value representing the {@code protected}
+     * modifier.
+     */
     public static final int PROTECTED = 0x4;
 
+    /**
+     * The {@code int} value representing the {@code static} modifier.
+     */
     public static final int STATIC = 0x8;
 
+    /**
+     * The {@code int} value representing the {@code final} modifier.
+     */
     public static final int FINAL = 0x10;
 
+    /**
+     * The {@code int} value representing the {@code synchronized}
+     * modifier.
+     */
     public static final int SYNCHRONIZED = 0x20;
 
+    /**
+     * The {@code int} value representing the {@code volatile}
+     * modifier.
+     */
     public static final int VOLATILE = 0x40;
 
+    /**
+     * The {@code int} value representing the {@code transient}
+     * modifier.
+     */
     public static final int TRANSIENT = 0x80;
 
+    /**
+     * The {@code int} value representing the {@code native} modifier.
+     */
     public static final int NATIVE = 0x100;
 
+    /**
+     * The {@code int} value representing the {@code interface}
+     * modifier.
+     */
     public static final int INTERFACE = 0x200;
 
+    /**
+     * The {@code int} value representing the {@code abstract}
+     * modifier.
+     */
     public static final int ABSTRACT = 0x400;
 
+    /**
+     * The {@code int} value representing the {@code strict} modifier.
+     */
     public static final int STRICT = 0x800;
 
     // Non-public types required by Java 5 update to class file format
@@ -60,161 +104,175 @@
 
     static final int ENUM = 0x4000;
 
+    /**
+     * Constructs a new {@code Modifier} instance.
+     */
     public Modifier() {
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>abstract</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * abstract} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the abstract modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         abstract} modifier, {@code false} otherwise
      */
     public static boolean isAbstract(int modifiers) {
         return ((modifiers & ABSTRACT) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>final</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * final} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the final modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         final} modifier, {@code false} otherwise
      */
     public static boolean isFinal(int modifiers) {
         return ((modifiers & FINAL) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>interface</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * interface} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the interface modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         interface} modifier, {@code false} otherwise
      */
     public static boolean isInterface(int modifiers) {
         return ((modifiers & INTERFACE) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>native</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * native} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the native modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         native} modifier, {@code false} otherwise
      */
     public static boolean isNative(int modifiers) {
         return ((modifiers & NATIVE) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>private</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * private} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the private modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         private} modifier, {@code false} otherwise
      */
     public static boolean isPrivate(int modifiers) {
         return ((modifiers & PRIVATE) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>protected</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * protected} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the protected modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         protected} modifier, {@code false} otherwise
      */
     public static boolean isProtected(int modifiers) {
         return ((modifiers & PROTECTED) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>public</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * public} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the abstract modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         public} modifier, {@code false} otherwise
      */
     public static boolean isPublic(int modifiers) {
         return ((modifiers & PUBLIC) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>static</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * static} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the static modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         static} modifier, {@code false} otherwise
      */
     public static boolean isStatic(int modifiers) {
         return ((modifiers & STATIC) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>strict</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * strict} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the strict modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         strict} modifier, {@code false} otherwise
      */
     public static boolean isStrict(int modifiers) {
         return ((modifiers & STRICT) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the
-     * <code>synchronized</code> modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * synchronized} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the synchronized modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         synchronized} modifier, {@code false} otherwise
      */
     public static boolean isSynchronized(int modifiers) {
         return ((modifiers & SYNCHRONIZED) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>transient</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * transient} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the transient modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         transient} modifier, {@code false} otherwise
      */
     public static boolean isTransient(int modifiers) {
         return ((modifiers & TRANSIENT) != 0);
     }
 
     /**
-     * Return true if the specified modifiers contain the <code>volatile</code>
-     * modifier, false otherwise.
+     * Indicates whether or not the specified modifiers contain the {@code
+     * volatile} modifier.
      * 
      * @param modifiers
      *            the modifiers to test
-     * @return if the modifiers contain the volatile modifier
+     * @return {@code true} if the specified modifiers contain the {@code
+     *         volatile} modifier, {@code false} otherwise
      */
     public static boolean isVolatile(int modifiers) {
         return ((modifiers & VOLATILE) != 0);
     }
 
     /**
-     * Answers a string containing the string representation of all modifiers
-     * present in the specified modifiers.
-     * 
-     * Modifiers appear in the order specified by the Java Language
-     * Specification:
-     * <code>public private protected abstract static final transient volatile native synchronized interface strict</code>
-     * 
+     * Returns a string containing the string representation of all modifiers
+     * present in the specified modifiers. Modifiers appear in the order
+     * specified by the Java Language Specification:
+     *
+     * {@code public private protected abstract static final transient volatile native synchronized interface strict}
+     *
      * @param modifiers
      *            the modifiers to print
      * @return a printable representation of the modifiers

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/ParameterizedType.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/ParameterizedType.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/ParameterizedType.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/ParameterizedType.java Sat May  2 08:09:50 2009
@@ -18,41 +18,59 @@
 package java.lang.reflect;
 
 /**
- * Represents a parameterized type.
- * 
+ * This interface represents a parameterized type such as {@code
+ * 'Set&lt;String&gt;'}.
+ *
  * @since 1.5
  */
 public interface ParameterizedType extends Type {
 
     /**
-     * Gets the type arguments for this type.
-     * 
-     * @return An array of {@link Type}, which may be empty.
+     * Returns an array of the actual type arguments for this type.
+     * <p>
+     * If this type models a non parameterized type nested within a
+     * parameterized type, this method returns a zero length array. The generic
+     * type of the following {@code field} declaration is an example for a
+     * parameterized type without type arguments.
+     *
+     * <pre>
+     * A&lt;String&gt;.B field;
+     *
+     * class A&lt;T&gt; {
+     *     class B {
+     *     }
+     * }</pre>
+     *
+     *
+     * @return the actual type arguments
+     *
      * @throws TypeNotPresentException
-     *             if one of the type arguments can't be found.
+     *             if one of the type arguments cannot be found
      * @throws MalformedParameterizedTypeException
-     *             if one of the type arguments can't be instantiated for some
-     *             reason.
+     *             if one of the type arguments cannot be instantiated for some
+     *             reason
      */
     Type[] getActualTypeArguments();
 
     /**
-     * Gets the parent/owner type, if this type is an inner type, otherwise
-     * <code>null</code> is returned if this is a top-level type.
+     * Returns the parent / owner type, if this type is an inner type, otherwise
+     * {@code null} is returned if this is a top-level type.
      * 
-     * @return An instance of {@link Type} or <code>null</code>.
+     * @return the owner type or {@code null} if this is a top-level type
+     *
      * @throws TypeNotPresentException
-     *             if one of the type arguments can't be found.
+     *             if one of the type arguments cannot be found
      * @throws MalformedParameterizedTypeException
-     *             if one of the type arguments can't be instantiated for some
-     *             reason.
+     *             if the owner type cannot be instantiated for some reason
      */
     Type getOwnerType();
 
     /**
-     * Gets the raw type of this type.
-     * 
-     * @return An instance of {@link Type}.
+     * Returns the declaring type of this parameterized type.
+     * <p>
+     * The raw type of {@code Set&lt;String&gt; field;} is {@code Set}.
+     *
+     * @return the raw type of this parameterized type
      */
     Type getRawType();
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Proxy.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Proxy.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Proxy.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Proxy.java Sat May  2 08:09:50 2009
@@ -28,10 +28,11 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * This class provides methods to creating dynamic proxy classes and instances.
- * 
+ * {@code Proxy} defines methods for creating dynamic proxy classes and instances.
+ * A proxy class implements a declared set of interfaces and delegates method
+ * invocations to an {@code InvocationHandler}.
+ *
  * @see InvocationHandler
- * 
  * @since 1.3
  */
 public class Proxy implements Serializable {
@@ -46,34 +47,46 @@
 
     private static int NextClassNameIndex = 0;
 
+    /**
+     * The invocation handler on which the method calls are dispatched.
+     */
     protected InvocationHandler h;
 
     private Proxy() {
     }
 
+    /**
+     * Constructs a new {@code Proxy} instance with the specified invocation
+     * handler.
+     *
+     * @param h
+     *            the invocation handler for the newly created proxy
+     */
     protected Proxy(InvocationHandler h) {
         this.h = h;
     }
 
     /**
-     * Return the dynamically build class for the given interfaces, build a new
-     * one when necessary. The order of the interfaces is important.
-     * 
-     * The interfaces must be visible from the supplied class loader; no
-     * duplicates are permitted. All non-public interfaces must be defined in
-     * the same package.
+     * Returns the dynamically built {@code Class} for the specified interfaces.
+     * Creates a new {@code Class} when necessary. The order of the interfaces
+     * is relevant. Invocations of this method with the same interfaces but
+     * different order result in different generated classes. The interfaces
+     * must be visible from the supplied class loader; no duplicates are
+     * permitted. All non-public interfaces must be defined in the same package.
      * 
      * @param loader
-     *            the class loader that will define the proxy class.
+     *            the class loader that will define the proxy class
      * @param interfaces
-     *            an array of <code>Class</code> objects, each one identifying
-     *            an interface that the new proxy must implement
+     *            an array of {@code Class} objects, each one identifying an
+     *            interface that will be implemented by the returned proxy
+     *            class
      * @return a proxy class that implements all of the interfaces referred to
-     *         in the contents of <code>interfaces</code>.
-     * @exception IllegalArgumentException
-     * @exception NullPointerException
-     *                if either <code>interfaces</code> or any of its elements
-     *                are <code>null</code>.
+     *         in the contents of {@code interfaces}
+     * @throws IllegalArgumentException
+     *                if any of the interface restrictions are violated
+     * @throws NullPointerException
+     *                if either {@code interfaces} or any of its elements are
+     *                {@code null}
      */
     public static Class<?> getProxyClass(ClassLoader loader,
             Class<?>[] interfaces) throws IllegalArgumentException {
@@ -173,23 +186,26 @@
     }
 
     /**
-     * Return an instance of the dynamically build class for the given
-     * interfaces that forwards methods to the specified invocation handler.
-     * 
-     * The interfaces must be visible from the supplied class loader; no
-     * duplicates are permitted. All non-public interfaces must be defined in
-     * the same package.
-     * 
+     * Returns an instance of the dynamically built class for the specified
+     * interfaces. Method invocations on the returned instance are forwarded to
+     * the specified invocation handler. The interfaces must be visible from the
+     * supplied class loader; no duplicates are permitted. All non-public
+     * interfaces must be defined in the same package.
+     *
      * @param loader
-     *            the class loader that will define the proxy class.
+     *            the class loader that will define the proxy class
      * @param interfaces
-     *            the list of interfaces to implement.
+     *            an array of {@code Class} objects, each one identifying an
+     *            interface that will be implemented by the returned proxy
+     *            object
      * @param h
-     *            the invocation handler for the forwarded methods.
-     * @return a new proxy object that delegates to the handler <code>h</code>
-     * @exception IllegalArgumentException
-     * @exception NullPointerException
-     *                if the interfaces or any of its elements are null.
+     *            the invocation handler that handles the dispatched method
+     *            invocations
+     * @return a new proxy object that delegates to the handler {@code h}
+     * @throws IllegalArgumentException
+     *                if any of the interface restrictions are violated
+     * @throws NullPointerException
+     *                if the interfaces or any of its elements are null
      */
     public static Object newProxyInstance(ClassLoader loader,
             Class<?>[] interfaces, InvocationHandler h)
@@ -218,13 +234,15 @@
     }
 
     /**
-     * Return whether the supplied class is a dynamically generated proxy class.
+     * Indicates whether or not the specified class is a dynamically generated
+     * proxy class.
      * 
      * @param cl
-     *            the class.
-     * @return true if the class is a proxy class and false otherwise.
-     * @exception NullPointerException
-     *                if the class is null.
+     *            the class
+     * @return {@code true} if the class is a proxy class, {@code false}
+     *         otherwise
+     * @throws NullPointerException
+     *                if the class is {@code null}
      */
     public static boolean isProxyClass(Class<?> cl) {
         if (cl == null) {
@@ -236,14 +254,13 @@
     }
 
     /**
-     * Return the proxy instance's invocation handler.
+     * Returns the invocation handler of the specified proxy instance.
      * 
      * @param proxy
-     *            the proxy instance.
-     * @return the proxy's invocation handler object
-     * @exception IllegalArgumentException
-     *                if the supplied <code>proxy</code> is not a proxy
-     *                object.
+     *            the proxy instance
+     * @return the invocation handler of the specified proxy instance
+     * @throws IllegalArgumentException
+     *                if the supplied {@code proxy} is not a proxy object
      */
     public static InvocationHandler getInvocationHandler(Object proxy)
             throws IllegalArgumentException {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/ReflectPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/ReflectPermission.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/ReflectPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/ReflectPermission.java Sat May  2 08:09:50 2009
@@ -20,31 +20,40 @@
 import java.security.BasicPermission;
 
 /**
- * ReflectPermission objects represent permission to access dangerous operations
- * in the reflection layer.
+ * A {@code ReflectPermission} object represents a permission to access
+ * operations in the reflection layer.
  */
 public final class ReflectPermission extends BasicPermission {
 
     private static final long serialVersionUID = 7412737110241507485L;
 
     /**
-     * Creates an instance of this class with given name.
+     * Constructs a new {@code ReflectPermission} instance with the specified
+     * name.
      * 
      * @param permissionName
-     *            String the name of the new permission.
+     *            the name of the new permission
+     * @throws IllegalArgumentException
+     *             if {@code name} is empty
+     * @throws NullPointerException
+     *             if {@code name} is {@code null}
      */
     public ReflectPermission(String permissionName) {
         super(permissionName);
     }
 
     /**
-     * Creates an instance of this class with the given name and action list.
-     * The action list is ignored.
+     * Constructs a new {@code ReflectPermission} instance with the specified
+     * name and action list. The action list will be ignored.
      * 
      * @param name
-     *            String the name of the new permission.
+     *            the name of the new permission
      * @param actions
-     *            String ignored.
+     *            this parameter will be ignored
+     * @throws IllegalArgumentException
+     *             if {@code name} is empty
+     * @throws NullPointerException
+     *             if {@code name} is {@code null}
      */
     public ReflectPermission(String name, String actions) {
         super(name, actions);

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Type.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Type.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Type.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/Type.java Sat May  2 08:09:50 2009
@@ -17,8 +17,8 @@
 package java.lang.reflect;
 
 /**
- * Common interface for all Java types.
- * 
+ * Common interface implemented by all Java types.
+ *
  * @since 1.5
  */
 public interface Type {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/TypeVariable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/TypeVariable.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/TypeVariable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/TypeVariable.java Sat May  2 08:09:50 2009
@@ -17,35 +17,43 @@
 package java.lang.reflect;
 
 /**
- * Represents a type variable.
- * 
+ * This interface represents a type variables such as {@code 'T'} in {@code
+ * 'public interface Comparable&lt;T&gt;'}, the bounded {@code 'T'} in {@code
+ * 'public interface A&lt;T extends Number&gt;'} or the multiple bounded {@code
+ * 'T'} in {@code 'public interface B&lt;T extends Number & Cloneable&gt;'}.
+ *
+ * @param <D>
+ *            the generic declaration that declares this type variable
  * @since 1.5
  */
 public interface TypeVariable<D extends GenericDeclaration> extends Type {
 
     /**
-     * Answers the upper bounds of the type variable.
-     * 
-     * @return array of type variable's upper bounds.
+     * Returns the upper bounds of this type variable. {@code Object} is the
+     * implicit upper bound if no other bounds are declared.
+     *
+     * @return the upper bounds of this type variable
+     *
      * @throws TypeNotPresentException
-     *             if the component type points to a missing type.
+     *             if any of the bounds points to a missing type
      * @throws MalformedParameterizedTypeException
-     *             if the component type points to a type that can't be
-     *             instantiated for some reason.
+     *             if any of the bounds points to a type that cannot be
+     *             instantiated for some reason
      */
     Type[] getBounds();
 
     /**
-     * Answers a GenericDeclaration object for this type variable.
-     * 
-     * @return the generic declaration spec
+     * Returns the language construct that declares this type variable.
+     *
+     * @return the generic declaration
      */
     D getGenericDeclaration();
 
     /**
-     * Answers the type variable's name from source.
-     * 
-     * @return the variable's name from the source code.
+     * Returns the name of this type variable as it is specified in source
+     * code.
+     *
+     * @return the name of this type variable
      */
     String getName();
 }

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/UndeclaredThrowableException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/UndeclaredThrowableException.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/UndeclaredThrowableException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/UndeclaredThrowableException.java Sat May  2 08:09:50 2009
@@ -18,9 +18,9 @@
 package java.lang.reflect;
 
 /**
- * This class provides a wrapper for an unexpected exception thrown by an
- * InvocationHandler
- * 
+ * This class provides a wrapper for an undeclared, checked exception thrown by
+ * an InvocationHandler.
+ *
  * @see java.lang.reflect.InvocationHandler#invoke
  */
 public class UndeclaredThrowableException extends RuntimeException {
@@ -30,11 +30,11 @@
     private Throwable undeclaredThrowable;
 
     /**
-     * Constructs a new instance of this class with its walkback and target
-     * exception filled in.
+     * Constructs a new {@code UndeclaredThrowableException} instance with the
+     * undeclared, checked exception that occurred.
      * 
      * @param exception
-     *            The exception which occurred while loading the class.
+     *            the undeclared, checked exception that occurred
      */
     public UndeclaredThrowableException(Throwable exception) {
         super();
@@ -43,14 +43,13 @@
     }
 
     /**
-     * Constructs a new instance of this class with its walkback, target
-     * exception and message filled in.
+     * Constructs a new {@code UndeclaredThrowableException} instance with the
+     * undeclared, checked exception that occurred and a message.
      * 
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for the exception
      * @param exception
-     *            Throwable The exception which occurred while loading the
-     *            class.
+     *            the undeclared, checked exception that occurred
      */
     public UndeclaredThrowableException(Throwable exception,
             String detailMessage) {
@@ -60,16 +59,20 @@
     }
 
     /**
-     * Answers the exception which caused the receiver to be thrown.
+     * Returns the undeclared, checked exception that occurred, which may be
+     * {@code null}.
+     *
+     * @return the undeclared, checked exception that occurred
      */
     public Throwable getUndeclaredThrowable() {
         return undeclaredThrowable;
     }
 
     /**
-     * Answers the cause of this Throwable, or null if there is no cause.
-     * 
-     * @return Throwable The receiver's cause.
+     * Returns the undeclared, checked exception that occurred, which may be
+     * {@code null}.
+     *
+     * @return the undeclared, checked exception that occurred
      */
     @Override
     public Throwable getCause() {

Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/WildcardType.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/WildcardType.java?rev=770909&r1=770908&r2=770909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/WildcardType.java (original)
+++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/reflect/WildcardType.java Sat May  2 08:09:50 2009
@@ -18,36 +18,41 @@
 package java.lang.reflect;
 
 /**
- * Represents a wildcard type, such as <code>?</code> or
- * <code>? extends Comparable</code>.
- * 
+ * This interface represents a wildcard type, such as the simple wildcard
+ * {@code '?'}, the upper bounded wildcard {@code '? extends Closeable'}, the
+ * multiple upper bounded wildcard {@code '? extends Closeable & Flushable'} or
+ * the lower bounded wildcard {@code '? super OutputStream'}.
+ *
  * @since 1.5
  */
 public interface WildcardType extends Type {
     /**
-     * Gets the array of types that represent the upper bounds of this type. The
-     * default upper bound is {@link Object}.
-     * 
-     * @return An array of {@link Type} instances.
+     * Returns the array of types that represent the upper bounds of this type.
+     * The default upper bound is {@code Object}.
+     *
+     * @return an array containing the upper bounds types
+     *
      * @throws TypeNotPresentException
-     *             if the component type points to a missing type.
+     *             if any of the bounds points to a missing type
      * @throws MalformedParameterizedTypeException
-     *             if the component type points to a type that can't be
-     *             instantiated for some reason.
+     *             if any bound points to a type that cannot be instantiated for
+     *             some reason
      */
     Type[] getUpperBounds();
 
     /**
-     * Gets the array of types that represent the lower bounds of this type. The
-     * default lower bound is <code>null</code>, in which case a empty array
-     * is returned.
-     * 
-     * @return An array of {@link Type} instances.
+     * Returns the array of types that represent the lower bounds of this type.
+     * The default lower bound is {@code null}, in which case an empty array is
+     * returned. Since only one lower bound is allowed, the returned array's
+     * length will never exceed one.
+     *
+     * @return an array containing the lower bounds types
+     *
      * @throws TypeNotPresentException
-     *             if the component type points to a missing type.
+     *             if any of the bounds points to a missing type
      * @throws MalformedParameterizedTypeException
-     *             if the component type points to a type that can't be
-     *             instantiated for some reason.
+     *             if any of the bounds points to a type that cannot be
+     *             instantiated for some reason
      */
     Type[] getLowerBounds();
 }



Mime
View raw message