graphql 2.6.9 → 2.6.14

data/lib/graphql/execution/lookahead.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module Execution
     # Lookahead creates a uniform interface to inspect the forthcoming selections.
@@ -9,28 +10,38 @@ module GraphQL
     # A field may get access to its lookahead by adding `extras: [:lookahead]`
     # to its configuration.
     #
-    # @example looking ahead in a field
-    #   field :articles, [Types::Article], null: false,
-    #     extras: [:lookahead]
+    # **Examples**
     #
-    #   # For example, imagine a faster database call
-    #   # may be issued when only some fields are requested.
-    #   #
-    #   # Imagine that _full_ fetch must be made to satisfy `fullContent`,
-    #   # we can look ahead to see if we need that field. If we do,
-    #   # we make the expensive database call instead of the cheap one.
-    #   def articles(lookahead:)
-    #     if lookahead.selects?(:full_content)
-    #       fetch_full_articles(object)
-    #     else
-    #       fetch_preview_articles(object)
-    #     end
+    # **Example: looking ahead in a field**
+    #
+    # ```ruby
+    # field :articles, [Types::Article], null: false,
+    #   extras: [:lookahead]
+    #
+    # # For example, imagine a faster database call
+    # # may be issued when only some fields are requested.
+    # #
+    # # Imagine that _full_ fetch must be made to satisfy `fullContent`,
+    # # we can look ahead to see if we need that field. If we do,
+    # # we make the expensive database call instead of the cheap one.
+    # def articles(lookahead:)
+    #   if lookahead.selects?(:full_content)
+    #     fetch_full_articles(object)
+    #   else
+    #     fetch_preview_articles(object)
     #   end
+    # end
+    # ```
     class Lookahead
-      # @param query [GraphQL::Query]
-      # @param ast_nodes [Array<GraphQL::Language::Nodes::Field>, Array<GraphQL::Language::Nodes::OperationDefinition>]
-      # @param field [GraphQL::Schema::Field] if `ast_nodes` are fields, this is the field definition matching those nodes
-      # @param root_type [Class] if `ast_nodes` are operation definition, this is the root type for that operation
+      # **Parameters**
+      #
+      # - `query` (`GraphQL::Query`)
+      # - `ast_nodes` (`Array<GraphQL::Language::Nodes::Field>, Array<GraphQL::Language::Nodes::OperationDefinition>`)
+      # - `field` (`GraphQL::Schema::Field`) — if `ast_nodes` are fields, this is the field definition matching those nodes
+      # - `root_type` (`Class`) — if `ast_nodes` are operation definition, this is the root type for that operation
+      #
+      # :call-seq:
+      #   initialize(GraphQL::Query query:, Array[GraphQL::Language::Nodes::Field] | Array[GraphQL::Language::Nodes::OperationDefinition] ast_nodes:, GraphQL::Schema::Field field:, Class root_type:, owner_type:)
       def initialize(query:, ast_nodes:, field: nil, root_type: nil, owner_type: nil)
         @ast_nodes = ast_nodes.freeze
         @field = field
@@ -40,16 +51,27 @@ module GraphQL
         @owner_type = owner_type
       end
 
-      # @return [Array<GraphQL::Language::Nodes::Field>]
+      # **Returns**
+      #
+      # - `Array<GraphQL::Language::Nodes::Field>`
       attr_reader :ast_nodes
 
-      # @return [GraphQL::Schema::Field]
+      # **Returns**
+      #
+      # - `GraphQL::Schema::Field`
       attr_reader :field
 
-      # @return [GraphQL::Schema::Object, GraphQL::Schema::Union, GraphQL::Schema::Interface]
+      # **Returns**
+      #
+      # - `GraphQL::Schema::Object, GraphQL::Schema::Union, GraphQL::Schema::Interface`
       attr_reader :owner_type
 
-      # @return [Hash<Symbol, Object>]
+      # **Returns**
+      #
+      # - `Hash<Symbol, Object>`
+      #
+      # :call-seq:
+      #   arguments() -> Hash[Symbol, Object]
       def arguments
         if defined?(@arguments)
           @arguments
@@ -80,9 +102,18 @@ module GraphQL
       # against the arguments in the next selection. This method will return false
       # if any of the given `arguments:` are not present and matching in the next selection.
       # (But, the next selection may contain _more_ than the given arguments.)
