add some documentation

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

@@ -115,10 +115,22 @@ public interface FetchSubPhase {
 
     void hitsExecute(SearchContext context, InternalSearchHit[] hits);
 
+    /**
+     * This interface is in the fetch phase plugin mechanism.
+     * Whenever a new search is executed we create a new {@link SearchContext} that holds individual contexts for each {@link org.elasticsearch.search.fetch.FetchSubPhase}.
+     * Fetch phases that use the plugin mechanism must provide a ContextFactory to the SearchContext that creates the fetch phase context and also associates them with a name.
+     * See {@link SearchContext#getFetchSubPhaseContext(FetchSubPhase.ContextFactory)}
+     */
     public interface ContextFactory {
 
+        /**
+         * The name of the context.
+         */
         public String getName();
 
+        /**
+         * Creates a new instance of a FetchSubPhaseContext that holds all information a FetchSubPhase needs to execute on hits.
+         */
         public FetchSubPhaseContext newContextInstance();
     }
 }

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

@@ -19,14 +19,26 @@
 
 package org.elasticsearch.search.fetch;
 
+/**
+ * This class stores  if or if not a FetchSubPhase is supposed to execute.
+ * It be extended by FetchSubPhases to hold information the phase needs to execute on hits.
+ * See {@link org.elasticsearch.search.fetch.FetchSubPhase.ContextFactory} and also {@link org.elasticsearch.search.fetch.fielddata.FieldDataFieldsContext} for an example.
+ */
 public class FetchSubPhaseContext {
 
+    // This is to store if the FetchSubPhase should be executed at all.
     private boolean hitExecutionNeeded = false;
 
+    /**
+     * Set if this phase should be executed at all.
+     */
     void setHitExecutionNeeded(boolean hitExecutionNeeded) {
         this.hitExecutionNeeded = hitExecutionNeeded;
     }
 
+    /**
+     * Returns if this phase be executed at all.
+     */
     public boolean hitExecutionNeeded() {
         return hitExecutionNeeded;
     }

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

@@ -33,7 +33,17 @@ import org.elasticsearch.search.highlight.HighlightPhase;
 import java.util.List;
 
 /**
- *
+ * Module for registering fetch sub phases. Fetch phases are executed when the document is finally
+ * retrieved from the shard. To implement a new fetch phase one needs to implement the following classes and interfaces
+ * <p/>
+ * <ul>
+ * <li>  {@link FetchSubPhaseParseElement} </li>
+ * <li>  {@link FetchSubPhase} </li>
+ * <li>  {@link FetchSubPhaseContext} </li>
+ * </ul>
+ * <p/>
+ * The FetchSubPhase must then be registered with this module with {@link FetchSubPhaseModule#registerFetchSubPhase(Class<? extends FetchSubPhase>)}.
+ * See {@link FieldDataFieldsFetchSubPhase} for an example.
  */
 public class FetchSubPhaseModule extends AbstractModule {
 

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

@@ -23,16 +23,26 @@ import org.elasticsearch.common.xcontent.XContentParser;
 import org.elasticsearch.search.SearchParseElement;
 import org.elasticsearch.search.internal.SearchContext;
 
+/**
+ * A parse element for a {@link org.elasticsearch.search.fetch.FetchSubPhase} that is used when parsing a search request.
+ */
 public abstract class FetchSubPhaseParseElement implements SearchParseElement {
 
     @Override
-    public void parse(XContentParser parser, SearchContext context) throws Exception {
+    final public void parse(XContentParser parser, SearchContext context) throws Exception {
         FetchSubPhaseContext fetchSubPhaseContext = context.getFetchSubPhaseContext(getContextFactory());
+        // this is to make sure that the SubFetchPhase knows it should execute
         fetchSubPhaseContext.setHitExecutionNeeded(true);
         innerParse(parser, fetchSubPhaseContext);
     }
 
+    /**
+     * Implement the actual parsing here.
+     */
     protected abstract void innerParse(XContentParser parser, FetchSubPhaseContext fetchSubPhaseContext) throws Exception;
 
+    /**
+     * Return the ContextFactory for this FetchSubPhase.
+     */
     protected abstract FetchSubPhase.ContextFactory getContextFactory();
 }