add java docs to all of the SearchPhase implementations

core/src/main/java/org/elasticsearch/search/aggregations/AggregationPhase.java

@@ -40,7 +40,7 @@ import java.util.Collections;
 import java.util.List;
 
 /**
- *
+ * Aggregation phase of a search request, used to collect aggregations
  */
 public class AggregationPhase implements SearchPhase {
 

core/src/main/java/org/elasticsearch/search/dfs/DfsPhase.java

@@ -37,7 +37,8 @@ import java.util.Collection;
 import java.util.Iterator;
 
 /**
- *
+ * Dfs phase of a search request, used to make scoring 100% accurate by collecting additional info from each shard before the query phase.
+ * The additional information is used to better compare the scores coming from all the shards, which depend on local factors (e.g. idf)
  */
 public class DfsPhase implements SearchPhase {
 

core/src/main/java/org/elasticsearch/search/fetch/FetchPhase.java

@@ -66,7 +66,8 @@ import static java.util.Collections.unmodifiableMap;
 import static org.elasticsearch.common.xcontent.XContentFactory.contentBuilder;
 
 /**
- * Fetch phase of a search request
+ * Fetch phase of a search request, used to fetch the actual top matching documents to be returned to the client, identified
+ * after reducing all of the matches returned by the query phase
  */
 public class FetchPhase implements SearchPhase {
 

core/src/main/java/org/elasticsearch/search/query/QueryPhase.java

@@ -68,7 +68,8 @@ import java.util.List;
 import java.util.concurrent.Callable;
 
 /**
- *
+ * Query phase of a search request, used to run the query and get back from each shard information about the matching documents
+ * (document ids and score or sort criteria) so that matches can be reduced on the coordinating node
  */
 public class QueryPhase implements SearchPhase {
 

core/src/main/java/org/elasticsearch/search/rescore/RescorePhase.java

@@ -29,6 +29,7 @@ import org.elasticsearch.search.internal.SearchContext;
 import java.io.IOException;
 
 /**
+ * Rescore phase of a search request, used to run potentially expensive scoring models against the top matching documents.
  */
 public class RescorePhase extends AbstractComponent implements SearchPhase {
 

core/src/main/java/org/elasticsearch/search/suggest/SuggestPhase.java

@@ -35,6 +35,7 @@ import java.util.List;
 import java.util.Map;
 
 /**
+ * Suggest phase of a search request, used to collect suggestions
  */
 public class SuggestPhase extends AbstractComponent implements SearchPhase {