harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r767886 - /harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/
Date Thu, 23 Apr 2009 10:45:29 GMT
Author: tellison
Date: Thu Apr 23 10:45:28 2009
New Revision: 767886

URL: http://svn.apache.org/viewvc?rev=767886&view=rev
Log:
Apply patch for HARMONY-6169 (Javadocs for java.lang.annotation.*)

Modified:
    harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Annotation.java
    harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/AnnotationFormatError.java
    harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/AnnotationTypeMismatchException.java
    harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Documented.java
    harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/ElementType.java
    harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/IncompleteAnnotationException.java
    harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Inherited.java
    harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Retention.java
    harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/RetentionPolicy.java
    harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Target.java

Modified: harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Annotation.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Annotation.java?rev=767886&r1=767885&r2=767886&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Annotation.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Annotation.java
Thu Apr 23 10:45:28 2009
@@ -18,52 +18,108 @@
 package java.lang.annotation;
 
 /**
- * <p>
- * The interface implemented by all annotations. This interface is NOT an
- * annotation itself and any interface that extends this one is NOT an
- * annotation either.
- * </p>
- * 
+ * Defines the interface implemented by all annotations. Note that the interface
+ * itself is <i>not</i> an annotation, and neither is an interface that simply
+ * extends this one. Only the compiler is able to create proper annotation
+ * types.
+ *
  * @since 1.5
  */
 public interface Annotation {
 
     /**
-     * <p>
      * Returns the type of this annotation.
-     * </p>
-     * 
-     * @return A Class instance.
+     *
+     * @return A {@code Class} instance representing the annotation type.
      */
     Class<? extends Annotation> annotationType();
 
     /**
-     * <p>
      * Determines whether or not this annotation is equivalent to the annotation
-     * passed.
-     * </p>
+     * passed. This is determined according to the following rules:
      * 
-     * @param obj The object to compare to.
-     * @return <code>true</code> if <code>obj</code> is equal to
this,
-     *         otherwise <code>false</code>.
+     * <ul>
+     *     <li>
+     *         Two annotations {@code x} and {@code y} are equal if and only if
+     *         they are members of the same annotation type and all the member
+     *         values of {@code x} are equal to the corresponding member values
+     *         of {@code y}.
+     *     </li>
+     *     <li>
+     *         The equality of primitive member values {@code x} and {@code y}
+     *         is determined (in a way similar to) using the corresponding
+     *         wrapper classes. For example,
+     *         {@code Integer.valueOf(x).equals(Integer.valueOf(y)} is used for
+     *         {@code int} values. Note: The behavior is identical to the
+     *         {@code ==} operator for all but the floating point type, so the
+     *         implementation may as well use {@code ==} in these cases for
+     *         performance reasons. Only for the {@code float} and {@code double}
+     *         types the result will be slightly different: {@code NaN} is equal
+     *         to {@code NaN}, and {@code -0.0} is equal to {@code 0.0}, both of
+     *         which is normally not the case.
+     *     </li>
+     *     <li>
+     *         The equality of two array member values {@code x} and {@code y}
+     *         is determined using the corresponding {@code equals(x, y)}
+     *         helper function in {@link java.util.Arrays}.
+     *     </li>
+     *     <li>
+     *         The hash code for all other member values is determined by simply
+     *         calling their {@code equals()} method.
+     *     </li>
+     * </ul>
+     *
+     * @param obj
+     *            The object to compare to.
+     *
+     * @return {@code true} if {@code obj} is equal to this annotation,
+     *            {@code false} otherwise.
      */
     boolean equals(Object obj);
 
     /**
-     * <p>
-     * Returns the hash value of this annotation.
-     * </p>
+     * Returns the hash code of this annotation. The hash code is determined
+     * according to the following rules:
      * 
-     * @return The hash value.
+     * <ul>
+     *     <li>
+     *         The hash code of an annotation is the sum of the hash codes of
+     *         its annotation members.
+     *     </li>
+     *     <li>
+     *         The hash code of an annotation member is calculated as {@code
+     *         (0x7f * n.hashCode()) ^ v.hashCode())}, where {@code n} is the
+     *         name of the member (as a {@code String}) and {@code v} its value.
+     *     </li>
+     *     <li>
+     *         The hash code for a primitive member value is determined using
+     *         the corresponding wrapper type. For example, {@code
+     *         Integer.valueOf(v).hashCode()} is used for an {@code int} value
+     *         {@code v}.
+     *     </li>
+     *     <li>
+     *         The hash code for an array member value {@code v} is determined
+     *         using the corresponding {@code hashCode(v)} helper function in
+     *         {@link java.util.Arrays}.
+     *     </li>
+     *     <li>
+     *         The hash code for all other member values is determined by simply
+     *         calling their {@code hashCode} method.
+     *     </li>
+     * </ul>
+     *
+     * @return the hash code.
      */
     int hashCode();
 
     /**
-     * <p>
-     * Returns a String representation of this annotation.
-     * </p>
+     * Returns a {@code String} representation of this annotation. It is not
+     * strictly defined what the representation has to look like, but it usually
+     * consists of the name of the annotation, preceded by a "@". If the
+     * annotation contains field members, their names and values are also
+     * included in the result.
      * 
-     * @return The String that represents this annotation.
+     * @return the {@code String} that represents this annotation.
      */
     String toString();
 }

