2006-04-17 Andrew John Hughes <gnu_andrew@member.fsf.org>

	* java/lang/Enum.java: Documented.

1 files changed, 103 insertions, 1 deletions

diff --git a/java/lang/Enum.java b/java/lang/Enum.java
index 61a0a638c..82b20e8e2 100644
--- a/java/lang/Enum.java
+++ b/java/lang/Enum.java
@@ -41,8 +41,15 @@ import java.io.Serializable;
 import java.lang.reflect.Field;
 
 /**
+ * This class represents a Java enumeration.  All enumerations are
+ * subclasses of this class.
+ *
+ * @author Tom Tromey (tromey@redhat.com)
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  * @since 1.5
  */
+/* FIXME[GENERICS]: Should be Enum<T extends Enum<T>>
+   and Comparable<T> */
 public abstract class Enum
   implements Comparable, Serializable
 {
@@ -52,9 +59,24 @@ public abstract class Enum
    */
   private static final long serialVersionUID = -4300926546619394005L;
 
+  /**
+   * The name of this enum constant.
+   */
   String name;
+
+  /**
+   * The number of this enum constant.  Each constant is given a number
+   * which matches the order in which it was declared, starting with zero.
+   */
   int ordinal;
 
+  /**
+   * This constructor is used by the compiler to create enumeration constants.
+   *
+   * @param name the name of the enumeration constant.
+   * @param ordinal the number of the enumeration constant, based on the
+   *                declaration order of the constants and starting from zero.
+   */
   protected Enum(String name, int ordinal)
   {
     this.name = name;
@@ -69,6 +91,7 @@ public abstract class Enum
    * @exception IllegalArgumentException when there is no value s in
    * the enum etype.
    */
+  /* FIXME[GENERICS]: Should be <S extends Enum<S>> S valueOf(Class<S>) */
   public static Enum valueOf(Class etype, String s)
   {
     if (etype == null || s == null)
@@ -79,7 +102,8 @@ public abstract class Enum
         Field f = etype.getDeclaredField(s);
         if (! f.isEnumConstant())
           throw new IllegalArgumentException(s);
-        return (Enum) f.get(null);
+	/* FIXME[GENERICS]: Should cast to S */
+        return (Enum) f.get(null); 
       }
     catch (NoSuchFieldException exception)
       {
@@ -91,22 +115,58 @@ public abstract class Enum
       }
   }
 
+  /**
+   * Returns true if this enumeration is equivalent to the supplied object,
+   * <code>o</code>.  Only one instance of an enumeration constant exists,
+   * so the comparison is simply done using <code>==</code>.
+   *
+   * @param o the object to compare to this.
+   * @return true if <code>this == o</code>.
+   */
   public final boolean equals(Object o)
   {
     // Enum constants are singular, so we need only compare `=='.
     return this == o;
   }
 
+  /**
+   * Returns the hash code of this constant.  This is simply the ordinal.
+   *
+   * @return the hash code of this enumeration constant.
+   */
   public final int hashCode()
   {
     return ordinal;
   }
 
+  /**
+   * Returns a textual representation of this enumeration constant.
+   * By default, this is simply the declared name of the constant, but
+   * specific enumeration types may provide an implementation more suited
+   * to the data being stored.
+   *
+   * @return a textual representation of this constant.
+   */
   public String toString()
   {
     return name;
   }
 
+  /**
+   * Returns an integer which represents the relative ordering of this
+   * enumeration constant.  Enumeration constants are ordered by their
+   * ordinals, which represents their declaration order.  So, comparing
+   * two identical constants yields zero, while one declared prior to
+   * this returns a positive integer and one declared after yields a
+   * negative integer.
+   *
+   * @param e the enumeration constant to compare.
+   * @return a negative integer if <code>e.ordinal < this.ordinal</code>,
+   *         zero if <code>e.ordinal == this.ordinal</code> and a positive
+   *         integer if <code>e.ordinal > this.ordinal</code>.
+   * @throws ClassCastException if <code>e</code> is not an enumeration
+   *                            constant of the same class.
+   */ 
   public final int compareTo(Enum e)
   {
     if (getDeclaringClass() != e.getDeclaringClass())
@@ -114,26 +174,68 @@ public abstract class Enum
     return ordinal - e.ordinal;
   }
 
+  /**
+   * Returns an integer which represents the relative ordering of this
+   * enumeration constant.  Enumeration constants are ordered by their
+   * ordinals, which represents their declaration order.  So, comparing
+   * two identical constants yields zero, while one declared prior to
+   * this returns a positive integer and one declared after yields a
+   * negative integer.
+   *
+   * @param e the enumeration constant to compare.
+   * @return a negative integer if <code>e.ordinal < this.ordinal</code>,
+   *         zero if <code>e.ordinal == this.ordinal</code> and a positive
+   *         integer if <code>e.ordinal > this.ordinal</code>.
+   * @throws ClassCastException if <code>e</code> is not an enumeration
+   *                            constant of the same class.
+   */ 
+  /* FIXME[GENERICS]: Remove this method */
   public final int compareTo(Object o)
   {
     return compareTo((Enum)o);
   }
 
+  /**
+   * Cloning of enumeration constants is prevented, to maintain their
+   * singleton status.
+   *
+   * @return the cloned object.
+   * @throws CloneNotSupportedException as enumeration constants can't be
+   *         cloned.
+   */
   protected final Object clone() throws CloneNotSupportedException
   {
     throw new CloneNotSupportedException("can't clone an enum constant");
   }
 
+  /**
+   * Returns the name of this enumeration constant.
+   *
+   * @return the name of the constant.
+   */
   public final String name()
   {
     return name;
   }
 
+  /**
+   * Returns the number of this enumeration constant, which represents
+   * the order in which it was originally declared, starting from zero.
+   * 
+   * @return the number of this constant.
+   */
   public final int ordinal()
   {
     return ordinal;
   }
 
+  /**
+   * Returns the type of this enumeration constant.  This is the class
+   * corresponding to the declaration of the enumeration.
+   *
+   * @return the type of this enumeration constant.
+   */
+  /* FIXME[GENERICS]: Should return Class<T> */
   public final Class getDeclaringClass()
   {
     Class k = getClass();