--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Add.java	Thu Aug 22 17:24:34 2013 +0200
+++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Add.java	Fri Aug 23 14:29:24 2013 +0200
@@ -37,7 +37,17 @@
 
 package com.redhat.thermostat.storage.core;
 
+/**
+ * Write operation to be used for adding new records into
+ * storage.
+ *
+ * @see Update
+ * @see Replace
+ * @see Remove
+ */
 public interface Add extends Put {
+    
+    
 
 }
 

--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Remove.java	Thu Aug 22 17:24:34 2013 +0200
+++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Remove.java	Fri Aug 23 14:29:24 2013 +0200
@@ -40,10 +40,21 @@
 import com.redhat.thermostat.storage.query.Expression;
 
 /**
- * Describes what data should be removed from storage.
+ * Write operation to be used for removing records from storage.
+ * 
+ * @see Add
+ * @see Update
+ * @see Replace
  */
 public interface Remove {
 
+    /**
+     * Boolean expression in order to restrict the set of records to be removed
+     * from storage.
+     * 
+     * @param where
+     *            The boolean expression.
+     */
     void where(Expression where);
     
     /**

--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Replace.java	Thu Aug 22 17:24:34 2013 +0200
+++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Replace.java	Fri Aug 23 14:29:24 2013 +0200
@@ -40,16 +40,21 @@
 import com.redhat.thermostat.storage.query.Expression;
 
 /**
- * Describes which object should get inserted into storage or which
- * object should get updated with new values in storage.
+ * Write operation which should be used if any existing record should get
+ * updated with new values. It can be thought of as {@link Update} for
+ * <strong>all</strong> properties of a record.
  * 
- * If the where expression matches an object in storage, this
- * object will get updated. Otherwise a new object gets inserted into
- * storage.
- *
+ * The only distinction to a regular {@link Update} is that if Replace is used
+ * and the associated where yields no result, a <strong>new</strong> record will
+ * be insterted into Storage.
+ * 
+ * @see Add
+ * @see Remove
+ * @see Update
  */
 public interface Replace extends Put {
 
     void where(Expression expression);
+
 }
 

--- a/storage/core/src/main/java/com/redhat/thermostat/storage/core/Update.java	Thu Aug 22 17:24:34 2013 +0200
+++ b/storage/core/src/main/java/com/redhat/thermostat/storage/core/Update.java	Fri Aug 23 14:29:24 2013 +0200
@@ -39,7 +39,11 @@
 import com.redhat.thermostat.storage.query.Expression;
 
 /**
- * Updates fields of a database entry. 
+ * Updates properties of a record in storage.
+ * 
+ * @see Add
+ * @see Replace
+ * @see Remove
  */
 public interface Update {
 
@@ -49,22 +53,24 @@
      * found (i.e. the where-clause yields no results), a
      * <code>StorageException</code> may get thrown.
      * 
-     * @param key the key of the field of the where clause
-     * @param value the value of the field of the where clause
+     * @param expr
+     *            A boolean expression.
      */
     void where(Expression expr);
 
     /**
-     * Sets a field in a found document to the specified value. If the same key is
+     * Sets a field in a found record to the specified value. If the same key is
      * set more than once, the latest values overrides the former values.
-     *
-     * @param key the key of the field
-     * @param value the value to set
+     * 
+     * @param key
+     *            the key of the field
+     * @param value
+     *            the value to set
      */
     <T> void set(Key<T> key, T value);
 
     /**
-     * Applies the update operation.
+     * Applies this update operation.
      */
     void apply();
 }