doc(Lazy) add yardoc for Lazy code

Author: rmosolgo

lib/graphql/execution/execute.rb

@@ -1,5 +1,6 @@
 module GraphQL
   module Execution
+    # A valid execution strategy
     class Execute
       PROPAGATE_NULL = :__graphql_propagate_null__
 
@@ -25,7 +26,7 @@ def resolve_selection(object, current_type, irep_nodes, query_ctx, mutation: fal
         query = query_ctx.query
         own_selections = query.selections(irep_nodes, current_type)
 
-        selection_result = SelectionResult.new(type: current_type)
+        selection_result = SelectionResult.new
 
         own_selections.each do |name, child_irep_nodes|
           field = query.get_field(current_type, child_irep_nodes.first.definition_name)
@@ -89,9 +90,7 @@ def resolve_field(owner, irep_nodes, parent_type, field, object, query_ctx)
 
         FieldResult.new(
           owner: owner,
-          parent_type: parent_type,
           field: field,
-          name: irep_node.name,
           value: result,
         )
       end

lib/graphql/execution/field_result.rb

@@ -1,27 +1,40 @@
 module GraphQL
   module Execution
+    # This is one key-value pair in a GraphQL response.
     class FieldResult
-      attr_reader :value, :parent_type, :field, :name, :owner
-      def initialize(parent_type:, field:, value:, name:, owner:)
-        @parent_type = parent_type
+      # @return [Any, Lazy] the GraphQL-ready response value, or a {Lazy} instance
+      attr_reader :value
+
+      # @return [GraphQL::Field] The field which resolved this value
+      attr_reader :field
+
+      # @return [SelectionResult] The result object that this field belongs to
+      attr_reader :owner
+
+      def initialize(field:, value:, owner:)
         @field = field
         @owner = owner
-        @name = name
         self.value = value
       end
 
+      # Set a new value for this field in the response.
+      # It may be updated after resolving a {Lazy}.
+      # If it is {Execute::PROPAGATE_NULL}, tell the owner to propagate null.
+      # If the value is a {SelectionResult}, make a link with it, and if it's already null,
+      # propagate the null as needed.
+      # @param new_value [Any] The GraphQL-ready value
       def value=(new_value)
         if new_value.is_a?(SelectionResult)
           if new_value.invalid_null?
-            new_value = new_value.invalid_null
+            new_value = GraphQL::Execution::Execute::PROPAGATE_NULL
           else
             new_value.owner = self
           end
         end
 
         if new_value == GraphQL::Execution::Execute::PROPAGATE_NULL
           if field.type.kind.non_null?
-            @owner.propagate_null(@name, new_value)
+            @owner.propagate_null
           else
             @value = nil
           end
@@ -31,7 +44,7 @@ def value=(new_value)
       end
 
       def inspect
-        "#<FieldResult #{name.inspect} => #{value.inspect} (#{field.type})>"
+        "#<FieldResult #{value.inspect} (#{field.type})>"
       end
     end
   end

lib/graphql/execution/lazy/lazy_method_map.rb

@@ -1,6 +1,9 @@
 module GraphQL
   module Execution
     class Lazy
+      # {GraphQL::Schema} uses this to match returned values to lazy resolution methods.
+      # Methods may be registered for classes, they apply to its subclasses also.
+      # The result of this lookup is cached for future resolutions.
       class LazyMethodMap
         def initialize
           @storage = {}

lib/graphql/execution/lazy/resolve.rb

@@ -3,13 +3,13 @@ module Execution
     class Lazy
       # Helpers for dealing with data structures containing {Lazy} instances
       module Resolve
+        # Mutate `value`, replacing {Lazy} instances in place with their resolved values
+        # @return [void]
         def self.resolve(value)
           lazies = resolve_in_place(value)
           deep_sync(lazies)
         end
 
-        # Mutate `value`, replacing {Lazy} instances in place with their resolved values
-        # @return [void]
         def self.resolve_in_place(value)
           lazies = []
 

lib/graphql/execution/selection_result.rb

@@ -1,27 +1,33 @@
 module GraphQL
   module Execution
+    # A set of key-value pairs suitable for a GraphQL response.
     class SelectionResult
-      def initialize(type:)
-        @type = type
+      def initialize
         @storage = {}
         @owner = nil
         @invalid_null = false
       end
 
+      # @param key [String] The name for this value in the result
+      # @param field_result [FieldResult] The result for this field
       def set(key, field_result)
         @storage[key] = field_result
       end
 
+      # @param key [String] The name of an already-defined result
+      # @return [FieldResult] The result for this field
       def fetch(key)
         @storage.fetch(key)
       end
 
+      # Visit each key-result pair in this result
       def each
         @storage.each do |key, field_res|
           yield(key, field_res)
         end
       end
 
+      # @return [Hash] A plain Hash representation of this result
       def to_h
         if @invalid_null
           nil
@@ -30,29 +36,27 @@ def to_h
         end
       end
 
-      def propagate_null(key, value)
+      # A field has been unexpectedly nullified.
+      # Tell the owner {FieldResult} if it is present.
+      # Record {#invalid_null} in case an owner is added later.
+      def propagate_null
         if @owner
-          @owner.value = value
+          @owner.value = GraphQL::Execution::Execute::PROPAGATE_NULL
         end
-        @invalid_null = value
+        @invalid_null = true
       end
 
+      # @return [Boolean] True if this selection has been nullified by a null child
       def invalid_null?
         @invalid_null
       end
 
-      def invalid_null
-        @invalid_null
-      end
-
+      # @param field_result [FieldResult] The field that this selection belongs to (used for propagating nulls)
       def owner=(field_result)
         if @owner
           raise("Can't change owners of SelectionResult")
         else
           @owner = field_result
-          if @invalid_null
-            @owner.value = @invalid_null
-          end
         end
       end