-      # @param field_name [String, Symbol]
-      # @param arguments [Hash] Arguments which must match in the selection
-      # @return [Boolean]
+      #
+      # **Parameters**
+      #
+      # - `field_name` (`String, Symbol`)
+      # - `arguments` (`Hash`) — Arguments which must match in the selection
+      #
+      # **Returns**
+      #
+      # - `Boolean`
+      #
+      # :call-seq:
+      #   selects?(String | Symbol field_name, selected_type:, Hash arguments:) -> bool
       def selects?(field_name, selected_type: @selected_type, arguments: nil)
         selection(field_name, selected_type: selected_type, arguments: arguments).selected?
       end
@@ -96,22 +127,45 @@ module GraphQL
       # against the arguments in the next selection. This method will return false
       # if any of the given `arguments:` are not present and matching in the next selection.
       # (But, the next selection may contain _more_ than the given arguments.)
-      # @param alias_name [String, Symbol]
-      # @param arguments [Hash] Arguments which must match in the selection
-      # @return [Boolean]
+      #
+      # **Parameters**
+      #
+      # - `alias_name` (`String, Symbol`)
+      # - `arguments` (`Hash`) — Arguments which must match in the selection
+      #
+      # **Returns**
+      #
+      # - `Boolean`
+      #
+      # :call-seq:
+      #   selects_alias?(String | Symbol alias_name, Hash arguments:) -> bool
       def selects_alias?(alias_name, arguments: nil)
         alias_selection(alias_name, arguments: arguments).selected?
       end
 
-      # @return [Boolean] True if this lookahead represents a field that was requested
+      # **Returns**
+      #
+      # - `Boolean` — True if this lookahead represents a field that was requested
+      #
+      # :call-seq:
+      #   selected?() -> bool
       def selected?
         true
       end
 
-      # Like {#selects?}, but can be used for chaining.
-      # It returns a null object (check with {#selected?})
-      # @param field_name [String, Symbol]
-      # @return [GraphQL::Execution::Lookahead]
+      # Like [selects?](rdoc-ref:#selects?), but can be used for chaining.
+      # It returns a null object (check with [selected?](rdoc-ref:#selected?))
+      #
+      # **Parameters**
+      #
+      # - `field_name` (`String, Symbol`)
+      #
+      # **Returns**
+      #
+      # - `GraphQL::Execution::Lookahead`
+      #
+      # :call-seq:
+      #   selection(String | Symbol field_name, selected_type:, arguments:) -> GraphQL::Execution::Lookahead
       def selection(field_name, selected_type: @selected_type, arguments: nil)
         next_field_defn = case field_name
         when String
@@ -141,12 +195,18 @@ module GraphQL
         lookahead_for_selection(next_field_defn, selected_type, arguments)
       end
 
-      # Like {#selection}, but for aliases.
-      # It returns a null object (check with {#selected?})
-      # @return [GraphQL::Execution::Lookahead]
+      # Like [selection](rdoc-ref:#selection), but for aliases.
+      # It returns a null object (check with [selected?](rdoc-ref:#selected?))
+      #
+      # **Returns**
+      #
+      # - `GraphQL::Execution::Lookahead`
+      #
+      # :call-seq:
+      #   alias_selection(alias_name, selected_type:, arguments:) -> GraphQL::Execution::Lookahead
       def alias_selection(alias_name, selected_type: @selected_type, arguments: nil)
-        alias_cache_key = [alias_name, arguments]
-        return alias_selections[key] if alias_selections.key?(alias_name)
+        alias_cache_key = [alias_name, selected_type, arguments]
+        return alias_selections[alias_cache_key] if alias_selections.key?(alias_cache_key)
 
         alias_node = lookup_alias_node(ast_nodes, alias_name)
         return NULL_LOOKAHEAD unless alias_node
@@ -163,21 +223,34 @@ module GraphQL
         alias_selections[alias_cache_key] = lookahead_for_selection(next_field_defn, selected_type, alias_arguments, alias_name)
       end
 
-      # Like {#selection}, but for all nodes.
+      # Like [selection](rdoc-ref:#selection), but for all nodes.
       # It returns a list of Lookaheads for all Selections
       #
       # If `arguments:` is provided, each provided key/value will be matched
       # against the arguments in each selection. This method will filter the selections
       # if any of the given `arguments:` do not match the given selection.
       #
