comments, cleanup

13 files changed, 72 insertions, 24 deletions

diff --git a/app/src/main/java/org/rssin/android/FeedsList.java b/app/src/main/java/org/rssin/android/FeedsList.java
index 6a0b7fc..72a56d1 100644
--- a/app/src/main/java/org/rssin/android/FeedsList.java
+++ b/app/src/main/java/org/rssin/android/FeedsList.java
@@ -1,7 +1,6 @@
 package org.rssin.android;
 
 import android.content.Context;
-import android.util.Log;
 
 import org.rssin.rssin.Feed;
 
@@ -10,7 +9,7 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * A list of filters that can be saved using the DefaultStorageProvider
+ * A list of feeds that can be saved using the DefaultStorageProvider
  * @author Camil Staps
  */
 class FeedsList {
@@ -50,7 +49,7 @@ class FeedsList {
     }
 
     /**
-     * Save all filters
+     * Save all feeds
      * @throws Exception if serializing or saving failed
      */
     public synchronized void save() throws Exception {
@@ -67,13 +66,4 @@ class FeedsList {
         }
     }
 
-    public Feed getFeedFromHashCode(int hashcode) {
-        for (Feed feed : feeds) {
-            if (feed.hashCode() == hashcode) {
-                return feed;
-            }
-        }
-        return null;
-    }
-
 }
