adding comments / documentation to filter related code

diff --git a/source/mircoders/abuse/FilterEngine.java b/source/mircoders/abuse/FilterEngine.java
index e36e95f..1f6cc42 100755 (executable)
--- a/source/mircoders/abuse/FilterEngine.java
+++ b/source/mircoders/abuse/FilterEngine.java
@@ -44,7 +44,10 @@ import mircoders.storage.DatabaseFilterGroup;
 
 import java.text.SimpleDateFormat;
 import java.util.*;
-
+/** The FilterEngine manages a list of all filters and filter groups.
+ *  Use the testPosting() method to apply all filters on an 
+ *  Entity (for ex. an article or a comment)
+ */
 public class FilterEngine {
   private Map filterTypes;
   private List filterTypeIds;
@@ -82,7 +85,9 @@ public class FilterEngine {
     dateFormat.setTimeZone(TimeZone.getTimeZone(configuration.getString("Mir.DefaultTimezone")));
     reload();
   }
-
+  /** applies all filters from all filter groups to an Entity.
+   *  The entity may be, for example, an article, or a comment.  
+   */
   public Filter testPosting(Entity anEntity, Request aRequest) {
     Iterator i = filterGroups.iterator();
     while (i.hasNext()) {
@@ -125,7 +130,11 @@ public class FilterEngine {
       throw new RuntimeException("can't get article actions");
     }
   }
-
+  /** This class reflects a row of the filter_group 
+   * database table. Filters groups allow you to organize 
+   * your filters. For example: group1=spammer ,  
+   * group2=nazis etc.  
+   */
   public class FilterGroup {
     private List filters;
     private Entity entity;
@@ -261,7 +270,11 @@ public class FilterEngine {
       return entity.getFieldValue("name");
     }
   }
-
+  /** This class reflects a row of the filter database table. 
+   * To actually run a filter on data, use the test() method. 
+   * This class will automatically retreive and use the correct 
+   * filter type.
+   */
   public class Filter {
     private Entity entity;
     private FilterInstance instance;

diff --git a/source/mircoders/abuse/FilterInstance.java b/source/mircoders/abuse/FilterInstance.java
index dd20409..a943794 100755 (executable)
--- a/source/mircoders/abuse/FilterInstance.java
+++ b/source/mircoders/abuse/FilterInstance.java
@@ -31,7 +31,12 @@ package mircoders.abuse;
 \r
 import mir.entity.Entity;\r
 import mir.session.Request;\r
-\r
+/**\r
+ * Classes implementing this interface provide the test() method\r
+ * that actually does the filtering work (ie. matching the \r
+ * data). The description of a filter is found in classes \r
+ * implementing FilterType \r
+ */\r
 public interface FilterInstance {\r
   /**\r
    * Must return <code>true</code> if the posting matches the filter.\r

diff --git a/source/mircoders/abuse/FilterType.java b/source/mircoders/abuse/FilterType.java
index acf3726..05d3e1a 100755 (executable)
--- a/source/mircoders/abuse/FilterType.java
+++ b/source/mircoders/abuse/FilterType.java
@@ -32,7 +32,11 @@ package mircoders.abuse;
 
 
 /**
- * Interface to define filter types for the anti-abuse system
+ * Interface to define filter types for the anti-abuse system.
+ * Implementing classes provide a description of the filter.
+ * The actual filtering work is done by classes implementing
+ * the FilterInstance interface. That class is provided by the
+ * constructFilterInstance method
  */
 
 public interface FilterType {

diff --git a/source/mircoders/abuse/RegularExpressionFilterType.java b/source/mircoders/abuse/RegularExpressionFilterType.java
index fe0e6bb..f6b57b6 100755 (executable)
--- a/source/mircoders/abuse/RegularExpressionFilterType.java
+++ b/source/mircoders/abuse/RegularExpressionFilterType.java
@@ -41,7 +41,7 @@ import mir.session.Request;
 
 
 /**
-  * A regular expression filter.
+  * A description of a regular expression filter.
   */
  public class RegularExpressionFilterType extends AbstractFilterType {
     private boolean exactMatch;