diff --git a/zanata-war/src/main/java/org/zanata/webtrans/client/presenter/ComparingPair.java b/zanata-war/src/main/java/org/zanata/webtrans/client/presenter/ComparingPair.java
index a19bbf9d5b..c2efebf9d5 100644
--- a/zanata-war/src/main/java/org/zanata/webtrans/client/presenter/ComparingPair.java
+++ b/zanata-war/src/main/java/org/zanata/webtrans/client/presenter/ComparingPair.java
@@ -24,7 +24,10 @@
 import org.zanata.webtrans.shared.model.TransHistoryItem;
 
 /**
-* @author Patrick Huang <a href="mailto:pahuang@redhat.com">pahuang@redhat.com</a>
+ * This class holds two distinct translation history items at most. They are then used for comparison.
+ * The object created is immutable. See test for more detail.
+ *
+ * @author Patrick Huang <a href="mailto:pahuang@redhat.com">pahuang@redhat.com</a>
 */
 class ComparingPair
 {
@@ -52,6 +55,15 @@ TransHistoryItem two()
       return two;
    }
 
+   /**
+    * Add item to this holder.
+    * If item already exist in this holder, it will be removed.
+    * If current holder is full (already contains two items), new item won't be added in. i.e. no op.
+    * Otherwise it will be added to the holder.
+    *
+    * @param newItem to be added/removed item
+    * @return a new object of this class
+    */
    public ComparingPair addOrRemove(TransHistoryItem newItem)
    {
       if (isEmpty())