Merge pull request #3242 from graphql-java/javadoc_fixups

Java doc fixups and some renaming

src/main/java/graphql/execution/DataFetcherResult.java

@@ -127,6 +127,7 @@ public DataFetcherResult<T> transform(Consumer<Builder<T>> builderConsumer) {
      * All other values are left unmodified.
      *
      * @param transformation the transformation that should be applied to the data
+     * @param <R>            the result type
      *
      * @return a new instance with where the data value has been transformed
      */

src/main/java/graphql/normalized/ExecutableNormalizedField.java

@@ -17,7 +17,7 @@
 import graphql.schema.GraphQLSchema;
 import graphql.schema.GraphQLUnionType;
 import graphql.util.FpKit;
-import graphql.util.Ref;
+import graphql.util.MutableRef;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
@@ -526,7 +526,7 @@ private Set<GraphQLInterfaceType> getInterfacesCommonToAllOutputTypes(GraphQLSch
             }
         }
 
-        Ref<Set<GraphQLInterfaceType>> commonInterfaces = new Ref<>();
+        MutableRef<Set<GraphQLInterfaceType>> commonInterfaces = new MutableRef<>();
         forEachFieldDefinition(schema, (fieldDef) -> {
             var outputType = unwrapAll(fieldDef.getType());
 

src/main/java/graphql/schema/diffing/EditorialCostForMapping.java

@@ -12,6 +12,12 @@
 @Internal
 public class EditorialCostForMapping {
     /**
+     * @param mapping     the mapping
+     * @param sourceGraph the source graph
+     * @param targetGraph the target graph
+     *
+     * @return the editorial cost
+     *
      * @see #baseEditorialCostForMapping(Mapping, SchemaGraph, SchemaGraph, List)
      */
     public static int baseEditorialCostForMapping(Mapping mapping, // can be a partial mapping
@@ -27,6 +33,13 @@ public static int baseEditorialCostForMapping(Mapping mapping, // can be a parti
      * Use this is as base cost when invoking
      * {@link #editorialCostForMapping(int, Mapping, SchemaGraph, SchemaGraph)}
      * as it heavily speeds up performance.
+     *
+     * @param mapping              the mapping
+     * @param sourceGraph          the source graph
+     * @param targetGraph          the target graph
+     * @param editOperationsResult the list of edit operations
+     *
+     * @return the editorial cost
      */
     public static int baseEditorialCostForMapping(Mapping mapping, // can be a partial mapping
                                                   SchemaGraph sourceGraph, // the whole graph
@@ -92,6 +105,13 @@ public static int baseEditorialCostForMapping(Mapping mapping, // can be a parti
      * {@link #baseEditorialCostForMapping(Mapping, SchemaGraph, SchemaGraph)}.
      * <p>
      * The sum of the non-fixed costs and the fixed costs is total editorial cost for mapping.
+     *
+     * @param baseCost    the starting base cost
+     * @param mapping     the mapping
+     * @param sourceGraph the source graph
+     * @param targetGraph the target graph
+     *
+     * @return the editorial cost
      */
     public static int editorialCostForMapping(int baseCost,
                                               Mapping mapping, // can be a partial mapping

src/main/java/graphql/schema/diffing/HungarianAlgorithm.java

@@ -34,7 +34,6 @@
  * one worker and so that no worker is assigned to more than one job in such a
  * manner so as to minimize the total cost of completing the jobs.
  * <p>
- * <p>
  * An assignment for a cost matrix that has more workers than jobs will
  * necessarily include unassigned workers, indicated by an assignment value of
  * -1; in no other circumstance will there be unassigned workers. Similarly, an
@@ -43,7 +42,6 @@
  * jobs. For completeness, an assignment for a square cost matrix will give
  * exactly one unique worker to each job.
  * <p>
- * <p>
  * This version of the Hungarian algorithm runs in time O(n^3), where n is the
  * maximum among the number of workers and the number of jobs.
  *
@@ -180,7 +178,6 @@ public int[] execute() {
      * more zero-slack edges (the labels of committed jobs are simultaneously
      * decreased by the same amount in order to maintain a feasible labeling).
      * <p>
-     * <p>
      * The runtime of a single phase of the algorithm is O(n^2), where n is the
      * dimension of the internal square cost matrix, since each edge is visited at
      * most once and since increasing the labeling is accomplished in time O(n) by
@@ -299,6 +296,9 @@ protected void initializePhase(int w) {
 
     /**
      * Helper method to record a matching between worker w and job j.
+     *
+     * @param w the worker
+     * @param j the job
      */
     protected void match(int w, int j) {
         matchJobByWorker[w] = j;
@@ -345,6 +345,8 @@ protected void reduce() {
      * Update labels with the specified slack by adding the slack value for
      * committed workers and by subtracting the slack value for committed jobs. In
      * addition, update the minimum slack values appropriately.
+     *
+     * @param slack the specified slack
      */
     protected void updateLabeling(double slack) {
         for (int w = 0; w < dim; w++) {

src/main/java/graphql/schema/diffing/PossibleMappingsCalculator.java

@@ -1092,6 +1092,8 @@ private Map<Vertex, Vertex> getFixedParentRestrictions(SchemaGraph sourceGraph,
      * e.g. for an output {collar: Dog} then the collar vertex must be a child of Dog in the mapping.
      *
      * @param mapping the mapping to get non-fixed parent restrictions for
+     * @param sourceGraph the source graph
+     * @param targetGraph the target graph
      * @return Map where key is any vertex, and the value is the parent that vertex must map to
      */
     public Map<Vertex, Vertex> getNonFixedParentRestrictions(SchemaGraph sourceGraph,

src/main/java/graphql/schema/diffing/SchemaGraph.java

@@ -260,6 +260,9 @@ public Vertex getAppliedDirectiveContainerForAppliedDirective(Vertex appliedDire
 
     /**
      * Gets the one inverse adjacent edge to the input and gets the other vertex.
+     *
+     * @param input  the vertex input
+     * @return a vertex
      */
     public Vertex getSingleAdjacentInverseVertex(Vertex input) {
         Collection<Edge> adjacentVertices = this.getAdjacentEdgesInverseNonCopy(input);

src/main/java/graphql/util/MutableRef.java

@@ -0,0 +1,15 @@
+package graphql.util;
+
+import graphql.Internal;
+
+/**
+ * This class is useful for creating a mutable reference to a variable that can be changed when you are in an
+ * effectively final bit of code.  Its more performant than an {@link java.util.concurrent.atomic.AtomicReference}
+ * to gain mutability.  Use this very carefully - Its not expected to be commonly used.
+ *
+ * @param <T> for two
+ */
+@Internal
+public class MutableRef<T> {
+    public T value;
+}