graphql-java · bbakerman · Sep 25, 2017 · Sep 22, 2017
diff --git a/src/main/java/graphql/Directives.java b/src/main/java/graphql/Directives.java
@@ -5,9 +5,14 @@
 import graphql.schema.GraphQLNonNull;
 
 import static graphql.Scalars.GraphQLBoolean;
-import static graphql.introspection.Introspection.DirectiveLocation.*;
+import static graphql.introspection.Introspection.DirectiveLocation.FIELD;
+import static graphql.introspection.Introspection.DirectiveLocation.FRAGMENT_SPREAD;
+import static graphql.introspection.Introspection.DirectiveLocation.INLINE_FRAGMENT;
 import static graphql.schema.GraphQLArgument.newArgument;
 
+/**
+ * The query directives that are under stood by graphql-java
+ */
 public class Directives {
 
     public static final GraphQLDirective IncludeDirective = GraphQLDirective.newDirective()

diff --git a/src/main/java/graphql/ErrorType.java b/src/main/java/graphql/ErrorType.java
@@ -1,6 +1,10 @@
 package graphql;
 
 
+/**
+ * All the errors in graphql belong to one of these categories
+ */
+@PublicApi
 public enum ErrorType {
     InvalidSyntax,
     ValidationError,

diff --git a/src/main/java/graphql/ExceptionWhileDataFetching.java b/src/main/java/graphql/ExceptionWhileDataFetching.java
@@ -12,6 +12,9 @@
 import static graphql.Assert.assertNotNull;
 import static java.lang.String.format;
 
+/**
+ * This graphql error will be used if a runtime exception is encountered while a data fetcher is invoked
+ */
 @PublicApi
 public class ExceptionWhileDataFetching implements GraphQLError {
 

diff --git a/src/main/java/graphql/ExecutionInput.java b/src/main/java/graphql/ExecutionInput.java
@@ -3,6 +3,9 @@
 import java.util.Collections;
 import java.util.Map;
 
+/**
+ * This represents the series of values that can be input on a graphql query execution
+ */
 @PublicApi
 public class ExecutionInput {
     private final String query;
@@ -20,22 +23,37 @@ public ExecutionInput(String query, String operationName, Object context, Object
         this.variables = variables;
     }
 
+    /**
+     * @return the query text
+     */
     public String getQuery() {
         return query;
     }
 
+    /**
+     * @return the name of the query operation
+     */
     public String getOperationName() {
         return operationName;
     }
 
+    /**
+     * @return the context object to pass to all data fetchers
+     */
     public Object getContext() {
         return context;
     }
 
+    /**
+     * @return the root object to start the query execution on
+     */
     public Object getRoot() {
         return root;
     }
 
+    /**
+     * @return a map of variables that can be referenced via $syntax in the query
+     */
     public Map<String, Object> getVariables() {
         return variables;
     }
@@ -51,6 +69,9 @@ public String toString() {
                 '}';
     }
 
+    /**
+     * @return a new builder of ExecutionInput objects
+     */
     public static Builder newExecutionInput() {
         return new Builder();
     }

diff --git a/src/main/java/graphql/GraphQL.java b/src/main/java/graphql/GraphQL.java
@@ -34,6 +34,14 @@
 import static graphql.Assert.assertNotNull;
 import static graphql.InvalidSyntaxError.toInvalidSyntaxError;
 
+/**
+ * This class is where all graphql-java query execution begins.  It combines the objects that are needed
+ * to make a successful graphql query, with the most important being the {@link graphql.schema.GraphQLSchema schema}
+ * and the {@link graphql.execution.ExecutionStrategy execution strategy}
+ *
+ * Building this object is very cheap and can be done on each execution if necessary.  Building the schema is often not
+ * as cheap, especially if its parsed from graphql IDL schema format via {@link graphql.schema.idl.SchemaParser}.
+ */
 @PublicApi
 public class GraphQL {
 

diff --git a/src/main/java/graphql/Internal.java b/src/main/java/graphql/Internal.java
@@ -8,6 +8,12 @@
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.TYPE;
 
+/**
+ * This represents code that the graphql-java project considers internal code that MAY not be stable within
+ * major releases.
+ *
+ * In general unecessary changes will be avoided but you should not depend on internal classes being stable
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = {CONSTRUCTOR, METHOD, TYPE})
 public @interface Internal {

diff --git a/src/main/java/graphql/PublicApi.java b/src/main/java/graphql/PublicApi.java
@@ -9,6 +9,13 @@
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.TYPE;
 
+/**
+ * This represents code that the graphql-java project considers public API and has an imperative to be stable within
+ * major releases.
+ *
+ * The guarantee  is for code calling classes and interfaces with this annotation, not derived from them.  New methods
+ * maybe be added which would break derivations but not callers.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = {CONSTRUCTOR, METHOD, TYPE})
 @Documented

diff --git a/src/main/java/graphql/PublicSpi.java b/src/main/java/graphql/PublicSpi.java
@@ -9,6 +9,15 @@
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.TYPE;
 
+/**
+ * This represents code that the graphql-java project considers public SPI and has an imperative to be stable within
+ * major releases.
+ *
+ * The guarantee  is for callers of code with this annotation as well as derivations that inherit / implement this code.
+ *
+ * New methods will not be added (without using default methods say) that would nominally breaks SPI implementations
+ * within a major release.
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = {CONSTRUCTOR, METHOD, TYPE})
 @Documented