-      # @example getting the name of a selection
-      #   def articles(lookahead:)
-      #     next_lookaheads = lookahead.selections # => [#<GraphQL::Execution::Lookahead ...>, ...]
-      #     next_lookaheads.map(&:name) #=> [:full_content, :title]
-      #   end
+      # **Examples**
+      #
+      # **Example: getting the name of a selection**
       #
-      # @param arguments [Hash] Arguments which must match in the selection
-      # @return [Array<GraphQL::Execution::Lookahead>]
+      # ```ruby
+      # def articles(lookahead:)
+      #   next_lookaheads = lookahead.selections # => [#<GraphQL::Execution::Lookahead ...>, ...]
+      #   next_lookaheads.map(&:name) #=> [:full_content, :title]
+      # end
+      # ```
+      #
+      # **Parameters**
+      #
+      # - `arguments` (`Hash`) — Arguments which must match in the selection
+      #
+      # **Returns**
+      #
+      # - `Array<GraphQL::Execution::Lookahead>`
+      #
+      # :call-seq:
+      #   selections(Hash arguments:) -> Array[GraphQL::Execution::Lookahead]
       def selections(arguments: nil)
         subselections_by_type = {}
         subselections_on_type = subselections_by_type[@selected_type] = {}
@@ -202,13 +275,23 @@ module GraphQL
       # The method name of the field.
       # It returns the method_sym of the Lookahead's field.
       #
-      # @example getting the name of a selection
-      #   def articles(lookahead:)
-      #     article.selection(:full_content).name # => :full_content
-      #     # ...
-      #   end
+      # **Examples**
+      #
+      # **Example: getting the name of a selection**
+      #
+      # ```ruby
+      # def articles(lookahead:)
+      #   article.selection(:full_content).name # => :full_content
+      #   # ...
+      # end
+      # ```
+      #
+      # **Returns**
+      #
+      # - `Symbol`
       #
-      # @return [Symbol]
+      # :call-seq:
+      #   name() -> Symbol
       def name
         @field && @field.original_name
       end
@@ -217,7 +300,7 @@ module GraphQL
         "#<GraphQL::Execution::Lookahead #{@field ? "@field=#{@field.path.inspect}": "@root_type=#{@root_type}"} @ast_nodes.size=#{@ast_nodes.size}>"
       end
 
-      # This is returned for {Lookahead#selection} when a non-existent field is passed
+      # This is returned for [Lookahead#selection](rdoc-ref:Lookahead#selection) when a non-existent field is passed
       class NullLookahead < Lookahead
         # No inputs required here.
         def initialize

data/lib/graphql/execution/multiplex.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module Execution
     # Execute multiple queries under the same multiplex "umbrella".
@@ -17,12 +18,11 @@ module GraphQL
     #
     # If one query raises an application error, all queries will be in undefined states.
     #
-    # Validation errors and {GraphQL::ExecutionError}s are handled in isolation:
+    # Validation errors and [GraphQL::ExecutionError](rdoc-ref:GraphQL::ExecutionError)s are handled in isolation:
     # one of these errors in one query will not affect the other queries.
     #
-    # @see {Schema#multiplex} for public API
-    # @api private
-    class Multiplex
+    # See [Schema.multiplex](rdoc-ref:GraphQL::Schema::multiplex) for the public API
+    class Multiplex # :nodoc:
       include Tracing::Traceable
 
       attr_reader :context, :queries, :schema, :max_complexity, :dataloader, :current_trace

data/lib/graphql/execution/next.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 require "graphql/execution/prepare_object_step"
 require "graphql/execution/input_values"
 require "graphql/execution/field_resolve_step"
@@ -9,6 +10,8 @@ require "graphql/execution/runner"
 require "graphql/execution/selections_step"
 module GraphQL
   module Execution
+    #--
+    # @requires_ancestor: Kernel
     module Finalizer
       attr_accessor :path
 
@@ -30,6 +33,8 @@ module GraphQL
     module HaltExecution
     end
 
+    #--
+    # @requires_ancestor: Kernel
     module PostProcessor
       def after_resolve(field_results)
         raise RequiredImplementationMissingError, "#{self.class}#after_resolve should handle `field_results` and return a new value to use"
@@ -37,6 +42,8 @@ module GraphQL
     end
 
     module Next