diff --git a/app/src/main/java/org/rssin/android/SortedArrayAdapter.java b/app/src/main/java/org/rssin/android/SortedArrayAdapter.java
index d4161ba..860752e 100644
--- a/app/src/main/java/org/rssin/android/SortedArrayAdapter.java
+++ b/app/src/main/java/org/rssin/android/SortedArrayAdapter.java
@@ -7,7 +7,9 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- * Created by camilstaps on 25-5-15.
+ * An ArrayAdapter that automatically sorts its elements
+ *
+ * @author Camil Staps
  */
 abstract class SortedArrayAdapter<T extends Comparable<T>> extends ArrayAdapter<T> {
 
diff --git a/app/src/main/java/org/rssin/http/Request.java b/app/src/main/java/org/rssin/http/Request.java
index b9861a5..5aac8dc 100644
--- a/app/src/main/java/org/rssin/http/Request.java
+++ b/app/src/main/java/org/rssin/http/Request.java
@@ -3,7 +3,7 @@ package org.rssin.http;
 import java.net.URL;
 
 /**
- * Created by camilstaps on 21-5-15.
+ * An HTTP request
  */
 public class Request {
 
diff --git a/app/src/main/java/org/rssin/listener/DismissListener.java b/app/src/main/java/org/rssin/listener/DismissListener.java
index cfdc51d..2833782 100644
--- a/app/src/main/java/org/rssin/listener/DismissListener.java
+++ b/app/src/main/java/org/rssin/listener/DismissListener.java
@@ -1,7 +1,7 @@
 package org.rssin.listener;
 
 /**
- * Created by camilstaps on 21-5-15.
+ * A listener that does not care about what it hears
  */
 public class DismissListener implements Listener, RealtimeListener, ErrorListener, FallibleListener {
     @Override
diff --git a/app/src/main/java/org/rssin/listener/ErrorListener.java b/app/src/main/java/org/rssin/listener/ErrorListener.java
index 5ad4f1b..42e2247 100644
--- a/app/src/main/java/org/rssin/listener/ErrorListener.java
+++ b/app/src/main/java/org/rssin/listener/ErrorListener.java
@@ -1,7 +1,7 @@
 package org.rssin.listener;
 
 /**
- * Created by camilstaps on 21-5-15.
+ * Listener for when an error occurs
  */
 public interface ErrorListener<T> {
     void onError(T error);
diff --git a/app/src/main/java/org/rssin/listener/FallibleListener.java b/app/src/main/java/org/rssin/listener/FallibleListener.java
index 4e1d113..76dfc8b 100644
--- a/app/src/main/java/org/rssin/listener/FallibleListener.java
+++ b/app/src/main/java/org/rssin/listener/FallibleListener.java
@@ -1,7 +1,7 @@
 package org.rssin.listener;
 
 /**
- * Created by camilstaps on 21-5-15.
+ * A Fallible Listener is a Listener *and* an ErrorListener!
  */
 public interface FallibleListener<T,E> extends Listener<T>, ErrorListener<E> {
 }
diff --git a/app/src/main/java/org/rssin/listener/Listener.java b/app/src/main/java/org/rssin/listener/Listener.java
index db1764c..a8174bc 100644
--- a/app/src/main/java/org/rssin/listener/Listener.java
+++ b/app/src/main/java/org/rssin/listener/Listener.java
@@ -1,7 +1,7 @@
 package org.rssin.listener;
 
 /**
- * Created by camilstaps on 21-5-15.
+ * A basic generic listener
  */
 public interface Listener<T> {
     void onReceive(T data);
diff --git a/app/src/main/java/org/rssin/listener/RealtimeListener.java b/app/src/main/java/org/rssin/listener/RealtimeListener.java
index 82a4c91..4a2ac3e 100644
--- a/app/src/main/java/org/rssin/listener/RealtimeListener.java
+++ b/app/src/main/java/org/rssin/listener/RealtimeListener.java
@@ -1,7 +1,8 @@
 package org.rssin.listener;
 
 /**
- * Created by camilstaps on 21-5-15.
+ * The RealtimeListener lets you call onReceive() multiple times.
+ * When all data has been sent, call finish().
  */
 public interface RealtimeListener extends Listener {
     void finish();
diff --git a/app/src/main/java/org/rssin/rssin/Feed.java b/app/src/main/java/org/rssin/rssin/Feed.java
index 4690d37..967c9b3 100644
--- a/app/src/main/java/org/rssin/rssin/Feed.java
+++ b/app/src/main/java/org/rssin/rssin/Feed.java
@@ -1,7 +1,5 @@
 package org.rssin.rssin;
 
-import android.util.Log;
-
 import org.rssin.storage.Storable;
 import org.rssin.storage.StorageProvider;
 
@@ -22,6 +20,9 @@ public class Feed implements Storable, Comparable<Feed> {
     private String title;
     private URL url;
 
+    /**
+     * The key with which this feed is stored in storage
+     */
     private Object storageKey;
 
     public Feed(URL url) {
diff --git a/app/src/main/java/org/rssin/rssin/FeedLoaderAndSorter.java b/app/src/main/java/org/rssin/rssin/FeedLoaderAndSorter.java
index 4113436..2ec3cfd 100755
--- a/app/src/main/java/org/rssin/rssin/FeedLoaderAndSorter.java
+++ b/app/src/main/java/org/rssin/rssin/FeedLoaderAndSorter.java
@@ -7,13 +7,13 @@ import org.rssin.listener.RealtimeListener;
 import org.rssin.neurons.FeedSorter;

 import org.rssin.rss.FeedItem;

 import org.rssin.rss.FeedLoader;

-import org.rssin.storage.StorageProvider;

 

 import java.util.ArrayList;

 import java.util.List;

 

 /**

  * Created by Jos on 20-5-2015.

+ * @todo javadoc

  */

 public class FeedLoaderAndSorter {

     private Filter filter;

diff --git a/app/src/main/java/org/rssin/rssin/Filter.java b/app/src/main/java/org/rssin/rssin/Filter.java
index b623b20..ef9fc7a 100755
--- a/app/src/main/java/org/rssin/rssin/Filter.java
+++ b/app/src/main/java/org/rssin/rssin/Filter.java
@@ -25,7 +25,20 @@ public class Filter implements Storable, Comparable<Filter> {
     private final List<Keyword> keywords;
     private String title = "";
 
+    /**
+     * The key with which this filter is stored in storage
+     */
     private Object storageKey;
+
+    /**
+     * The FeedSorter for this filter
+     * Since this object is fairly large, serialisation takes too long to save it with the filter
+     * itself, and serialise the FeedSorter every time we update our filter's settings. Therefore,
+     * We define this attribute to be transient, and require the programmer to call
+     * {@link this#ensureFeedSorter(StorageProvider)} before using this attribute.
+     *
+     * @see this#ensureFeedSorter(StorageProvider)
+     */
     private transient FeedSorter feedSorter;
 
     public Filter() {
@@ -80,6 +93,10 @@ public class Filter implements Storable, Comparable<Filter> {
         this.title = title.trim();
     }
 
+    /**
+     * Be sure to call {@link this#ensureFeedSorter(StorageProvider)} before calling this getter.
+     * @return
+     */
     public FeedSorter getFeedSorter() {
         return feedSorter;
     }
@@ -90,8 +107,9 @@ public class Filter implements Storable, Comparable<Filter> {
 
     /**
      * Ensure that there is a feedSorter linked to this object
-     * Because the feedSorter attribute is transient (if not, serialization for changing settings takes too long),
-     * we need to manually ensure we get the FeedSorter as well every time we need it.
+     * Because the feedSorter attribute is transient (if not, serialisation for changing settings
+     * takes too long), we need to manually ensure we get the FeedSorter as well every time we need
+     * it. It is the programmer's responsibility to call this method.
      * @param storageProvider
      */
     public synchronized void ensureFeedSorter(StorageProvider storageProvider) {
@@ -134,6 +152,8 @@ public class Filter implements Storable, Comparable<Filter> {
 
     /**
      * Save the FeedSorter of this Filter
+     * This is done in a separate thread because it takes too long to do in a main thread. This
+     * also means that you cannot rely on the FeedSorter being saved when this method returns.
      * @param storageProvider
      * @throws Exception
      */
diff --git a/app/src/main/java/org/rssin/storage/FeedStorageProvider.java b/app/src/main/java/org/rssin/storage/FeedStorageProvider.java
index b299911..eac78ce 100644
--- a/app/src/main/java/org/rssin/storage/FeedStorageProvider.java
+++ b/app/src/main/java/org/rssin/storage/FeedStorageProvider.java
@@ -9,7 +9,24 @@ import java.util.List;
  * @author Camil Staps
  */
 public interface FeedStorageProvider<K> {
+
+    /**
+     * Get all feeds in storage
+     * @return
+     */
     List<Feed> allFeeds();
+
+    /**
+     * Get the feed for a specific key
+     * @param key
+     * @return
+     */
     Feed getFeed(K key);
+
+    /**
+     * Remove the key indicated by a key
+     * @param key
+     */
     void removeFeed(K key);
+
 }
diff --git a/app/src/main/java/org/rssin/storage/FilterStorageProvider.java b/app/src/main/java/org/rssin/storage/FilterStorageProvider.java
index 44a5fc0..b1807d9 100644
--- a/app/src/main/java/org/rssin/storage/FilterStorageProvider.java
+++ b/app/src/main/java/org/rssin/storage/FilterStorageProvider.java
@@ -9,7 +9,24 @@ import java.util.List;
  * @author Camil Staps
  */
 public interface FilterStorageProvider<K> {
+
+    /**
+     * Get a list of all filters in storage
+     * @return
+     */
     List<Filter> allFilters();
+
+    /**
+     * Get the filter of a specific key
+     * @param key
+     * @return
+     */
     Filter getFilter(K key);
+
+    /**
+     * Remove the filter of a specific key
+     * @param key
+     */
     void removeFilter(K key);
+
 }