diff --git a/.idea/libraries/jgroups.xml b/.idea/libraries/jgroups.xml
index 5ac32951af5..1c00f56f53e 100644
--- a/.idea/libraries/jgroups.xml
+++ b/.idea/libraries/jgroups.xml
@@ -4,6 +4,8 @@
       <root url="jar://$GRADLE_REPOSITORY$/jgroups/jgroups/jars/jgroups-2.9.0.GA.jar!/" />
     </CLASSES>
     <JAVADOC />
-    <SOURCES />
+    <SOURCES>
+      <root url="file://$PROJECT_DIR$/../../../opt/jgroups/2.9.0.GA.src/src" />
+    </SOURCES>
   </library>
 </component>
\ No newline at end of file
diff --git a/.idea/projectCodeStyle.xml b/.idea/projectCodeStyle.xml
index 22399cebbb2..f98da4cdac3 100644
--- a/.idea/projectCodeStyle.xml
+++ b/.idea/projectCodeStyle.xml
@@ -4,7 +4,6 @@
     <option name="PER_PROJECT_SETTINGS">
       <value>
         <option name="LINE_SEPARATOR" value="&#10;" />
-        <option name="USE_FQ_CLASS_NAMES_IN_JAVADOC" value="false" />
         <option name="NAMES_COUNT_TO_USE_IMPORT_ON_DEMAND" value="1" />
         <option name="PACKAGES_TO_USE_IMPORT_ON_DEMAND">
           <value>
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/ElasticSearchException.java b/modules/elasticsearch/src/main/java/org/elasticsearch/ElasticSearchException.java
index 6990f2c5180..b1354621d2b 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/ElasticSearchException.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/ElasticSearchException.java
@@ -20,12 +20,14 @@
 package org.elasticsearch;
 
 /**
- * @author kimchy (Shay Banon) (Shay Banon)
+ * A base class for all elasticsearch exceptions.
+ *
+ * @author kimchy (Shay Banon)
  */
 public class ElasticSearchException extends RuntimeException {
 
     /**
-     * Construct a <code>NestedRuntimeException</code> with the specified detail message.
+     * Construct a <code>ElasticSearchException</code> with the specified detail message.
      *
      * @param msg the detail message
      */
@@ -34,7 +36,7 @@ public class ElasticSearchException extends RuntimeException {
     }
 
     /**
-     * Construct a <code>NestedRuntimeException</code> with the specified detail message
+     * Construct a <code>ElasticSearchException</code> with the specified detail message
      * and nested exception.
      *
      * @param msg   the detail message
@@ -44,6 +46,12 @@ public class ElasticSearchException extends RuntimeException {
         super(msg, cause);
     }
 
+    /**
+     * Unwraps the actual cause from the exception for cases when the exception is a
+     * {@link ElasticSearchWrapperException}.
+     *
+     * @see org.elasticsearch.ExceptionsHelper#unwrapCause(Throwable)
+     */
     public Throwable unwrapCause() {
         return ExceptionsHelper.unwrapCause(this);
     }
@@ -68,9 +76,6 @@ public class ElasticSearchException extends RuntimeException {
 
     /**
      * Retrieve the innermost cause of this exception, if any.
-     *
-     * @return the innermost exception, or <code>null</code> if none
-     * @since 2.0
      */
     public Throwable getRootCause() {
         Throwable rootCause = null;
@@ -89,7 +94,6 @@ public class ElasticSearchException extends RuntimeException {
      * to the present exception if there is no root cause.
      *
      * @return the most specific cause (never <code>null</code>)
-     * @since 2.0.3
      */
     public Throwable getMostSpecificCause() {
         Throwable rootCause = getRootCause();
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/action/index/IndexRequest.java b/modules/elasticsearch/src/main/java/org/elasticsearch/action/index/IndexRequest.java
index d6421f946d0..51d80901168 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/action/index/IndexRequest.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/action/index/IndexRequest.java
@@ -24,6 +24,7 @@ import org.elasticsearch.action.ActionRequestValidationException;
 import org.elasticsearch.action.support.replication.ShardReplicationOperationRequest;
 import org.elasticsearch.util.Required;
 import org.elasticsearch.util.TimeValue;
+import org.elasticsearch.util.json.JsonBuilder;
 
 import java.io.DataInput;
 import java.io.DataOutput;
@@ -122,7 +123,7 @@ public class IndexRequest extends ShardReplicationOperationRequest {
         return id;
     }
 
-    @Required public IndexRequest id(String id) {
+    public IndexRequest id(String id) {
         this.id = id;
         return this;
     }
@@ -131,7 +132,15 @@ public class IndexRequest extends ShardReplicationOperationRequest {
         return source;
     }
 
-    public IndexRequest source(String source) {
+    @Required public IndexRequest source(JsonBuilder jsonBuilder) {
+        try {
+            return source(jsonBuilder.string());
+        } catch (IOException e) {
+            throw new ElasticSearchIllegalArgumentException("Failed to build json for index request", e);
+        }
+    }
+
+    @Required public IndexRequest source(String source) {
         this.source = source;
         return this;
     }
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/client/AdminClient.java b/modules/elasticsearch/src/main/java/org/elasticsearch/client/AdminClient.java
index d4283918e2c..91712ce4b3a 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/client/AdminClient.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/client/AdminClient.java
@@ -20,11 +20,20 @@
 package org.elasticsearch.client;
 
 /**
+ * Administrative actions/operations against the cluster or the indices.
+ *
  * @author kimchy (Shay Banon)
+ * @see org.elasticsearch.client.Client#admin()
  */
 public interface AdminClient {
 
+    /**
+     * A client allowing to perform actions/operations against the cluster.
+     */
     ClusterAdminClient cluster();
 
+    /**
+     * A client allowing to perform actions/operations against the indices.
+     */
     IndicesAdminClient indices();
 }
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/client/Client.java b/modules/elasticsearch/src/main/java/org/elasticsearch/client/Client.java
index 8cf42b67bef..d169bc69961 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/client/Client.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/client/Client.java
@@ -36,53 +36,231 @@ import org.elasticsearch.action.search.SearchResponse;
 import org.elasticsearch.action.search.SearchScrollRequest;
 
 /**
+ * A client provides a one stop interface for performing actions/operations against the cluster.
+ *
+ * <p>All operations performed are asynchronous by nature. There are three flavors for each operation,
+ * the simplest returns an {@link ActionFuture}, another that also accepts an {@link ActionListener},
+ * and the last (prefixed with <tt>exec</tt>) which just accepts an {@link ActionListener} without returning
+ * an {@link ActionFuture}.
+ *
+ * <p>A client can either be retrieved from a {@link org.elasticsearch.server.Server} started, or connected remotely
+ * to one or more nodes using {@link org.elasticsearch.client.transport.TransportClient}.
+ *
  * @author kimchy (Shay Banon)
+ * @see org.elasticsearch.server.Server#client()
+ * @see org.elasticsearch.client.transport.TransportClient
  */
 public interface Client {
 
+    /**
+     * Closes the client.
+     */
     void close();
 
+    /**
+     * The admin client that can be used to perform administrative operations.
+     */
     AdminClient admin();
 
+    /**
+     * Index a JSON source associated with a given index and type.
+     *
+     * <p>The id is optional, if it is not provided, one will be generated automatically.
+     *
+     * @param request The index request
+     * @return The result future
+     * @see Requests#indexRequest(String)
+     */
     ActionFuture<IndexResponse> index(IndexRequest request);
 
+    /**
+     * Index a JSON source associated with a given index and type.
+     *
+     * <p>The id is optional, if it is not provided, one will be generated automatically.
+     *
+     * @param request  The index request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see Requests#indexRequest(String)
+     */
     ActionFuture<IndexResponse> index(IndexRequest request, ActionListener<IndexResponse> listener);
 
+    /**
+     * Index a JSON source associated with a given index and type.
+     *
+     * <p>The id is optional, if it is not provided, one will be generated automatically.
+     *
+     * @param request  The index request
+     * @param listener A listener to be notified with a result
+     * @see Requests#indexRequest(String)
+     */
     void execIndex(IndexRequest request, ActionListener<IndexResponse> listener);
 
+    /**
+     * Deletes a document from the index based on the index, type and id.
+     *
+     * @param request The delete request
+     * @return The result future
+     * @see Requests#deleteRequest(String)
+     */
     ActionFuture<DeleteResponse> delete(DeleteRequest request);
 
+    /**
+     * Deletes a document from the index based on the index, type and id.
+     *
+     * @param request  The delete request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see Requests#deleteRequest(String)
+     */
     ActionFuture<DeleteResponse> delete(DeleteRequest request, ActionListener<DeleteResponse> listener);
 
+    /**
+     * Deletes a document from the index based on the index, type and id.
+     *
+     * @param request  The delete request
+     * @param listener A listener to be notified with a result
+     * @see Requests#deleteRequest(String)
+     */
     void execDelete(DeleteRequest request, ActionListener<DeleteResponse> listener);
 
+    /**
+     * Deletes all documents from one or more indices based on a query.
+     *
+     * @param request The delete by query request
+     * @return The result future
+     * @see Requests#deleteByQueryRequest(String...)
+     */
     ActionFuture<DeleteByQueryResponse> deleteByQuery(DeleteByQueryRequest request);
 
+    /**
+     * Deletes all documents from one or more indices based on a query.
+     *
+     * @param request  The delete by query request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see Requests#deleteByQueryRequest(String...)
+     */
     ActionFuture<DeleteByQueryResponse> deleteByQuery(DeleteByQueryRequest request, ActionListener<DeleteByQueryResponse> listener);
 
+    /**
+     * Deletes all documents from one or more indices based on a query.
+     *
+     * @param request  The delete by query request
+     * @param listener A listener to be notified with a result
+     * @see Requests#deleteByQueryRequest(String...)
+     */
     void execDeleteByQuery(DeleteByQueryRequest request, ActionListener<DeleteByQueryResponse> listener);
 
+    /**
+     * Gets the JSON source that was indexed from an index with a type and id.
+     *
+     * @param request The get request
+     * @return The result future
+     * @see Requests#getRequest(String)
+     */
     ActionFuture<GetResponse> get(GetRequest request);
 
+    /**
+     * Gets the JSON source that was indexed from an index with a type and id.
+     *
+     * @param request  The get request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see Requests#getRequest(String)
+     */
     ActionFuture<GetResponse> get(GetRequest request, ActionListener<GetResponse> listener);
 
+    /**
+     * Gets the JSON source that was indexed from an index with a type and id.
+     *
+     * @param request  The get request
+     * @param listener A listener to be notified with a result
+     * @see Requests#getRequest(String)
+     */
     void execGet(GetRequest request, ActionListener<GetResponse> listener);
 
+    /**
+     * A count of all the documents matching a specific query.
+     *
+     * @param request The count request
+     * @return The result future
+     * @see Requests#countRequest(String...)
+     */
     ActionFuture<CountResponse> count(CountRequest request);
 
+    /**
+     * A count of all the documents matching a specific query.
+     *
+     * @param request  The count request
+     * @param listener A listener to be notified of the result
+     * @return The result future
+     * @see Requests#countRequest(String...)
+     */
     ActionFuture<CountResponse> count(CountRequest request, ActionListener<CountResponse> listener);
 
+    /**
+     * A count of all the documents matching a specific query.
+     *
+     * @param request  The count request
+     * @param listener A listener to be notified of the result
+     * @see Requests#countRequest(String...)
+     */
     void execCount(CountRequest request, ActionListener<CountResponse> listener);
 
+    /**
+     * Search across one or more indices and one or more types with a query.
+     *
+     * @param request The search request
+     * @return The result future
+     * @see Requests#searchRequest(String...)
+     */
     ActionFuture<SearchResponse> search(SearchRequest request);
 
+    /**
+     * Search across one or more indices and one or more types with a query.
+     *
+     * @param request  The search request
+     * @param listener A listener to be notified of the result
+     * @return The result future
+     * @see Requests#searchRequest(String...)
+     */
     ActionFuture<SearchResponse> search(SearchRequest request, ActionListener<SearchResponse> listener);
 
+    /**
+     * Search across one or more indices and one or more types with a query.
+     *
+     * @param request  The search request
+     * @param listener A listener to be notified of the result
+     * @see Requests#searchRequest(String...)
+     */
     void execSearch(SearchRequest request, ActionListener<SearchResponse> listener);
 
+    /**
+     * A search scroll request to continue searching a previous scrollable search request.
+     *
+     * @param request The search scroll request
+     * @return The result future
+     * @see Requests#searchScrollRequest(String)
+     */
     ActionFuture<SearchResponse> searchScroll(SearchScrollRequest request);
 
+    /**
+     * A search scroll request to continue searching a previous scrollable search request.
+     *
+     * @param request  The search scroll request
+     * @param listener A listener to be notified of the result
+     * @return The result future
+     * @see Requests#searchScrollRequest(String)
+     */
     ActionFuture<SearchResponse> searchScroll(SearchScrollRequest request, ActionListener<SearchResponse> listener);
 
+    /**
+     * A search scroll request to continue searching a previous scrollable search request.
+     *
+     * @param request  The search scroll request
+     * @param listener A listener to be notified of the result
+     * @see Requests#searchScrollRequest(String)
+     */
     void execSearchScroll(SearchScrollRequest request, ActionListener<SearchResponse> listener);
 }
\ No newline at end of file
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/client/ClusterAdminClient.java b/modules/elasticsearch/src/main/java/org/elasticsearch/client/ClusterAdminClient.java
index f0949fe4531..601fcca5700 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/client/ClusterAdminClient.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/client/ClusterAdminClient.java
@@ -33,16 +33,69 @@ import org.elasticsearch.action.admin.cluster.state.ClusterStateRequest;
 import org.elasticsearch.action.admin.cluster.state.ClusterStateResponse;
 
 /**
+ * Administrative actions/operations against indices.
+ *
  * @author kimchy (Shay Banon)
+ * @see AdminClient#cluster()
  */
 public interface ClusterAdminClient {
 
+    /**
+     * The state of the cluster.
+     *
+     * @param request The cluster state request.
+     * @return The result future
+     * @see Requests#clusterState()
+     */
     ActionFuture<ClusterStateResponse> state(ClusterStateRequest request);
 
+    /**
+     * The state of the cluster.
+     *
+     * @param request  The cluster state request.
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see Requests#clusterState()
+     */
     ActionFuture<ClusterStateResponse> state(ClusterStateRequest request, ActionListener<ClusterStateResponse> listener);
 
+    /**
+     * The state of the cluster.
+     *
+     * @param request  The cluster state request.
+     * @param listener A listener to be notified with a result
+     * @see Requests#clusterState()
+     */
     void execState(ClusterStateRequest request, ActionListener<ClusterStateResponse> listener);
 
+    /**
+     * Nodes info of the cluster.
+     *
+     * @param request The nodes info request
+     * @return The result future
+     * @see org.elasticsearch.client.Requests#nodesInfo(String...)
+     */
+    ActionFuture<NodesInfoResponse> nodesInfo(NodesInfoRequest request);
+
+    /**
+     * Nodes info of the cluster.
+     *
+     * @param request  The nodes info request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see org.elasticsearch.client.Requests#nodesInfo(String...)
+     */
+    ActionFuture<NodesInfoResponse> nodesInfo(NodesInfoRequest request, ActionListener<NodesInfoResponse> listener);
+
+    /**
+     * Nodes info of the cluster.
+     *
+     * @param request  The nodes info request
+     * @param listener A listener to be notified with a result
+     * @see org.elasticsearch.client.Requests#nodesInfo(String...)
+     */
+    void execNodesInfo(NodesInfoRequest request, ActionListener<NodesInfoResponse> listener);
+
     ActionFuture<SinglePingResponse> ping(SinglePingRequest request);
 
     ActionFuture<SinglePingResponse> ping(SinglePingRequest request, ActionListener<SinglePingResponse> listener);
@@ -60,10 +113,4 @@ public interface ClusterAdminClient {
     ActionFuture<ReplicationPingResponse> ping(ReplicationPingRequest request, ActionListener<ReplicationPingResponse> listener);
 
     void execPing(ReplicationPingRequest request, ActionListener<ReplicationPingResponse> listener);
-
-    ActionFuture<NodesInfoResponse> nodesInfo(NodesInfoRequest request);
-
-    ActionFuture<NodesInfoResponse> nodesInfo(NodesInfoRequest request, ActionListener<NodesInfoResponse> listener);
-
-    void execNodesInfo(NodesInfoRequest request, ActionListener<NodesInfoResponse> listener);
 }
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/client/IndicesAdminClient.java b/modules/elasticsearch/src/main/java/org/elasticsearch/client/IndicesAdminClient.java
index 39da5cfc479..d3da1bf85e7 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/client/IndicesAdminClient.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/client/IndicesAdminClient.java
@@ -37,49 +37,206 @@ import org.elasticsearch.action.admin.indices.status.IndicesStatusRequest;
 import org.elasticsearch.action.admin.indices.status.IndicesStatusResponse;
 
 /**
+ * Administrative actions/operations against indices.
+ *
  * @author kimchy (Shay Banon)
+ * @see AdminClient#indices()
  */
 public interface IndicesAdminClient {
 
+    /**
+     * The status of one or more indices.
+     *
+     * @param request The indices status request
+     * @return The result future
+     * @see Requests#indicesStatus(String...)
+     */
     ActionFuture<IndicesStatusResponse> status(IndicesStatusRequest request);
 
+    /**
+     * The status of one or more indices.
+     *
+     * @param request  The indices status request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see Requests#indicesStatus(String...)
+     */
     ActionFuture<IndicesStatusResponse> status(IndicesStatusRequest request, ActionListener<IndicesStatusResponse> listener);
 
+    /**
+     * The status of one or more indices.
+     *
+     * @param request  The indices status request
+     * @param listener A listener to be notified with a result
+     * @see Requests#indicesStatus(String...)
+     */
     void execStatus(IndicesStatusRequest request, ActionListener<IndicesStatusResponse> listener);
 
+    /**
+     * Creates an index using an explicit request allowing to specify the settings of the index.
+     *
+     * @param request The create index request
+     * @return The result future
+     * @see org.elasticsearch.client.Requests#createIndexRequest(String)
+     */
     ActionFuture<CreateIndexResponse> create(CreateIndexRequest request);
 
+    /**
+     * Creates an index using an explicit request allowing to specify the settings of the index.
+     *
+     * @param request  The create index request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see org.elasticsearch.client.Requests#createIndexRequest(String)
+     */
     ActionFuture<CreateIndexResponse> create(CreateIndexRequest request, ActionListener<CreateIndexResponse> listener);
 
+    /**
+     * Creates an index using an explicit request allowing to specify the settings of the index.
+     *
+     * @param request  The create index request
+     * @param listener A listener to be notified with a result
+     * @see org.elasticsearch.client.Requests#createIndexRequest(String)
+     */
     void execCreate(CreateIndexRequest request, ActionListener<CreateIndexResponse> listener);
 
+    /**
+     * Deletes an index based on the index name.
+     *
+     * @param request The delete index request
+     * @return The result future
+     * @see org.elasticsearch.client.Requests#deleteIndexRequest(String)
+     */
     ActionFuture<DeleteIndexResponse> delete(DeleteIndexRequest request);
 
+    /**
+     * Deletes an index based on the index name.
+     *
+     * @param request  The delete index request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see org.elasticsearch.client.Requests#deleteIndexRequest(String)
+     */
     ActionFuture<DeleteIndexResponse> delete(DeleteIndexRequest request, ActionListener<DeleteIndexResponse> listener);
 
+    /**
+     * Deletes an index based on the index name.
+     *
+     * @param request  The delete index request
+     * @param listener A listener to be notified with a result
+     * @see org.elasticsearch.client.Requests#deleteIndexRequest(String)
+     */
     void execDelete(DeleteIndexRequest request, ActionListener<DeleteIndexResponse> listener);
 
+    /**
+     * Explicitly refresh one or more indices (making the content indexed since the last refresh searchable).
+     *
+     * @param request The refresh request
+     * @return The result future
+     * @see org.elasticsearch.client.Requests#refreshRequest(String...)
+     */
     ActionFuture<RefreshResponse> refresh(RefreshRequest request);
 
+    /**
+     * Explicitly refresh one or more indices (making the content indexed since the last refresh searchable).
+     *
+     * @param request  The refresh request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see org.elasticsearch.client.Requests#refreshRequest(String...)
+     */
     ActionFuture<RefreshResponse> refresh(RefreshRequest request, ActionListener<RefreshResponse> listener);
 
+    /**
+     * Explicitly refresh one or more indices (making the content indexed since the last refresh searchable).
+     *
+     * @param request  The refresh request
+     * @param listener A listener to be notified with a result
+     * @see org.elasticsearch.client.Requests#refreshRequest(String...)
+     */
     void execRefresh(RefreshRequest request, ActionListener<RefreshResponse> listener);
 
+    /**
+     * Explicitly flush one or more indices (releasing memory from the node).
+     *
+     * @param request The flush request
+     * @return A result future
+     * @see org.elasticsearch.client.Requests#flushRequest(String...)
+     */
     ActionFuture<FlushResponse> flush(FlushRequest request);
 
+    /**
+     * Explicitly flush one or more indices (releasing memory from the node).
+     *
+     * @param request  The flush request
+     * @param listener A listener to be notified with a result
+     * @return A result future
+     * @see org.elasticsearch.client.Requests#flushRequest(String...)
+     */
     ActionFuture<FlushResponse> flush(FlushRequest request, ActionListener<FlushResponse> listener);
 
+    /**
+     * Explicitly flush one or more indices (releasing memory from the node).
+     *
+     * @param request  The flush request
+     * @param listener A listener to be notified with a result
+     * @see org.elasticsearch.client.Requests#flushRequest(String...)
+     */
     void execFlush(FlushRequest request, ActionListener<FlushResponse> listener);
 
+    /**
+     * Add mapping definition for a type into one or more indices.
+     *
+     * @param request The create mapping request
+     * @return A result future
+     * @see org.elasticsearch.client.Requests#createMappingRequest(String...)
+     */
     ActionFuture<CreateMappingResponse> createMapping(CreateMappingRequest request);
 
+    /**
+     * Add mapping definition for a type into one or more indices.
+     *
+     * @param request  The create mapping request
+     * @param listener A listener to be notified with a result
+     * @return A result future
+     * @see org.elasticsearch.client.Requests#createMappingRequest(String...)
+     */
     ActionFuture<CreateMappingResponse> createMapping(CreateMappingRequest request, ActionListener<CreateMappingResponse> listener);
 
+    /**
+     * Add mapping definition for a type into one or more indices.
+     *
+     * @param request  The create mapping request
+     * @param listener A listener to be notified with a result
+     * @see org.elasticsearch.client.Requests#createMappingRequest(String...)
+     */
     void execCreateMapping(CreateMappingRequest request, ActionListener<CreateMappingResponse> listener);
 
+    /**
+     * Explicitly perform gateway snapshot for one or more indices.
+     *
+     * @param request The gateway snapshot request
+     * @return The result future
+     * @see org.elasticsearch.client.Requests#gatewaySnapshotRequest(String...)
+     */
     ActionFuture<GatewaySnapshotResponse> gatewaySnapshot(GatewaySnapshotRequest request);
 
+    /**
+     * Explicitly perform gateway snapshot for one or more indices.
+     *
+     * @param request  The gateway snapshot request
+     * @param listener A listener to be notified with a result
+     * @return The result future
+     * @see org.elasticsearch.client.Requests#gatewaySnapshotRequest(String...)
+     */
     ActionFuture<GatewaySnapshotResponse> gatewaySnapshot(GatewaySnapshotRequest request, ActionListener<GatewaySnapshotResponse> listener);
 
+    /**
+     * Explicitly perform gateway snapshot for one or more indices.
+     *
+     * @param request  The gateway snapshot request
+     * @param listener A listener to be notified with a result
+     * @see org.elasticsearch.client.Requests#gatewaySnapshotRequest(String...)
+     */
     void execGatewaySnapshot(GatewaySnapshotRequest request, ActionListener<GatewaySnapshotResponse> listener);
 }
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/client/Requests.java b/modules/elasticsearch/src/main/java/org/elasticsearch/client/Requests.java
index a0200838c88..d70007d6772 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/client/Requests.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/client/Requests.java
@@ -40,66 +40,203 @@ import org.elasticsearch.action.search.SearchRequest;
 import org.elasticsearch.action.search.SearchScrollRequest;
 
 /**
+ * A handy one stop shop for creating requests (make sure to import static this class).
+ *
  * @author kimchy (Shay Banon)
  */
 public class Requests {
 
+    /**
+     * Create an index request against a specific index. Note the {@link IndexRequest#type(String)} must be
+     * set as well and optionally the {@link IndexRequest#id(String)}.
+     *
+     * @param index The index name to index the request against
+     * @return The index request
+     * @see org.elasticsearch.client.Client#index(org.elasticsearch.action.index.IndexRequest)
+     */
     public static IndexRequest indexRequest(String index) {
         return new IndexRequest(index);
     }
 
+    /**
+     * Creates a delete request against a specific index. Note the {@link DeleteRequest#type(String)} and
+     * {@link DeleteRequest#id(String)} must be set.
+     *
+     * @param index The index name to delete from
+     * @return The delete request
+     * @see org.elasticsearch.client.Client#delete(org.elasticsearch.action.delete.DeleteRequest)
+     */
     public static DeleteRequest deleteRequest(String index) {
         return new DeleteRequest(index);
     }
 
+    /**
+     * Creates a delete by query request. Note, the query itself must be set either by setting the JSON source
+     * of the query, or by using a {@link org.elasticsearch.index.query.QueryBuilder} (using {@link org.elasticsearch.index.query.json.JsonQueryBuilders}).
+     *
+     * @param indices The indices the delete by query against. Use <tt>null</tt> or <tt>_all</tt> to execute against all indices
+     * @return The delete by query request
+     * @see org.elasticsearch.client.Client#deleteByQuery(org.elasticsearch.action.deletebyquery.DeleteByQueryRequest)
+     */
     public static DeleteByQueryRequest deleteByQueryRequest(String... indices) {
         return new DeleteByQueryRequest(indices);
     }
 
+    /**
+     * Creates a get request to get the JSON source from an index based on a type and id. Note, the
+     * {@link GetRequest#type(String)} and {@link GetRequest#id(String)} must be set.
+     *
+     * @param index The index to get the JSON source from
+     * @return The get request
+     * @see org.elasticsearch.client.Client#get(org.elasticsearch.action.get.GetRequest)
+     */
     public static GetRequest getRequest(String index) {
         return new GetRequest(index);
     }
 
+    /**
+     * Creates a count request which counts the hits matched against a query. Note, the query itself must be set
+     * either using the JSON source of the query, or using a {@link org.elasticsearch.index.query.QueryBuilder} (using {@link org.elasticsearch.index.query.json.JsonQueryBuilders}).
+     *
+     * @param indices The indices the delete by query against. Use <tt>null</tt> or <tt>_all</tt> to execute against all indices
+     * @return The count request
+     * @see org.elasticsearch.client.Client#count(org.elasticsearch.action.count.CountRequest)
+     */
     public static CountRequest countRequest(String... indices) {
         return new CountRequest(indices);
     }
 
-    public static SearchRequest searchRequest(String... index) {
-        return new SearchRequest(index);
+    /**
+     * Creates a search request against one or more indices. Note, the search source must be set either using the
+     * actual JSON search source, or the {@link org.elasticsearch.search.builder.SearchSourceBuilder}.
+     *
+     * @param indices The indices the delete by query against. Use <tt>null</tt> or <tt>_all</tt> to execute against all indices
+     * @return The search request
+     * @see org.elasticsearch.client.Client#search(org.elasticsearch.action.search.SearchRequest)
+     */
+    public static SearchRequest searchRequest(String... indices) {
+        return new SearchRequest(indices);
     }
 
+    /**
+     * Creates a search scroll request allowing to continue searching a previous search request.
+     *
+     * @param scrollId The scroll id representing the scrollable search
+     * @return The search scroll request
+     * @see org.elasticsearch.client.Client#searchScroll(org.elasticsearch.action.search.SearchScrollRequest)
+     */
     public static SearchScrollRequest searchScrollRequest(String scrollId) {
         return new SearchScrollRequest(scrollId);
     }
 
+    /**
+     * Creates an indices status request.
+     *
+     * @param indices The indices the delete by query against. Use <tt>null</tt> or <tt>_all</tt> to execute against all indices
+     * @return The indices status request
+     * @see org.elasticsearch.client.IndicesAdminClient#status(org.elasticsearch.action.admin.indices.status.IndicesStatusRequest)
+     */
     public static IndicesStatusRequest indicesStatus(String... indices) {
         return new IndicesStatusRequest(indices);
     }
 
+    /**
+     * Creates a create index request.
+     *
+     * @param index The index to create
+     * @return The index create request
+     * @see org.elasticsearch.client.IndicesAdminClient#create(org.elasticsearch.action.admin.indices.create.CreateIndexRequest)
+     */
     public static CreateIndexRequest createIndexRequest(String index) {
         return new CreateIndexRequest(index);
     }
 
+    /**
+     * Creates a delete index request.
+     *
+     * @param index The index to delete
+     * @return The delete index request
+     * @see org.elasticsearch.client.IndicesAdminClient#delete(org.elasticsearch.action.admin.indices.delete.DeleteIndexRequest)
+     */
     public static DeleteIndexRequest deleteIndexRequest(String index) {
         return new DeleteIndexRequest(index);
     }
 
+    /**
+     * Create a create mapping request against one or more indices.
+     *
+     * @param indices The indices the delete by query against. Use <tt>null</tt> or <tt>_all</tt> to execute against all indices
+     * @return The create mapping request
+     * @see org.elasticsearch.client.IndicesAdminClient#createMapping(org.elasticsearch.action.admin.indices.mapping.create.CreateMappingRequest)
+     */
     public static CreateMappingRequest createMappingRequest(String... indices) {
         return new CreateMappingRequest(indices);
     }
 
+    /**
+     * Creates a refresh indices request.
+     *
+     * @param indices The indices the delete by query against. Use <tt>null</tt> or <tt>_all</tt> to execute against all indices
+     * @return The refresh request
+     * @see org.elasticsearch.client.IndicesAdminClient#refresh(org.elasticsearch.action.admin.indices.refresh.RefreshRequest)
+     */
     public static RefreshRequest refreshRequest(String... indices) {
         return new RefreshRequest(indices);
     }
 
+    /**
+     * Creates a flush indices request.
+     *
+     * @param indices The indices the delete by query against. Use <tt>null</tt> or <tt>_all</tt> to execute against all indices
+     * @return The flush request
+     * @see org.elasticsearch.client.IndicesAdminClient#flush(org.elasticsearch.action.admin.indices.flush.FlushRequest)
+     */
     public static FlushRequest flushRequest(String... indices) {
         return new FlushRequest(indices);
     }
 
+    /**
+     * Creates a gateway snapshot indices request.
+     *
+     * @param indices The indices the delete by query against. Use <tt>null</tt> or <tt>_all</tt> to execute against all indices
+     * @return The gateway snapshot request
+     * @see org.elasticsearch.client.IndicesAdminClient#gatewaySnapshot(org.elasticsearch.action.admin.indices.gateway.snapshot.GatewaySnapshotRequest)
+     */
     public static GatewaySnapshotRequest gatewaySnapshotRequest(String... indices) {
         return new GatewaySnapshotRequest(indices);
     }
 
+    /**
+     * Creates a cluster state request.
+     *
+     * @return The cluster state request.
+     * @see org.elasticsearch.client.ClusterAdminClient#state(org.elasticsearch.action.admin.cluster.state.ClusterStateRequest)
+     */
+    public static ClusterStateRequest clusterState() {
+        return new ClusterStateRequest();
+    }
+
+    /**
+     * Creates a nodes info request against all the nodes.
+     *
+     * @return The nodes info request
+     * @see org.elasticsearch.client.ClusterAdminClient#nodesInfo(org.elasticsearch.action.admin.cluster.node.info.NodesInfoRequest)
+     */
+    public static NodesInfoRequest nodesInfo() {
+        return new NodesInfoRequest();
+    }
+
+    /**
+     * Creates a nodes info request against one or more nodes. Pass <tt>null</tt> or an empty array for all nodes.
+     *
+     * @param nodesIds The nodes ids to get the status for
+     * @return The nodes info request
+     * @see org.elasticsearch.client.ClusterAdminClient#nodesInfo(org.elasticsearch.action.admin.cluster.node.info.NodesInfoRequest)
+     */
+    public static NodesInfoRequest nodesInfo(String... nodesIds) {
+        return new NodesInfoRequest(nodesIds);
+    }
+
     public static SinglePingRequest pingSingleRequest(String index) {
         return new SinglePingRequest(index);
     }
@@ -111,16 +248,4 @@ public class Requests {
     public static ReplicationPingRequest pingReplicationRequest(String... indices) {
         return new ReplicationPingRequest(indices);
     }
-
-    public static NodesInfoRequest nodesInfo() {
-        return new NodesInfoRequest();
-    }
-
-    public static NodesInfoRequest nodesInfo(String... nodesIds) {
-        return new NodesInfoRequest(nodesIds);
-    }
-
-    public static ClusterStateRequest clusterState() {
-        return new ClusterStateRequest();
-    }
 }
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/client/package-info.java b/modules/elasticsearch/src/main/java/org/elasticsearch/client/package-info.java
new file mode 100644
index 00000000000..eb1a0ebd326
--- /dev/null
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/client/package-info.java
@@ -0,0 +1,23 @@
+/*
+ * Licensed to Elastic Search and Shay Banon under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. Elastic Search licenses this
+ * file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * The client module allowing to easily perform actions/operations.
+ */
+package org.elasticsearch.client;
\ No newline at end of file
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/client/transport/NoNodeAvailableException.java b/modules/elasticsearch/src/main/java/org/elasticsearch/client/transport/NoNodeAvailableException.java
index 2ddfe4b1f9a..7c1a2b26cf7 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/client/transport/NoNodeAvailableException.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/client/transport/NoNodeAvailableException.java
@@ -22,6 +22,8 @@ package org.elasticsearch.client.transport;
 import org.elasticsearch.ElasticSearchException;
 
 /**
+ * An exception indicating no node is available to perform the operation.
+ *
  * @author kimchy (Shay Banon)
  */
 public class NoNodeAvailableException extends ElasticSearchException {
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/client/transport/TransportClient.java b/modules/elasticsearch/src/main/java/org/elasticsearch/client/transport/TransportClient.java
index 1fddf91cb57..7476bbee8bd 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/client/transport/TransportClient.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/client/transport/TransportClient.java
@@ -62,6 +62,12 @@ import java.util.ArrayList;
 import static org.elasticsearch.util.settings.ImmutableSettings.*;
 
 /**
+ * The transport client allows to create a client that is not part of the cluster, but simply connects to one
+ * or more nodes directly by adding their respective addresses using {@link #addTransportAddress(org.elasticsearch.util.transport.TransportAddress)}.
+ *
+ * <p>The transport client important modules used is the {@link org.elasticsearch.transport.TransportModule} which is
+ * started in client mode (only connects, no bind).
+ *
  * @author kimchy (Shay Banon)
  */
 public class TransportClient implements Client {
@@ -78,14 +84,31 @@ public class TransportClient implements Client {
     private final InternalTransportClient internalClient;
 
 
+    /**
+     * Constructs a new transport client with settings loaded either from the classpath or the file system (the
+     * <tt>elasticsearch.(yml|json)</tt> files optionally prefixed with <tt>config/</tt>).
+     */
     public TransportClient() throws ElasticSearchException {
         this(ImmutableSettings.Builder.EMPTY_SETTINGS, true);
     }
 
+    /**
+     * Constructs a new transport client with explicit settings and settings loaded either from the classpath or the file
+     * system (the <tt>elasticsearch.(yml|json)</tt> files optionally prefixed with <tt>config/</tt>).
+     */
     public TransportClient(Settings settings) {
         this(settings, true);
     }
 
+    /**
+     * Constructs a new transport client with the provided settings and the ability to control if settings will
+     * be loaded from the classpath / file system (the <tt>elasticsearch.(yml|json)</tt> files optionally prefixed with
+     * <tt>config/</tt>).
+     *
+     * @param pSettings          The explicit settings.
+     * @param loadConfigSettings <tt>true</tt> if settings should be loaded from the classpath/file system.
+     * @throws ElasticSearchException
+     */
     public TransportClient(Settings pSettings, boolean loadConfigSettings) throws ElasticSearchException {
         Tuple<Settings, Environment> tuple = InternalSettingsPerparer.prepareSettings(pSettings, loadConfigSettings);
         this.settings = settingsBuilder().putAll(tuple.v1())
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/server/Server.java b/modules/elasticsearch/src/main/java/org/elasticsearch/server/Server.java
index cedaab6bf64..985bda28472 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/server/Server.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/server/Server.java
@@ -23,17 +23,38 @@ import org.elasticsearch.client.Client;
 import org.elasticsearch.util.settings.Settings;
 
 /**
+ * A server represent a node within a cluster (<tt>cluster.name</tt>). The {@link #client()} can be used
+ * in order to use a {@link Client} to perform actions/operations against the cluster.
+ *
+ * <p>In order to create a server, the {@link ServerBuilder} can be used. When done with it, make sure to
+ * call {@link #close()} on it.
+ *
  * @author kimchy (Shay Banon)
  */
 public interface Server {
 
+    /**
+     * The settings that were used to create the server.
+     */
     Settings settings();
 
+    /**
+     * A client that can be used to execute actions (operations) against the cluster.
+     */
     Client client();
 
+    /**
+     * Start the server. If the server is already started, this method is noop.
+     */
     Server start();
 
+    /**
+     * Stops the server. If the server is already started, this method is noop.
+     */
     Server stop();
 
+    /**
+     * Closes the server (and {@link #stop}s if its running).
+     */
     void close();
 }
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/server/ServerBuilder.java b/modules/elasticsearch/src/main/java/org/elasticsearch/server/ServerBuilder.java
index 2adfee6f2b3..186276a9feb 100644
--- a/modules/elasticsearch/src/main/java/org/elasticsearch/server/ServerBuilder.java
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/server/ServerBuilder.java
@@ -24,6 +24,35 @@ import org.elasticsearch.util.settings.ImmutableSettings;
 import org.elasticsearch.util.settings.Settings;
 
 /**
+ * A server builder is used to construct a {@link Server} instance.
+ *
+ * <p>Settings will be loaded relative to the ES home (with or without <tt>config/</tt> prefix) and if not found,
+ * within the classpath (with or without <tt>config/<tt> prefix). The settings file loaded can either be named
+ * <tt>elasticsearch.yml</tt> or <tt>elasticsearch.json</tt>). Loading settings can be disabled by calling
+ * {@link #loadConfigSettings(boolean)} with <tt>false<tt>.
+ *
+ * <p>Explicit settings can be passed by using the {@link #settings(Settings)} method.
+ *
+ * <p>In any case, settings will be resolved from system properties as well that are either prefixed with <tt>es.</tt>
+ * or <tt>elasticsearch.</tt>.
+ *
+ * <p>An example for creating a simple server with optional settings loaded from the classpath:
+ *
+ * <pre>
+ * Server server = ServerBuilder.serverBuilder().server();
+ * </pre>
+ *
+ * <p>An example for creating a server with explicit settings (in this case, a node in the cluster that does not hold
+ * data):
+ *
+ * <pre>
+ * Server server = ServerBuilder.serverBuilder()
+ *                      .settings(ImmutableSettings.settingsBuilder().putBoolean("node.data", false)
+ *                      .server();
+ * </pre>
+ *
+ * <p>When done with the server, make sure you call {@link Server#close()} on it.
+ *
  * @author kimchy (Shay Banon)
  */
 public class ServerBuilder {
@@ -32,19 +61,32 @@ public class ServerBuilder {
 
     private boolean loadConfigSettings = true;
 
+    /**
+     * A convenient factory method to create a {@link ServerBuilder}.
+     */
     public static ServerBuilder serverBuilder() {
         return new ServerBuilder();
     }
 
+    /**
+     * Explicit server settings to set.
+     */
     public ServerBuilder settings(Settings.Builder settings) {
         return settings(settings.build());
     }
 
+    /**
+     * Explicit server settings to set.
+     */
     public ServerBuilder settings(Settings settings) {
         this.settings = settings;
         return this;
     }
 
+    /**
+     * Should the server builder automatically try and load config settings from the file system / classpath. Defaults
+     * to <tt>true</tt>.
+     */
     public ServerBuilder loadConfigSettings(boolean loadConfigSettings) {
         this.loadConfigSettings = loadConfigSettings;
         return this;
diff --git a/modules/elasticsearch/src/main/java/org/elasticsearch/server/package-info.java b/modules/elasticsearch/src/main/java/org/elasticsearch/server/package-info.java
new file mode 100644
index 00000000000..9c250a293b6
--- /dev/null
+++ b/modules/elasticsearch/src/main/java/org/elasticsearch/server/package-info.java
@@ -0,0 +1,23 @@
+/*
+ * Licensed to Elastic Search and Shay Banon under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. Elastic Search licenses this
+ * file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Allow to build a {@link Server} using {@link ServerBuilder} which is a node within the cluster.
+ */
+package org.elasticsearch.server;
\ No newline at end of file