+      #--
+      # @requires_ancestor: singleton(GraphQL::Schema)
       module SchemaExtension
         def execute_next(query_str = nil, query: nil, subscription_topic: nil, context: nil, document: nil, operation_name: nil, variables: nil, warden: nil, root_value: nil, validate: true, visibility_profile: nil)
           multiplex_context = if context

data/lib/graphql/execution/prepare_object_step.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module Execution
     class PrepareObjectStep
@@ -13,6 +14,7 @@ module GraphQL
         @resolved_type = nil
         @authorized_value = nil
         @authorization_error = nil
+        @execution_error = nil
         @key = key
         @next_step = :resolve_type
         @is_from_array = is_from_array
@@ -23,7 +25,12 @@ module GraphQL
         if @authorized_value
           query = @field_resolve_step.selections_step.query
           query.current_trace.begin_authorized(@resolved_type, @object, query.context)
-          @authorized_value = @field_resolve_step.sync(@authorized_value)
+          begin
+            @authorized_value = @runner.schema.sync_lazy(@authorized_value)
+          rescue StandardError => err
+            @authorized_value = nil
+            handle_authorization_error(err, query)
+          end
           query.current_trace.end_authorized(@resolved_type, @object, query.context, @authorized_value)
         elsif @resolved_type
           ctx = @field_resolve_step.selections_step.query.context
@@ -89,8 +96,9 @@ module GraphQL
           query.current_trace.begin_authorized(@resolved_type, @object, query.context)
           @authorized_value = @resolved_type.authorized?(@object, query.context)
           query.current_trace.end_authorized(@resolved_type, @object, query.context, @authorized_value)
-        rescue GraphQL::UnauthorizedError => auth_err
-          @authorization_error = auth_err
+        rescue StandardError => err
+          @authorized_value = nil
+          handle_authorization_error(err, query)
         end
 
         if @runner.resolves_lazies && @runner.lazy?(@authorized_value)
@@ -99,19 +107,14 @@ module GraphQL
         else
           create_result
         end
-      rescue GraphQL::RuntimeError => err
-        @graphql_result[@key] = add_field_error(err)
-      rescue StandardError => err
-        query ||= @field_resolve_step.selections_step.query
-        begin
-          query.handle_or_reraise(err, field: @field_resolve_step.field_definition, arguments: @field_resolve_step.arguments, object: @object) # rubocop:disable Development/ContextIsPassedCop
-        rescue GraphQL::RuntimeError => err
-          @graphql_result[@key] = add_field_error(err)
-        end
       end
 
       def create_result
-        if !@authorized_value
+        if @execution_error
+          # `.authorized?` raised (or its lazy value raised) an error other than UnauthorizedError:
+          # it isn't an authorization decision, so don't call `unauthorized_object`.
+          @graphql_result[@key] = add_field_error(@execution_error)
+        elsif !@authorized_value
           @authorization_error ||= GraphQL::UnauthorizedError.new(object: @object, type: @resolved_type, context: @field_resolve_step.selections_step.query.context)
         end
 
@@ -146,6 +149,28 @@ module GraphQL
 
         @field_resolve_step.authorized_finished(self)
       end
+
+      private
+
+      # Errors raised by `.authorized?` (or by syncing its lazy return value):
+      #
+      # - `UnauthorizedError` is equivalent to returning `false`, so it goes to `unauthorized_object`
+      # - Other `GraphQL::RuntimeError`s are added to the response for this field
+      # - Other errors go to `rescue_from` handlers, which might return a `GraphQL::RuntimeError`, or else re-raise
+      def handle_authorization_error(err, query)
+        case err
+        when GraphQL::UnauthorizedError
+          @authorization_error = err
+        when GraphQL::RuntimeError
+          @execution_error = err
+        else
+          begin
+            @authorized_value = query.handle_or_reraise(err, field: @field_resolve_step.field_definition, arguments: @field_resolve_step.arguments, object: @object) # rubocop:disable Development/ContextIsPassedCop
+          rescue GraphQL::RuntimeError => runtime_err
+            handle_authorization_error(runtime_err, query)
+          end
+        end
+      end
     end
   end
 end

data/lib/graphql/execution/resolve_type_step.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module Execution
     class ResolveTypeStep
@@ -17,7 +18,7 @@ module GraphQL
       def self.assert_valid_resolved_type(abstract_type, resolved_type, object, field_resolution_step, query: field_resolution_step.selections_step.query)
         possible_types = query.types.possible_types(abstract_type)
         if !possible_types.include?(resolved_type)
