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

	* java/lang/Enum.java: Documented.

2 files changed, 85 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 50f26c07a..a9a7310af 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2006-04-17  Andrew John Hughes  <gnu_andrew@member.fsf.org>
 
+	* java/lang/Enum.java: Documented.
+
+2006-04-17  Andrew John Hughes  <gnu_andrew@member.fsf.org>
+
 	* gnu/java/lang/InstrumentationImpl.java:
 	Moved from java.lang.
 	* java/lang/InstrumentationImpl.java:
diff --git a/java/lang/Enum.java b/java/lang/Enum.java
index c4160ebaa..374940333 100644
--- a/java/lang/Enum.java
+++ b/java/lang/Enum.java
@@ -41,6 +41,11 @@ 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
  */
 public abstract class Enum<T extends Enum<T>>
@@ -52,9 +57,24 @@ public abstract class Enum<T extends Enum<T>>
    */
   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;
@@ -92,22 +112,58 @@ public abstract class Enum<T extends Enum<T>>
       }
   }
 
+  /**
+   * 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(T e)
   {
     if (getDeclaringClass() != e.getDeclaringClass())
@@ -115,21 +171,46 @@ public abstract class Enum<T extends Enum<T>>
     return ordinal - e.ordinal;
   }
 
+  /**
+   * 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.
+   */
   public final Class<T> getDeclaringClass()
   {
     Class k = getClass();