diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterService.java b/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterService.java
index a44a28a2cc4..d374787991b 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterService.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterService.java
@@ -24,19 +24,40 @@ import org.elasticsearch.common.component.LifecycleComponent;
 import org.elasticsearch.common.unit.TimeValue;
 
 /**
+ * The cluster service allowing to both register for cluster state events ({@link ClusterStateListener})
+ * and submit state update tasks ({@link ClusterStateUpdateTask}.
+ *
  * @author kimchy (shay.banon)
  */
 public interface ClusterService extends LifecycleComponent<ClusterService> {
 
+    /**
+     * The local node.
+     */
     DiscoveryNode localNode();
 
+    /**
+     * The current state.
+     */
     ClusterState state();
 
+    /**
+     * Adds a listener for updated cluster states.
+     */
     void add(ClusterStateListener listener);
 
+    /**
+     * Removes a listener for updated cluster states.
+     */
     void remove(ClusterStateListener listener);
 
+    /**
+     * Adds a cluster state listener that will timeout after the provided timeout.
+     */
     void add(TimeValue timeout, TimeoutClusterStateListener listener);
 
+    /**
+     * Submits a task that will update the cluster state.
+     */
     void submitStateUpdateTask(final String source, final ClusterStateUpdateTask updateTask);
 }
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterStateListener.java b/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterStateListener.java
index c6f5a39e86b..873bd87482d 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterStateListener.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterStateListener.java
@@ -20,9 +20,14 @@
 package org.elasticsearch.cluster;
 
 /**
- * @author kimchy (Shay Banon)
+ * A listener to be notified when a cluster state changes.
+ *
+ * @author kimchy (shay.banon)
  */
 public interface ClusterStateListener {
 
+    /**
+     * Called when cluster state changes.
+     */
     void clusterChanged(ClusterChangedEvent event);
 }
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterStateUpdateTask.java b/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterStateUpdateTask.java
index b70663994c4..3a50220fb87 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterStateUpdateTask.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/cluster/ClusterStateUpdateTask.java
@@ -20,9 +20,15 @@
 package org.elasticsearch.cluster;
 
 /**
- * @author kimchy (Shay Banon)
+ * A task that can update the cluster state.
+ *
+ * @author kimchy (shay.banon)
  */
 public interface ClusterStateUpdateTask {
 
+    /**
+     * Update the cluster state based on the current state. Return the *same instance* if no state
+     * should be changed.
+     */
     ClusterState execute(ClusterState currentState);
 }