harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r412851 - /incubator/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Enum.java
Date Thu, 08 Jun 2006 20:38:30 GMT
Author: tellison
Date: Thu Jun  8 13:38:29 2006
New Revision: 412851

URL: http://svn.apache.org/viewvc?rev=412851&view=rev
Log:
Add some javadoc.

Modified:
    incubator/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Enum.java

Modified: incubator/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Enum.java
URL: http://svn.apache.org/viewvc/incubator/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Enum.java?rev=412851&r1=412850&r2=412851&view=diff
==============================================================================
--- incubator/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Enum.java
(original)
+++ incubator/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Enum.java
Thu Jun  8 13:38:29 2006
@@ -23,9 +23,10 @@
 import org.apache.harmony.luni.util.Msg;
 
 /**
- * TODO Enum doc
+ * The superclass of all enumerated types.
  */
-public abstract class Enum<E extends Enum<E>> implements Serializable, Comparable<E>
{
+public abstract class Enum<E extends Enum<E>> implements Serializable,
+        Comparable<E> {
 
     private static final long serialVersionUID = 0L;
 
@@ -33,43 +34,102 @@
 
     private final int ordinal;
 
+    /**
+     * Constructor for enum subtypes.
+     * 
+     * @param name
+     *            the enum constant declared name.
+     * @param ordinal
+     *            the enum constant position ordinal.
+     */
     protected Enum(String name, int ordinal) {
         this.name = name;
         this.ordinal = ordinal;
     }
 
+    /**
+     * Answers the name of the enum constant. The name is the field as it
+     * appears in the <code>Enum</code> declaration.
+     * 
+     * @return the precise enum constant name.
+     * @see #toString()
+     */
     public final String name() {
         return name;
     }
 
+    /**
+     * Answers the position of the enum constant in the declaration. The first
+     * constant has and ordinal value of zero.
+     * 
+     * @return the constant's ordinal value.
+     */
     public final int ordinal() {
         return ordinal;
     }
 
+    /**
+     * Answer a string representation of the receiver suitable for display to a
+     * programmer.
+     * 
+     * @return the displayable string name.
+     */
     public String toString() {
         return "Enum:" + name;
     }
 
+    /**
+     * Answers true only if the receiver is equal to the argument. Since enums
+     * are unique this is equivalent to an identity test.
+     * 
+     * @return true if the receiver and argument are equal, otherwise return
+     *         false.
+     */
     public final boolean equals(Object other) {
         return this == other;
     }
 
+    /**
+     * Answers the hash of the receiver.
+     * 
+     * @return the hash code.
+     */
     public final int hashCode() {
         return ordinal + (name == null ? 0 : name.hashCode());
     }
 
     /**
-     * Enums are singletons, they may not be cloned.
+     * Enums are singletons, they may not be cloned. This method always throws a
+     * {@link CloneNotSupportedException}.
+     * 
+     * @return does not return.
      */
     protected final Object clone() throws CloneNotSupportedException {
         // KA004=Enums may not be cloned
         throw new CloneNotSupportedException(Msg.getString("KA004"));
     }
 
+    /**
+     * Answers the comparative ordering of the receiver and the given argument.
+     * If the receiver is naturally ordered before the actual argument then the
+     * result is negative, if the receiver is naturally ordered in equal
+     * position to the actual argument then the result is zero, and if the
+     * receiver is naturally ordered after the actual argument then the result
+     * is positive.
+     * 
+     * @return negative, zero, or positive value depending upon before, equal,
+     *         or after natural order respectively.
+     * @see Comparable#compareTo(Object)
+     */
     public final int compareTo(E o) {
         return ordinal - o.ordinal;
     }
 
+    /**
+     * Answers the enum constant's declaring class.
+     * 
+     * @return the class object representing the constant's enum type.
+     */
     public final Class<E> getDeclaringClass() {
         Class myClass = getClass();
         Class mySuperClass = myClass.getSuperclass();
@@ -79,6 +139,22 @@
         return mySuperClass;
     }
 
+    /**
+     * Answers the named constant of the given enum type.
+     * 
+     * @param enumType
+     *            the class of the enumerated type to search for the constant
+     *            value.
+     * @param name
+     *            the name of the constant value to find.
+     * @return the enum constant
+     * @throws NullPointerException
+     *             if either the <code>enumType</code> or <code>name</code>
+     *             are <code>null</code>.
+     * @throws IllegalArgumentException
+     *             if <code>enumType</code> is not an enumerated type or does
+     *             not have a constant value called <code>name</code>.
+     */
     public static <T extends Enum<T>> T valueOf(Class<T> enumType, String
name) {
         if ((enumType == null) || (name == null)) {
             // KA001=Argument must not be null
@@ -95,23 +171,25 @@
             }
         }
         // KA006={0} is not a constant in the enum type {1}
-        throw new IllegalArgumentException(Msg.getString("KA006", name, enumType));
+        throw new IllegalArgumentException(Msg.getString("KA006", name,
+                enumType));
     }
 
     /*
-     * Helper to invoke the values() static method on T and answer
-     * the result.  Returns null if there is a problem.
+     * Helper to invoke the values() static method on T and answer the result.
+     * Returns null if there is a problem.
      */
     static <T extends Enum<T>> T[] getValues(final Class<T> enumType) {
         try {
-            Method values = AccessController.doPrivileged(
-                new PrivilegedExceptionAction<Method>() {
-                    public Method run() throws Exception {
-                        Method valsMethod = enumType.getMethod("values", (Class[])null);
-                        valsMethod.setAccessible(true);
-                        return valsMethod;
-                    }
-                });
+            Method values = AccessController
+                    .doPrivileged(new PrivilegedExceptionAction<Method>() {
+                        public Method run() throws Exception {
+                            Method valsMethod = enumType.getMethod("values",
+                                    (Class[]) null);
+                            valsMethod.setAccessible(true);
+                            return valsMethod;
+                        }
+                    });
             return (T[]) values.invoke(enumType, null);
         } catch (Exception e) {
             return null;



Mime
View raw message