graphql-java
diff --git a/‎src/main/java/graphql/execution/instrumentation/FieldFetchingInstrumentationContext.java‎
Lines changed: 20 additions & 19 deletions b/‎src/main/java/graphql/execution/instrumentation/FieldFetchingInstrumentationContext.java‎
Lines changed: 20 additions & 19 deletions
diff --git a/‎src/main/java/graphql/execution/instrumentation/Instrumentation.java‎
Lines changed: 5 additions & 0 deletions b/‎src/main/java/graphql/execution/instrumentation/Instrumentation.java‎
Lines changed: 5 additions & 0 deletions
@@ -2,12 +2,30 @@
 
 import graphql.Internal;
 import graphql.PublicSpi;
+import graphql.execution.instrumentation.parameters.InstrumentationFieldFetchParameters;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+/**
+ * FieldFetchingInstrumentationContext is returned back from the {@link Instrumentation#beginFieldFetching(InstrumentationFieldFetchParameters, InstrumentationState)}
+ * method, and it's much like the normal {@link InstrumentationContext} type except it also
+ * gives the value that was returned by a fields {@link graphql.schema.DataFetcher}.  This allows
+ * you to know if the field value is a completely materialised field or if it's a {@link java.util.concurrent.CompletableFuture}
+ * promise to a value.
+ */
 @PublicSpi
 public interface FieldFetchingInstrumentationContext extends InstrumentationContext<Object> {
 
+    /**
+     * This is called back with the value fetched for the field by its {@link graphql.schema.DataFetcher}.
+     * This can be a materialised java object or it maybe a {@link java.util.concurrent.CompletableFuture}
+     * promise to some async value that has not yet completed.
+     *
+     * @param fetchedValue a value that a field's {@link graphql.schema.DataFetcher} returned
+     */
+    default void onFetchedValue(Object fetchedValue) {
+    }
+
     @Internal
     FieldFetchingInstrumentationContext NOOP = new FieldFetchingInstrumentationContext() {
         @Override
@@ -17,18 +35,13 @@ public void onDispatched() {
         @Override
         public void onCompleted(Object result, Throwable t) {
         }
-
-        @Override
-        public void onFetchedValue(Object fetchedValue) {
-        }
     };
 
     /**
-     * This creates a no-op {@link InstrumentationContext} if the one pass in is null
+     * This creates a no-op {@link InstrumentationContext} if the one passed in is null
      *
      * @param nullableContext a {@link InstrumentationContext} that can be null
-     *
-     * @return a non null {@link InstrumentationContext} that maybe a no-op
+     * @return a non-null {@link InstrumentationContext} that maybe a no-op
      */
     @NotNull
     @Internal
@@ -51,18 +64,6 @@ public void onDispatched() {
             public void onCompleted(Object result, Throwable t) {
                 context.onCompleted(result, t);
             }
-
-            @Override
-            public void onFetchedValue(Object fetchedValue) {
-            }
         };
     }
-
-    /**
-     * This is called back with value fetched for the field.
-     *
-     * @param fetchedValue a value that a field's {@link graphql.schema.DataFetcher} returned
-     */
-    default void onFetchedValue(Object fetchedValue) {
-    }
 }
@@ -209,6 +209,11 @@ default InstrumentationContext<Object> beginFieldFetch(InstrumentationFieldFetch
      * This is called just before a field {@link DataFetcher} is invoked. The {@link FieldFetchingInstrumentationContext#onFetchedValue(Object)}
      * callback will be invoked once a value is returned by a {@link DataFetcher} but perhaps before
      * its value is completed if it's a {@link CompletableFuture} value.
+     * <p>
+     * This method is the replacement method for the now deprecated {@link #beginFieldFetch(InstrumentationFieldFetchParameters, InstrumentationState)}
+     * method, and it should be implemented in new {@link Instrumentation} classes.  This default version of this
+     * method calls back to the deprecated  {@link #beginFieldFetch(InstrumentationFieldFetchParameters, InstrumentationState)} method
+     * so that older implementations continue to work.
      *
      * @param parameters the parameters to this step
      * @param state      the state created during the call to {@link #createStateAsync(InstrumentationCreateStateParameters)}