-          err_class = abstract_type::UnresolvedTypeError
+          err_class = abstract_type.const_get(:UnresolvedTypeError)
           type_error = err_class.new(object, field_resolution_step.field_definition, abstract_type, resolved_type, possible_types)
           query.schema.type_error(type_error, query.context)
         end

data/lib/graphql/execution/runner.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module Execution
     class Runner
@@ -15,7 +16,7 @@ module GraphQL
           h[query] = InputValues.new(query, self)
         end.compare_by_identity
 
-        @runtime_directives = nil
+        @runtime_directives = nil #: Hash[String, singleton(GraphQL::Schema::Directive)]?
         @schema.directives.each do |name, dir_class|
           if dir_class.runtime? && name != "include" && name != "skip"
             @runtime_directives ||= {}
@@ -54,7 +55,12 @@ module GraphQL
 
       attr_reader :schema, :variables, :dataloader, :resolves_lazies, :authorizes, :static_type_at, :runtime_type_at, :finalizers, :input_values
 
-      # @return [void]
+      # **Returns**
+      #
+      # - `void`
+      #
+      # :call-seq:
+      #   add_finalizer(query, result_value, key, finalizer) -> void
       def add_finalizer(query, result_value, key, finalizer)
         @finalizers ||= {}.compare_by_identity
         f_for_query = @finalizers[query] ||= {}.compare_by_identity
@@ -72,6 +78,7 @@ module GraphQL
       end
 
       def execute
+        previous_multiplex = Fiber[:__graphql_current_multiplex]
         Fiber[:__graphql_current_multiplex] = @multiplex
         isolated_steps = [[]]
         trace = @multiplex.current_trace
@@ -86,10 +93,10 @@ module GraphQL
           @schema.analysis_engine.analyze_multiplex(@multiplex, multiplex_analyzers)
           trace.end_analyze_multiplex(@multiplex, multiplex_analyzers)
 
-          results = []
+          results = {}.compare_by_identity
           queries.each do |query|
             if query.validate && !query.valid?
