Minor modifications and added documentation to model cache.

src/main/java/com/github/droidfu/cachefu/CachedList.java

@@ -6,59 +6,148 @@
 import android.os.Parcel;
 import android.os.Parcelable;
 
+/**
+ * Superclass of all list objects to be stored in {@link ModelCache}.
+ * 
+ * Operates just as standard cached object, and contains an array list of objects.
+ * 
+ * <b>Must</b> be initialized with the class of the objects stored, as this is used in
+ * parcelling/unparcelling.
+ * 
+ * In order to ensure thread-safe use of list (such as iteration), use the {@link #getList()}
+ * method, creating a copy of the list in its current state.
+ * 
+ * @author michaelengland
+ * 
+ * @param <CO>
+ *            Type of cached models to be stored in list
+ */
 public class CachedList<CO extends CachedModel> extends CachedModel {
 
+    /**
+     * Class type of object list
+     */
     protected Class<? extends CachedModel> clazz;
+    /**
+     * List of objects.
+     */
     protected ArrayList<CO> list;
 
+    /**
+     * Simple parameter-less constructor. <b>Must</b> also have parameter-less constructor in
+     * subclasses in order for parceling to work.
+     * 
+     * <b>Do not use this constructor when creating a list, use one setting class instead.</b>
+     */
     public CachedList() {
         list = new ArrayList<CO>();
     }
 
+    /**
+     * Constructor setting variables from parcel. Same as using a blank constructor and calling
+     * readFromParcel.
+     * 
+     * @param source
+     *            Parcel to be read from.
+     * @throws IOException
+     */
+    public CachedList(Parcel source) throws IOException {
+        super(source);
+    }
+
+    /**
+     * Constructor initializing class of objects stored.
+     * 
+     * @param clazz
+     *            Required for parcelling and unparcelling of list
+     */
     public CachedList(Class<? extends CachedModel> clazz) {
-        initList(clazz);
+        this.clazz = clazz;
         list = new ArrayList<CO>();
     }
 
+    /**
+     * Constructor initializing class of objects stored as well as initial length of list.
+     * 
+     * @param clazz
+     *            Required for parcelling and unparcelling of list
+     * @param initialLength
+     *            Initial length of list
+     */
     public CachedList(Class<? extends CachedModel> clazz, int initialLength) {
-        initList(clazz);
+        this.clazz = clazz;
         list = new ArrayList<CO>(initialLength);
     }
 
-    public CachedList(Parcel source) throws IOException {
-        super(source);
-    }
-
+    /**
+     * Constructor initializing class of objects stored as well as id used in key generation.
+     * 
+     * @param clazz
+     *            Required for parcelling and unparcelling of list
+     * @param id
+     *            ID of new list (used when generating cache key).
+     */
     public CachedList(Class<? extends CachedModel> clazz, String id) {
         super(id);
-        initList(clazz);
-        list = new ArrayList<CO>();
-    }
-
-    private void initList(Class<? extends CachedModel> clazz) {
         this.clazz = clazz;
+        list = new ArrayList<CO>();
     }
 
+    /**
+     * Synchronized method to get a copy of the list in its current state. This should be used when
+     * iterating over the list in order to avoid thread-unsafe operations.
+     * 
+     * @return Copy of list in its current state
+     */
     public synchronized ArrayList<CO> getList() {
         return new ArrayList<CO>(list);
     }
 
+    /**
+     * Synchronized method used to append an object to the list.
+     * 
+     * @param cachedObject
+     *            Object to add to list
+     */
     public synchronized void add(CO cachedObject) {
         list.add(cachedObject);
     }
 
+    /**
+     * Synchronized method used to set an object at a location in the list.
+     * 
+     * @param index
+     *            Index of item to set
+     * @param cachedObject
+     *            Object to set in list
+     */
     public synchronized void set(int index, CO cachedObject) {
         list.set(index, cachedObject);
     }
 
+    /**
+     * Synchronized method used to get an object from the live list.
+     * 
+     * @param index
+     *            Index of item in list
+     * @return Item in list
+     */
     public synchronized CO get(int index) {
         return list.get(index);
     }
 
+    /**
+     * Synchronized method used to return size of list.
+     * 
+     * @return Size of list
+     */
     public synchronized int size() {
         return list.size();
     }
 
+    /**
+     * @see java.lang.Object#equals(java.lang.Object)
+     */
     @Override
     public synchronized boolean equals(Object o) {
         if (!(o instanceof CachedList)) {
@@ -69,14 +158,19 @@ public synchronized boolean equals(Object o) {
         return clazz.equals(that.clazz) && list.equals(that.list);
     }
 
+    /**
+     * @see com.github.droidfu.cachefu.CachedModel#createKey(java.lang.String)
+     */
     @Override
     public synchronized String createKey(String id) {
         return "list_" + id;
     }
 
     @Override
     public boolean reload(ModelCache modelCache) {
+        // First reload list object
         boolean result = super.reload(modelCache);
+        // Then reload each item in list
         for (CachedModel listModel : list) {
             if (listModel.reload(modelCache)) {
                 result = true;
@@ -85,6 +179,10 @@ public boolean reload(ModelCache modelCache) {
         return result;
     }
 
+    /**
+     * @see com.github.droidfu.cachefu.CachedModel#reloadFromCachedModel(com.github.droidfu.cachefu.ModelCache,
+     *      com.github.droidfu.cachefu.CachedModel)
+     */
     @Override
     public synchronized boolean reloadFromCachedModel(ModelCache modelCache, CachedModel cachedModel) {
         @SuppressWarnings("unchecked")
@@ -94,8 +192,14 @@ public synchronized boolean reloadFromCachedModel(ModelCache modelCache, CachedM
         return false;
     }
 
+    /**
+     * Creator object used for parcelling
+     */
     public static final Creator<CachedList<CachedModel>> CREATOR = new Parcelable.Creator<CachedList<CachedModel>>() {
 
+        /**
+         * @see android.os.Parcelable.Creator#createFromParcel(android.os.Parcel)
+         */
         @SuppressWarnings({ "rawtypes", "unchecked" })
         @Override
         public CachedList<CachedModel> createFromParcel(Parcel source) {
@@ -107,6 +211,9 @@ public CachedList<CachedModel> createFromParcel(Parcel source) {
             }
         }
 
+        /**
+         * @see android.os.Parcelable.Creator#newArray(int)
+         */
         @SuppressWarnings("unchecked")
         @Override
         public CachedList<CachedModel>[] newArray(int size) {
@@ -115,10 +222,14 @@ public CachedList<CachedModel>[] newArray(int size) {
 
     };
 
+    /**
+     * @see com.github.droidfu.cachefu.CachedModel#readFromParcel(android.os.Parcel)
+     */
     @SuppressWarnings({ "unchecked", "rawtypes" })
     @Override
     public void readFromParcel(Parcel source) throws IOException {
         super.readFromParcel(source);
+        // Read class from parcel, then load class and use creator to generate new object from data
         String className = source.readString();
         try {
             clazz = (Class<? extends CachedModel>) Class.forName(className);
@@ -128,9 +239,13 @@ public void readFromParcel(Parcel source) throws IOException {
         }
     }
 
+    /**
+     * @see com.github.droidfu.cachefu.CachedModel#writeToParcel(android.os.Parcel, int)
+     */
     @Override
     public void writeToParcel(Parcel dest, int flags) {
         super.writeToParcel(dest, flags);
+        // Write class name to parcel before object, so can be loaded correctly back in
         dest.writeString(clazz.getCanonicalName());
         dest.writeTypedList(list);
     }