I'm committing the attached patch which adds documentation to java.lang.Enum.
Changelog:
2006-04-17 Andrew John Hughes <[EMAIL PROTECTED]>
* java/lang/Enum.java: Documented.
--
Andrew :-)
Please avoid sending me Microsoft Office (e.g. Word, PowerPoint) attachments.
See http://www.fsf.org/philosophy/no-word-attachments.html
If you use Microsoft Office, support movement towards the end of vendor lock-in:
http://opendocumentfellowship.org/petition/
"Value your freedom, or you will lose it, teaches history.
`Don't bother us with politics' respond those who don't want to learn."
-- Richard Stallman
Escape the Java Trap with GNU Classpath!
http://www.gnu.org/philosophy/java-trap.html
public class gcj extends Freedom implements Java { ... }
Index: java/lang/Enum.java
===================================================================
RCS file: /cvsroot/classpath/classpath/java/lang/Enum.java,v
retrieving revision 1.1.2.8
diff -u -3 -p -u -r1.1.2.8 Enum.java
--- java/lang/Enum.java 28 Mar 2006 18:51:01 -0000 1.1.2.8
+++ java/lang/Enum.java 17 Apr 2006 18:48:55 -0000
@@ -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 ([EMAIL PROTECTED])
+ * @author Andrew John Hughes ([EMAIL PROTECTED])
* @since 1.5
*/
public abstract class Enum<T extends Enum<T>>
@@ -52,9 +57,24 @@ public abstract class Enum<T extends Enu
*/
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 Enu
}
}
+ /**
+ * 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 Enu
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();
signature.asc
Description: Digital signature