Modified: harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/AnnotationFormatError.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/AnnotationFormatError.java?rev=767886&r1=767885&r2=767886&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/AnnotationFormatError.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/AnnotationFormatError.java
Thu Apr 23 10:45:28 2009
@@ -18,10 +18,11 @@
 package java.lang.annotation;
 
 /**
- * <p>
- * Indicates that an annotation in a class file is incorrectly formatted.
- * </p>
- * 
+ * Indicates that an annotation in the binary representation of a class is
+ * syntactically incorrect and the annotation parser is unable to process it.
+ * This exception is unlikely to ever occur, given that the code has been
+ * compiled by an ordinary Java compiler.
+ *
  * @since 1.5
  */
 public class AnnotationFormatError extends Error {
@@ -29,36 +30,34 @@
     private static final long serialVersionUID = -4256701562333669892L;
 
     /**
-     * <p>
      * Constructs an instance with the message provided.
-     * </p>
-     * 
-     * @param message The details of the error.
+     *
+     * @param message
+     *            the details of the error.
      */
     public AnnotationFormatError(String message) {
         super(message);
     }
 
     /**
-     * <p>
      * Constructs an instance with a message and a cause.
-     * </p>
-     * 
-     * @param message The details of the error.
-     * @param cause The cause of the error or <code>null</code> if none.
+     *
+     * @param message
+     *            the details of the error.
+     * @param cause
+     *            the cause of the error or {@code null} if none.
      */
     public AnnotationFormatError(String message, Throwable cause) {
         super(message, cause);
     }
 
     /**
-     * <p>
-     * Constructs an instance with a cause. If the cause is NOT
-     * <code>null</code>, then <code>cause.toString()</code> is used
as the
+     * Constructs an instance with a cause. If the cause is not
+     * {@code null}, then {@code cause.toString()} is used as the
      * error's message.
-     * </p>
-     * 
-     * @param cause The cause of the error or <code>null</code> if none.
+     *
+     * @param cause
+     *            the cause of the error or {@code null} if none.
      */
     public AnnotationFormatError(Throwable cause) {
         super(cause == null ? null : cause.toString(), cause);

Modified: harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/AnnotationTypeMismatchException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/AnnotationTypeMismatchException.java?rev=767886&r1=767885&r2=767886&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/AnnotationTypeMismatchException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/AnnotationTypeMismatchException.java
Thu Apr 23 10:45:28 2009
@@ -22,11 +22,9 @@
 import org.apache.harmony.annotation.internal.nls.Messages;
 
 /**
- * <p>
  * Indicates that an annotation type has changed since it was compiled or
  * serialized.
- * </p>
- * 
+ *
  * @since 1.5
  */
 public class AnnotationTypeMismatchException extends RuntimeException {
@@ -38,12 +36,14 @@
     private String foundType;
 
     /**
-     * <p>
      * Constructs an instance for the given type element and the type found.
-     * </p>
-     * 
-     * @param element The annotation type element.
-     * @param foundType The invalid type that was found.
+     *
+     * @param element
+     *            the annotation type element.
+     * @param foundType
+     *            the invalid type that was found. This is actually the textual
+     *            type description found in the binary class representation,
+     *            so it may not be human-readable.
      */
     public AnnotationTypeMismatchException(Method element, String foundType) {
         super(Messages.getString("annotation.1", element, foundType)); //$NON-NLS-1$
@@ -52,22 +52,18 @@
     }
 
     /**
-     * <p>
-     * The method object for the invalid type.
-     * </p>
-     * 
-     * @return A {@link Method} instance.
+     * Returns the method object for the invalid type.
+     *
+     * @return a {@link Method} instance.
      */
     public Method element() {
         return element;
     }
 
     /**
-     * <p>
-     * The invalid type.
-     * </p>
-     * 
-     * @return A String describing the invalid data.
+     * Returns the invalid type.
+     *
+     * @return a string describing the invalid data.
      */
     public String foundType() {
         return foundType;

Modified: harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Documented.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Documented.java?rev=767886&r1=767885&r2=767886&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Documented.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Documented.java
Thu Apr 23 10:45:28 2009
@@ -18,11 +18,9 @@
 package java.lang.annotation;
 
 /**
- * <p>
- * A meta-annotation used to indicate that a type's annotation are documented
- * and part of the public API.
- * </p>
- * 
+ * Defines a meta-annotation for indicating that an annotation is documented and
+ * considered part of the public API.
+ *
  * @since 1.5
  */
 @Documented

Modified: harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/ElementType.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/ElementType.java?rev=767886&r1=767885&r2=767886&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/ElementType.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/ElementType.java
Thu Apr 23 10:45:28 2009
@@ -18,59 +18,43 @@
 package java.lang.annotation;
 
 /**
- * <p>
- * An enumeration of element types.
- * </p>
- * 
+ * Defines an enumeration for Java program elements. It is used in conjunction
+ * with the {@link Target} meta-annotation to restrict the use of an annotation
+ * to certain program elements.
+ *
  * @since 1.5
  */
 public enum ElementType {
     /**
-     * <p>
      * Class, interface or enum declaration.
-     * </p>
      */
     TYPE,
     /**
-     * <p>
      * Field declaration.
-     * </p>
      */
     FIELD,
     /**
-     * <p>
      * Method declaration.
-     * </p>
      */
     METHOD,
     /**
-     * <p>
      * Parameter declaration.
-     * </p>
      */
     PARAMETER,
     /**
-     * <p>
      * Constructor declaration.
-     * </p>
      */
     CONSTRUCTOR,
     /**
-     * <p>
      * Local variable declaration.
-     * </p>
      */
     LOCAL_VARIABLE,
     /**
-     * <p>
      * Annotation type declaration.
-     * </p>
      */
     ANNOTATION_TYPE,
     /**
-     * <p>
      * Package declaration.
-     * </p>
      */
     PACKAGE
 }

Modified: harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/IncompleteAnnotationException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/IncompleteAnnotationException.java?rev=767886&r1=767885&r2=767886&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/IncompleteAnnotationException.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/IncompleteAnnotationException.java
Thu Apr 23 10:45:28 2009
@@ -20,12 +20,10 @@
 import org.apache.harmony.annotation.internal.nls.Messages;
 
 /**
- * <p>
  * Indicates that an element of an annotation type was accessed that was added
  * after the type was compiled or serialized. This does not apply to new
  * elements that have default values.
- * </p>
- * 
+ *
  * @since 1.5
  */
 public class IncompleteAnnotationException extends RuntimeException {
@@ -37,13 +35,13 @@
     private String elementName;
 
     /**
-     * <p>
      * Constructs an instance with the incomplete annotation type and the name
      * of the element that's missing.
-     * </p>
-     * 
-     * @param annotationType The annotation type.
-     * @param elementName The name of the incomplete element.
+     *
+     * @param annotationType
+     *            the annotation type.
+     * @param elementName
+     *            the name of the incomplete element.
      */
     public IncompleteAnnotationException(
             Class<? extends Annotation> annotationType, String elementName) {
@@ -53,22 +51,18 @@
     }
 
     /**
-     * <p>
-     * The annotation type.
-     * </p>
-     * 
-     * @return A Class instance.
+     * Returns the annotation type.
+     *
+     * @return a Class instance.
      */
     public Class<? extends Annotation> annotationType() {
         return annotationType;
     }
 
     /**
-     * <p>
-     * The incomplete element's name.
-     * </p>
-     * 
-     * @return The name of the element.
+     * Returns the incomplete element's name.
+     *
+     * @return the name of the element.
      */
     public String elementName() {
         return elementName;

Modified: harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Inherited.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Inherited.java?rev=767886&r1=767885&r2=767886&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Inherited.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Inherited.java
Thu Apr 23 10:45:28 2009
@@ -18,11 +18,9 @@
 package java.lang.annotation;
 
 /**
- * <p>
- * A meta-annotation used to indicate that an annotation is automatically
+ * Defines a meta-annotation for indicating that an annotation is automatically
  * inherited.
- * </p>
- * 
+ *
  * @since 1.5
  */
 @Documented

Modified: harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Retention.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Retention.java?rev=767886&r1=767885&r2=767886&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Retention.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Retention.java
Thu Apr 23 10:45:28 2009
@@ -18,11 +18,10 @@
 package java.lang.annotation;
 
 /**
- * <p>
- * A meta-annotation used to determine the scope of retention for an annotation.
- * The default value is {@link RetentionPolicy#RUNTIME}.
- * </p>
- * 
+ * Defines a meta-annotation for determining the scope of retention for an
+ * annotation. If the retention annotation is not set {@code
+ * RetentionPolicy.CLASS} is used as default retention.
+ *
  * @since 1.5
  */
 @Documented

Modified: harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/RetentionPolicy.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/RetentionPolicy.java?rev=767886&r1=767885&r2=767886&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/RetentionPolicy.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/RetentionPolicy.java
Thu Apr 23 10:45:28 2009
@@ -18,31 +18,25 @@
 package java.lang.annotation;
 
 /**
- * <p>
- * An enumeration for annotation retention policies.
- * </p>
- * 
+ * Defines an enumeration for annotation retention policies. Used in conjunction
+ * with the {@link Retention} annotation to specify an annotation's time-to-live
+ * in the overall development life cycle.
+ *
  * @since 1.5
  */
 public enum RetentionPolicy {
     /**
-     * <p>
      * Annotation is only available in the source code.
-     * </p>
      */
     SOURCE,
     /**
-     * <p>
      * Annotation is available in the source code and in the class file, but not
      * at runtime. This is the default policy.
-     * </p>
      */
     CLASS,
     /**
-     * <p>
      * Annotation is available in the source code, the class file and is
      * available at runtime.
-     * </p>
      */
     RUNTIME
 }

Modified: harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Target.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Target.java?rev=767886&r1=767885&r2=767886&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Target.java
(original)
+++ harmony/enhanced/classlib/trunk/modules/annotation/src/main/java/java/lang/annotation/Target.java
Thu Apr 23 10:45:28 2009
@@ -18,11 +18,9 @@
 package java.lang.annotation;
 
 /**
- * <p>
- * A meta-annotation used to determine what {@link ElementType}s an annotation
- * can be applied to.
- * </p>
- * 
+ * Defines a meta-annotation for determining what {@link ElementType}s an
+ * annotation can be applied to.
+ *
  * @since 1.5
  */
 @Documented



Mime
View raw message