svn commit: r1859103 - /pivot/trunk/core/src/org/apache/pivot/collections/EnumList.java

[rw...@apache.org]

Author: rwhitcomb
Date: Fri May 10 21:05:12 2019
New Revision: 1859103

URL: http://svn.apache.org/viewvc?rev=1859103&view=rev
Log:
Add some explanatory Javadoc to the EnumList class to explain how to use it.

Modified:
    pivot/trunk/core/src/org/apache/pivot/collections/EnumList.java

Modified: pivot/trunk/core/src/org/apache/pivot/collections/EnumList.java
URL: http://svn.apache.org/viewvc/pivot/trunk/core/src/org/apache/pivot/collections/EnumList.java?rev=1859103&r1=1859102&r2=1859103&view=diff
==============================================================================
--- pivot/trunk/core/src/org/apache/pivot/collections/EnumList.java (original)
+++ pivot/trunk/core/src/org/apache/pivot/collections/EnumList.java Fri May 10 21:05:12 2019
@@ -28,6 +28,13 @@ import org.apache.pivot.util.Utils;
 
 /**
  * A read-only implementation of the {@link List} interface that is backed by an enum.
+ * <p> An {@code EnumList} cannot be modified once constructed and only ever contains all the
+ * enum constant values defined in the class. As such, the {@code "add"} and {@code "remove"}
+ * (and related) methods throw exceptions.
+ * <p> This class is meant to facilitate using enum constants as elements in a dropdown list
+ * (for instance). A useful way to do this is to override the {@code "toString()"} method of
+ * the enum to provide a human-readable version of the enum constant value, which will then
+ * appear in the UI.
  */
 public class EnumList<E extends Enum<E>> implements List<E>, Serializable {
     private static final long serialVersionUID = 5104856822133576300L;
@@ -63,6 +70,11 @@ public class EnumList<E extends Enum<E>>
 
     private transient ListListenerList<E> listListeners = new ListListenerList<>();
 
+    /**
+     * Construct the full list populated by the enum constants of the given class.
+     *
+     * @param enumClass The enum class whose constant values are used to fully populate the list.
+     */
     public EnumList(Class<E> enumClass) {
         this.enumClass = enumClass;
         items = enumClass.getEnumConstants();