--- a/artifact-database/src/main/java/de/intevation/artifactdatabase/state/FacetActivity.java	Tue Oct 16 15:08:43 2012 +0200
+++ b/artifact-database/src/main/java/de/intevation/artifactdatabase/state/FacetActivity.java	Wed Oct 17 22:16:17 2012 +0200
@@ -7,8 +7,16 @@
 import java.util.List;
 import java.util.Map;
 
+import org.apache.log4j.Logger;
 
-/** Magical system. */
+
+/**
+ * System used in practice used by AttributeWriter in flys-artifacts to decide
+ * whether a facet is initially active.
+ * Provides a singleton Registry into which FacetActivities can be registered
+ * under a key (in practice the artifacts name.  This Registry is queried for
+ * new Facets in order to find whether they are active or inactive.
+ */
 public interface FacetActivity
 {
     /** Static 'activity' that lets all facets be active. */
@@ -41,9 +49,13 @@
      * decide whether or not a facet should be (initially) active. */
     public static final class Registry {
 
+        /** The logger for this class. */
+        private static Logger logger = Logger.getLogger(Registry.class);
+
         /** Singleton instance. */
         private static final Registry INSTANCE = new Registry();
 
+        /** Map of keys (artifact names) to the activities. */
         private Map<String, List<FacetActivity>> activities;
 
         /** Private singleton constructor for the Facet-Activity-Registry. */
@@ -65,11 +77,18 @@
         ) {
             List<FacetActivity> activityList = activities.get(key);
             if (activityList == null) {
+                logger.debug("FacetActivity.Registry: No activity "
+                             "registered for " + key);
                 return true;
             }
+            if (activityList.size() != 1) {
+                logger.warn("FacetActivity.Registry: More than one "
+                            "FacetActivity registered for " + key);
+            }
             for (FacetActivity activity: activityList) {
                 Boolean isActive =
                     activity.isInitialActive(artifact, facet, output);
+                // Nice. Only, in practice they never return NULL.
                 if (isActive != null) {
                     return isActive;
                 }
@@ -77,6 +96,8 @@
             return true;
         }
 
+
+        /** Add a FacetActivity under given key (usually artifacts name). */
         public synchronized void register(String key, FacetActivity activity) {
             List<FacetActivity> activityList = activities.get(key);
             if (activityList == null) {