javadoc

andimarek · andimarek · commit bd830f8e89b1 · 2018-05-27T20:18:14.000+10:00
diff --git a/src/main/java/graphql/analysis/QueryReducer.java b/src/main/java/graphql/analysis/QueryReducer.java
@@ -2,9 +2,26 @@
 
 import graphql.PublicApi;
 
+/**
+ * Used by {@link QueryTraversal} to reduce the fields of a Document (or part of it) to a single value.
+ * <p/>
+ * How this happens in detail (pre vs post-order for example) is defined by {@link QueryTraversal}.
+ * <p/>
+ * See {@link QueryTraversal#reducePostOrder(QueryReducer, Object)} and {@link QueryTraversal#reducePreOrder(QueryReducer, Object)}
+ *
+ * @param <T>
+ */
 @PublicApi
 @FunctionalInterface
 public interface QueryReducer<T> {
 
-    T reduceField(QueryVisitorFieldEnvironment reducerEnvironment, T acc);
+    /**
+     * Called each time a field is visited.
+     *
+     * @param fieldEnvironment
+     * @param acc              the previous result
+     *
+     * @return the new result
+     */
+    T reduceField(QueryVisitorFieldEnvironment fieldEnvironment, T acc);
 }
diff --git a/src/main/java/graphql/analysis/QueryTraversal.java b/src/main/java/graphql/analysis/QueryTraversal.java
@@ -36,6 +36,15 @@
 import static graphql.Assert.assertShouldNeverHappen;
 import static graphql.language.NodeTraverser.LeaveOrEnter.LEAVE;
 
+/**
+ * Helps to traverse (or reduce) a Document (or parts of it) and tracks at the same time the corresponding Schema types.
+ * <p/>
+ * This is an important distinction to just traversing the Document without any type information: Each field has a clearly
+ * defined type. See {@link QueryVisitorFieldEnvironment}.
+ * <p/>
+ * Further are the built in Directives skip/include automatically evaluated: if parts of the Document should be ignored they will not
+ * be visited.
+ */
 @PublicApi
 public class QueryTraversal {
 
@@ -76,27 +85,33 @@ public QueryTraversal(GraphQLSchema schema,
         this.childrenOfSelectionProvider = new ChildrenOfSelectionProvider(fragmentsByName);
     }
 
+    /**
+     * Visits the Document (or parts of it) in post-order.
+     *
+     * @param visitor
+     */
     public void visitPostOrder(QueryVisitor visitor) {
         visitImpl(visitor, false);
     }
 
+    /**
+     * Visits the Document (or parts of it) in pre-order.
+     *
+     * @param visitor
+     */
     public void visitPreOrder(QueryVisitor visitor) {
         visitImpl(visitor, true);
     }
 
-    private GraphQLObjectType getRootTypeFromOperation(OperationDefinition operationDefinition) {
-        switch (operationDefinition.getOperation()) {
-            case MUTATION:
-                return assertNotNull(schema.getMutationType());
-            case QUERY:
-                return assertNotNull(schema.getQueryType());
-            case SUBSCRIPTION:
-                return assertNotNull(schema.getSubscriptionType());
-            default:
-                return assertShouldNeverHappen();
-        }
-    }
-
+    /**
+     * Reduces the fields of a Document (or parts of it) to a single value. The fields are visited in post-order.
+     *
+     * @param queryReducer
+     * @param initialValue
+     * @param <T>
+     *
+     * @return the calculated overall value
+     */
     @SuppressWarnings("unchecked")
     public <T> T reducePostOrder(QueryReducer<T> queryReducer, T initialValue) {
         // compiler hack to make acc final and mutable :-)
@@ -110,6 +125,15 @@ public void visitField(QueryVisitorFieldEnvironment env) {
         return (T) acc[0];
     }
 
+    /**
+     * Reduces the fields of a Document (or parts of it) to a single value. The fields are visited in pre-order.
+     *
+     * @param queryReducer
+     * @param initialValue
+     * @param <T>
+     *
+     * @return the calucalated overall value
+     */
     @SuppressWarnings("unchecked")
     public <T> T reducePreOrder(QueryReducer<T> queryReducer, T initialValue) {
         // compiler hack to make acc final and mutable :-)
@@ -123,6 +147,19 @@ public void visitField(QueryVisitorFieldEnvironment env) {
         return (T) acc[0];
     }
 
+    private GraphQLObjectType getRootTypeFromOperation(OperationDefinition operationDefinition) {
+        switch (operationDefinition.getOperation()) {
+            case MUTATION:
+                return assertNotNull(schema.getMutationType());
+            case QUERY:
+                return assertNotNull(schema.getQueryType());
+            case SUBSCRIPTION:
+                return assertNotNull(schema.getSubscriptionType());
+            default:
+                return assertShouldNeverHappen();
+        }
+    }
+
     private List<Node> childrenOf(Node selection) {
         return childrenOfSelectionProvider.getSelections((Selection) selection);
     }
diff --git a/src/main/java/graphql/analysis/QueryVisitor.java b/src/main/java/graphql/analysis/QueryVisitor.java
@@ -2,6 +2,11 @@
 
 import graphql.PublicApi;
 
+/**
+ * User by {@link QueryTraversal} to visit the nodes of a Query.
+ * <p/>
+ * How this happens in detail (pre vs post-order for example) is defined by {@link QueryTraversal}.
+ */
 @PublicApi
 public interface QueryVisitor {
 