-              results << {
+              results[query] = {
                 "errors" => query.static_errors.map(&:to_h)
               }
               next
@@ -124,8 +131,8 @@ module GraphQL
             end
           end
 
-          queries.each_with_index.map do |query, idx|
-            result = results[idx]
+          queries.map do |query|
+            result = results[query]
 
             fin_result = if (!@finalizers&.key?(query) && query.context.errors.empty?) || !query.valid?
               result
@@ -154,9 +161,19 @@ module GraphQL
             end
             query.result
           end
+        rescue SystemStackError => err
+          queries.map do |query|
+            @schema.query_stack_error(query, err)
+            query.result_values ||= { "errors" => query.context.errors.map(&:to_h) }
+            query.result
+          end
+        rescue Exception
+          # Assign values here so that the query's `@executed` becomes true
+          queries.map { |q| q.result_values ||= {} }
+          raise
         end
       ensure
-        Fiber[:__graphql_current_multiplex] = nil
+        Fiber[:__graphql_current_multiplex] = previous_multiplex
       end
 
       def gather_selections(type_defn, ast_selections, selections_step, query, all_selections, prototype_result, into:)
@@ -255,17 +272,17 @@ module GraphQL
             end
 
             if !auth_check
-              results << {}
+              results[query] = {}
               return
             end
           end
 
-          results << { "data" => data }
+          results[query] = { "data" => data }
           objects = [root_value]
           query.current_trace.objects(root_type, objects, query.context)
 
           if query.is_a?(GraphQL::Query) && uses_runtime_directives && (query_dirs = selected_operation.directives).any? # rubocop:disable Development/NoneWithoutBlockCop
-            continue_execution = true
+            continue_execution = true #: bool
             query_dirs.each do |dir_node|
               dir_defn = runtime_directives[dir_node.name] || raise(GraphQL::Error, "No directive definition found for: #{dir_node.name.inspect}")
               dir_args, errors = input_values[query].argument_values(dir_defn, dir_node.arguments, nil) # rubocop:disable Development/ContextIsPassedCop
@@ -354,7 +371,7 @@ module GraphQL
           objects = [root_value]
           query.current_trace.objects(resolved_type, objects, query.context)
           runtime_type_at[data] = resolved_type
-          results << { "data" => data }
+          results[query] = { "data" => data }
           isolated_steps[0] << SelectionsStep.new(
             parent_type: resolved_type,
             field_resolve_step: nil,
@@ -369,10 +386,10 @@ module GraphQL
           inner_type = root_type.unwrap
           case inner_type.kind.name
           when "SCALAR", "ENUM"
-            results << run_isolated_scalar(root_type, query)
+            results[query] = run_isolated_scalar(root_type, query)
           else
             list_result = Array.new(root_value.size) { Hash.new.compare_by_identity }
-            results << { "data" => list_result }
+            results[query] = { "data" => list_result }
             isolated_steps[0] << SelectionsStep.new(
               parent_type: inner_type,
               field_resolve_step: nil,
@@ -385,7 +402,7 @@ module GraphQL
             )
           end
         when "SCALAR", "ENUM"
-          results << run_isolated_scalar(root_type, query)
+          results[query] = run_isolated_scalar(root_type, query)
         else
           raise "Unhandled root type kind: #{root_type.kind.name.inspect}"
         end
@@ -418,7 +435,7 @@ module GraphQL
         key = dummy_path.pop
         is_from_array = key.is_a?(Integer)
 
-        if lazy?(value)
+        if resolves_lazies && lazy?(value)
           value = @schema.sync_lazy(value)
         end
         selections = partial.ast_nodes

data/lib/graphql/execution/selections_step.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   module Execution
     class SelectionsStep
@@ -35,10 +36,10 @@ module GraphQL
         l = @all_selections.length
         while i < l
           grouped_selections = @all_selections[i]
-          selections_prototype_result = @all_selections[i + 1]
+          selections_prototype_result = @all_selections[i + 1] #: as !nil
           if (directives_owner = grouped_selections.delete(:__node))
             directives = directives_owner.directives
-            continue_execution = true
+            continue_execution = true #: bool
             directives.each do |dir_node|
               dir_defn = @runner.runtime_directives[dir_node.name]
               if dir_defn # not present for `skip` or `include`

data/lib/graphql/execution.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 require "graphql/execution/directive_checks"
 require "graphql/execution/next"
 require "graphql/execution/interpreter"
@@ -9,8 +10,7 @@ require "graphql/execution/errors"
 
 module GraphQL
   module Execution
-    # @api private
-    class Skip < GraphQL::RuntimeError
+    class Skip < GraphQL::RuntimeError # :nodoc:
       attr_accessor :path
       def ast_nodes=(_ignored); end
 

data/lib/graphql/execution_error.rb

@@ -1,21 +1,25 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
-  # If a field's resolve function returns a {ExecutionError},
+  # If a field's resolve function returns an [ExecutionError](rdoc-ref:GraphQL::ExecutionError),
   # the error will be inserted into the response's `"errors"` key
   # and the field will resolve to `nil`.
   class ExecutionError < GraphQL::RuntimeError
-    # @return [String] an array describing the JSON-path into the execution
-    # response which corresponds to this error.
+    # **Returns**
+    #
+    # - `String` — an array describing the JSON-path into the execution response which corresponds to this error.
     attr_accessor :path
 
-    # @return [Hash] Optional data for error objects
-    # @deprecated Use `extensions` instead of `options`. The GraphQL spec
-    # recommends that any custom entries in an error be under the
-    # `extensions` key.
+    # **Deprecated:** Use `extensions` instead of `options`. The GraphQL spec recommends that any custom entries in an error be under the `extensions` key.
+    #
+    # **Returns**
+    #
+    # - `Hash` — Optional data for error objects
     attr_accessor :options
 
-    # @return [Hash] Optional custom data for error objects which will be added
-    # under the `extensions` key.
+    # **Returns**
+    #
+    # - `Hash` — Optional custom data for error objects which will be added under the `extensions` key.
     attr_accessor :extensions
 
     def initialize(message, ast_node: nil, ast_nodes: nil, options: nil, extensions: nil)
@@ -38,7 +42,12 @@ module GraphQL
       end
     end
 
-    # @return [Hash] An entry for the response's "errors" key
+    # **Returns**
+    #
+    # - `Hash` — An entry for the response's "errors" key
+    #
+    # :call-seq:
+    #   to_h() -> Hash
     def to_h
       hash = {
         "message" => message,