graphql 2.6.9 → 2.6.14

data/lib/graphql/query/partial.rb

@@ -1,24 +1,30 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Query
-    # This class is _like_ a {GraphQL::Query}, except it can run on an arbitrary path within a query string.
+    # This class is _like_ a [GraphQL::Query](rdoc-ref:GraphQL::Query), except it can run on an arbitrary path within a query string.
     #
-    # It depends on a "parent" {Query}.
+    # It depends on a "parent" [Query](rdoc-ref:Query).
     #
     # During execution, it calls query-related tracing hooks but passes itself as `query:`.
     #
-    # The {Partial} will use your {Schema.resolve_type} hook to find the right GraphQL type to use for
+    # The [Partial](rdoc-ref:Partial) will use your [Schema.resolve_type](rdoc-ref:Schema.resolve_type) hook to find the right GraphQL type to use for
     # `object` in some cases.
     #
-    # @see Query#run_partials Run via {Query#run_partials}
+    # Run via [Query#run_partials](rdoc-ref:Query#run_partials).
     class Partial
       include Query::Runnable
 
-      # @param path [Array<String, Integer>] A path in `query.query_string` to start executing from
-      # @param object [Object] A starting object for execution
-      # @param query [GraphQL::Query] A full query instance that this partial is based on. Caches are shared.
-      # @param context [Hash] Extra context values to merge into `query.context`, if provided
-      # @param fragment_node [GraphQL::Language::Nodes::InlineFragment, GraphQL::Language::Nodes::FragmentDefinition]
+      # **Parameters**
+      #
+      # - `path` (`Array<String, Integer>`) — A path in `query.query_string` to start executing from
+      # - `object` (`Object`) — A starting object for execution
+      # - `query` (`GraphQL::Query`) — A full query instance that this partial is based on. Caches are shared.
+      # - `context` (`Hash`) — Extra context values to merge into `query.context`, if provided
+      # - `fragment_node` (`GraphQL::Language::Nodes::InlineFragment, GraphQL::Language::Nodes::FragmentDefinition`)
+      #
+      # :call-seq:
+      #   initialize(Array[String | Integer] path:, Object object:, GraphQL::Query query:, Hash context:, GraphQL::Language::Nodes::InlineFragment | GraphQL::Language::Nodes::FragmentDefinition fragment_node:, type:)
       def initialize(path: nil, object:, query:, context: nil, fragment_node: nil, type: nil)
         @path = path
         @object = object
@@ -65,7 +71,12 @@ module GraphQL
           @query.path
         end
 
-        # @return [GraphQL::Query::Partial]
+        # **Returns**
+        #
+        # - `GraphQL::Query::Partial`
+        #
+        # :call-seq:
+        #   partial() -> GraphQL::Query::Partial
         def partial
           @query
         end
@@ -138,9 +149,9 @@ module GraphQL
       private
 
       def set_type_info_from_path
-        selections = [@query.selected_operation]
+        selections = [@query.selected_operation] #: Array[GraphQL::Language::Nodes::OperationDefinition | GraphQL::Language::Nodes::Field]
         type = @query.root_type
-        field_defn = nil
+        field_defn = nil #: GraphQL::Schema::Field?
 
         @path.each do |name_in_doc|
           if name_in_doc.is_a?(Integer)
@@ -152,9 +163,9 @@ module GraphQL
             end
           end
 
-          next_selections = []
+          next_selections = [] #: Array[GraphQL::Language::Nodes::Field]
           selections.each do |selection|
-            selections_to_check = []
+            selections_to_check = [] #: Array[GraphQL::Language::Nodes::Field | GraphQL::Language::Nodes::InlineFragment | GraphQL::Language::Nodes::FragmentSpread]
             selections_to_check.concat(selection.selections)
             while (sel = selections_to_check.shift)
               case sel
@@ -168,7 +179,7 @@ module GraphQL
                   next_selections << sel
                 end
               else
-                raise "Unexpected selection in partial path: #{sel.class}, #{sel.inspect}"
+                raise "Unexpected selection in partial path: #{sel.class}, #{sel.inspect}" #: absurd(sel)
               end
             end
           end
@@ -176,7 +187,8 @@ module GraphQL
           if next_selections.empty?
             raise ArgumentError, "Path `#{@path.inspect}` is not present in this query. `#{name_in_doc.inspect}` was not found. Try a different path or rewrite the query to include it."
           end
-          field_name = next_selections.first.name
+          first_selection = next_selections.first #: as !nil
+          field_name = first_selection.name
           field_defn = @schema.get_field(type, field_name, @query.context) || raise("Invariant: no field called #{field_name} on #{type.graphql_name}")
           type = field_defn.type
           if type.non_null?

data/lib/graphql/query/result.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
   class Query
-    # A result from {Schema#execute}.
+    # A result from [Schema.execute](rdoc-ref:GraphQL::Schema.execute).
     # It provides the requested data and
-    # access to the {Query} and {Query::Context}.
+    # access to the [Query](rdoc-ref:GraphQL::Query) and [Query::Context](rdoc-ref:GraphQL::Query::Context).
     class Result
       extend Forwardable
 
@@ -13,10 +14,14 @@ module GraphQL
         @to_h = values
       end
 
-      # @return [GraphQL::Query] The query that was executed
+      # **Returns**
+      #
+      # - `GraphQL::Query` — The query that was executed
       attr_reader :query
 
-      # @return [Hash] The resulting hash of "data" and/or "errors"
+      # **Returns**
+      #
+      # - `Hash` — The resulting hash of "data" and/or "errors"
       attr_reader :to_h
 
       def_delegators :@query, :context, :mutation?, :query?, :subscription?
@@ -47,7 +52,12 @@ module GraphQL
       #
       # (The query is ignored for comparing result equality.)
       #
-      # @return [Boolean]
+      # **Returns**
+      #
+      # - `Boolean`
+      #
+      # :call-seq:
+      #   ==(other) -> bool
       def ==(other)
         case other
         when Hash

data/lib/graphql/query/validation_pipeline.rb

@@ -1,19 +1,19 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Query
     # Contain the validation pipeline and expose the results.
     #
-    # 0. Checks in {Query#initialize}:
+    # 0. Checks in the [GraphQL::Query](rdoc-ref:GraphQL::Query) constructor:
     #   - Rescue a ParseError, halt if there is one
     #   - Check for selected operation, halt if not found
     # 1. Validate the AST, halt if errors
     # 2. Validate the variables, halt if errors
     # 3. Run query analyzers, halt if errors
     #
-    # {#valid?} is false if any of the above checks halted the pipeline.
+    # [valid?](rdoc-ref:#valid?) is false if any of the above checks halted the pipeline.
     #
-    # @api private
-    class ValidationPipeline
+    class ValidationPipeline # :nodoc:
       attr_reader :max_depth, :max_complexity, :validate_timeout_remaining
 
       def initialize(query:, parse_error:, operation_name_error:, max_depth:, max_complexity:)
@@ -28,13 +28,23 @@ module GraphQL
         @has_validated = false
       end
 
-      # @return [Boolean] does this query have errors that should prevent it from running?
+      # **Returns**
+      #
+      # - `Boolean` — does this query have errors that should prevent it from running?
+      #
+      # :call-seq:
+      #   valid?() -> bool
       def valid?
         ensure_has_validated
         @valid
       end
 
-      # @return [Array<GraphQL::StaticValidation::Error, GraphQL::Query::VariableValidationError>] Static validation errors for the query string
+      # **Returns**
+      #
+      # - `Array<GraphQL::StaticValidation::Error, GraphQL::Query::VariableValidationError>` — Static validation errors for the query string
+      #
+      # :call-seq:
+      #   validation_errors() -> Array[GraphQL::StaticValidation::Error | GraphQL::Query::VariableValidationError]
       def validation_errors
         ensure_has_validated
         @validation_errors

data/lib/graphql/query/variable_validation_error.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Query
     class VariableValidationError < GraphQL::ExecutionError
@@ -22,7 +23,7 @@ module GraphQL
         # It is possible there are other extension items in this error, so handle
         # a one level deep merge explicitly. However beyond that only show the
         # latest value and problems.
-        super.merge({ "extensions" => { "value" => value, "problems" => validation_result.problems }}) do |key, oldValue, newValue|
+        super.merge({ "extensions" => { "value" => value_for_extensions, "problems" => validation_result.problems }}) do |key, oldValue, newValue|
           if oldValue.respond_to?(:merge)
             oldValue.merge(newValue)
           else
@@ -33,6 +34,21 @@ module GraphQL
 
       private
 
+      def value_for_extensions(value = @value)
+        case value
+        when Array
+          value.map { |item| value_for_extensions(item) }
+        when Hash
+          value.each_with_object({}) do |(key, item), result|
+            result[key] = value_for_extensions(item)
+          end
+        when Float
+          value.finite? ? value : value.to_s
+        else
+          value
+        end
+      end
+
       def problem_fields
         @problem_fields ||= @validation_result
           .problems

data/lib/graphql/query/variables.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
+# typed: true
 module GraphQL
   class Query
     # Read-only access to query variables, applying default values if needed.
     class Variables
       extend Forwardable
 
-      # @return [Array<GraphQL::Query::VariableValidationError>]  Any errors encountered when parsing the provided variables and literal values
+      # **Returns**
+      #
+      # - `Array<GraphQL::Query::VariableValidationError>` — Any errors encountered when parsing the provided variables and literal values
       attr_reader :errors
 
       attr_reader :context
@@ -35,7 +38,11 @@ module GraphQL
             value_was_provided =  @provided_variables.key?(variable_name)
             max_errors = schema.validate_max_errors - @errors.count if schema.validate_max_errors
             begin
-              validation_result = variable_type.validate_input(provided_value, ctx, max_errors: max_errors)
+              validation_result = if value_was_provided || default_value.nil?
+                variable_type.validate_input(provided_value, ctx, max_errors: max_errors)
+              else
+                GraphQL::Query::InputValidationResult::VALID
+              end
               if validation_result.valid?
                 if value_was_provided
                   # Add the variable if a value was provided

data/lib/graphql/query.rb

@@ -1,7 +1,42 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
-  # A combination of query string and {Schema} instance which can be reduced to a {#result}.
+  # A combination of query string and [Schema](rdoc-ref:GraphQL::Schema) instance which can be reduced to a [result](rdoc-ref:#result).
+  #
+  # The API-specific portions of `guides/queries/executing_queries.md` were
+  # migrated to `Schema#execute`, `Schema#multiplex`, and this initializer.
+  # Those APIs accept query strings or parsed documents, variables, context,
+  # root values, operation names, validation controls, and depth/complexity
+  # limits. The guide remains a standalone execution tutorial.
+  #
+  # ## API-specific portions
+  #
+  # [GraphQL::Schema.execute](rdoc-ref:GraphQL::Schema.execute) runs one query
+  # and [GraphQL::Schema.multiplex](rdoc-ref:GraphQL::Schema.multiplex) runs
+  # several queries with shared multiplex-level context. Both delegate to this
+  # class, so the following options have the same meaning in each API:
+  #
+  # - `query` or the positional query string is a GraphQL document to parse.
+  # - `document:` accepts an already-parsed
+  #   [GraphQL::Language::Nodes::Document](rdoc-ref:GraphQL::Language::Nodes::Document);
+  #   pass one or the other, not both.
+  # - `variables:` is a `Hash` of values for `$`-named variables. Keys omit the
+  #   leading `$`; values may contain nested input objects.
+  # - `context:` contains application values made available to field resolvers,
+  #   schema hooks, and [Query::Context](rdoc-ref:GraphQL::Query::Context).
+  # - `root_value:` is passed as `obj` to root-level fields.
+  # - `operation_name:` selects which named operation to execute when a document
+  #   contains more than one operation.
+  # - `validate: false` skips static validation. Use this only when the document
+  #   has already been validated; execution of an invalid document is undefined.
+  # - `max_depth:` and `max_complexity:` override the corresponding schema limits
+  #   for this query. `nil` uses the schema configuration.
+  #
+  # The [executing queries guide](/queries/executing_queries) keeps examples for
+  # variables, context, scoped context, and root values. This class and the
+  # `Schema#execute`/`Schema#multiplex` method comments are the source of truth
+  # for option names, defaults, and execution behavior.
   class Query
     extend Autoload
     include Tracing::Traceable
@@ -17,7 +52,7 @@ module GraphQL
     autoload :VariableValidationError, "graphql/query/variable_validation_error"
     autoload :ValidationPipeline, "graphql/query/validation_pipeline"
 
-    # Code shared with {Partial}
+    # Code shared with [Partial](rdoc-ref:GraphQL::Query::Partial)
     module Runnable
       def after_lazy(value, &block)
         if !defined?(@runtime_instance)
@@ -32,10 +67,19 @@ module GraphQL
       end
 
       # Node-level cache for calculating arguments. Used during execution and query analysis.
-      # @param ast_node [GraphQL::Language::Nodes::AbstractNode]
-      # @param definition [GraphQL::Schema::Field]
-      # @param parent_object [GraphQL::Schema::Object]
-      # @return [Hash{Symbol => Object}]
+      #
+      # **Parameters**
+      #
+      # - `ast_node` (`GraphQL::Language::Nodes::AbstractNode`)
+      # - `definition` (`GraphQL::Schema::Field`)
+      # - `parent_object` (`GraphQL::Schema::Object`)
+      #
+      # **Returns**
+      #
+      # - `Hash{Symbol => Object}`
+      #
+      # :call-seq:
+      #   arguments_for(GraphQL::Language::Nodes::AbstractNode ast_node, GraphQL::Schema::Field definition, GraphQL::Schema::Object parent_object:) -> Hash[Symbol, Object]
       def arguments_for(ast_node, definition, parent_object: nil)
         arguments_cache.fetch(ast_node, definition, parent_object)
       end
@@ -44,8 +88,7 @@ module GraphQL
         @arguments_cache ||= Execution::Interpreter::ArgumentsCache.new(self)
       end
 
-      # @api private
-      def handle_or_reraise(err, **kwargs)
+      def handle_or_reraise(err, **kwargs) # :nodoc:
         @schema.handle_or_reraise(context, err, **kwargs)
       end
     end
@@ -67,13 +110,22 @@ module GraphQL
     # The value for root types
     attr_accessor :root_value
 
-    # @return [nil, String] The operation name provided by client or the one inferred from the document. Used to determine which operation to run.
+    # **Returns**
+    #
+    # - `nil, String` — The operation name provided by client or the one inferred from the document. Used to determine which operation to run.
     attr_accessor :operation_name
 
-    # @return [Boolean] if false, static validation is skipped (execution behavior for invalid queries is undefined)
+    # **Returns**
+    #
+    # - `Boolean` — if false, static validation is skipped (execution behavior for invalid queries is undefined)
     attr_reader :validate
 
-    # @param new_validate [Boolean] if false, static validation is skipped. This can't be reasssigned after validation.
+    # **Parameters**
+    #
+    # - `new_validate` (`Boolean`) — if false, static validation is skipped. This can't be reasssigned after validation.
+    #
+    # :call-seq:
+    #   validate=(bool new_validate)
     def validate=(new_validate)
       if defined?(@validation_pipeline) && @validation_pipeline && @validation_pipeline.has_validated?
         raise ArgumentError, "Can't reassign Query#validate= after validation has run, remove this assignment."
@@ -82,10 +134,17 @@ module GraphQL
       end
     end
 
-    # @return [GraphQL::StaticValidation::Validator] if present, the query will validate with these rules.
+    # **Returns**
+    #
+    # - `GraphQL::StaticValidation::Validator` — if present, the query will validate with these rules.
     attr_reader :static_validator
 
-    # @param new_validator [GraphQL::StaticValidation::Validator] if present, the query will validate with these rules. This can't be reasssigned after validation.
+    # **Parameters**
+    #
+    # - `new_validator` (`GraphQL::StaticValidation::Validator`) — if present, the query will validate with these rules. This can't be reasssigned after validation.
+    #
+    # :call-seq:
+    #   static_validator=(GraphQL::StaticValidation::Validator new_validator)
     def static_validator=(new_validator)
       if defined?(@validation_pipeline) && @validation_pipeline && @validation_pipeline.has_validated?
         raise ArgumentError, "Can't reassign Query#static_validator= after validation has run, remove this assignment."
@@ -98,7 +157,12 @@ module GraphQL
 
     attr_writer :query_string
 
-    # @return [GraphQL::Language::Nodes::Document]
+    # **Returns**
+    #
+    # - `GraphQL::Language::Nodes::Document`
+    #
+    # :call-seq:
+    #   document() -> GraphQL::Language::Nodes::Document
     def document
       # It's ok if this hasn't been assigned yet
       if @query_string || @document
@@ -112,27 +176,40 @@ module GraphQL
       "query ..."
     end
 
-    # @return [String, nil] The name of the operation to run (may be inferred)
+    # **Returns**
+    #
+    # - `String, nil` — The name of the operation to run (may be inferred)
+    #
+    # :call-seq:
+    #   selected_operation_name() -> String | nil
     def selected_operation_name
       return nil unless selected_operation
       selected_operation.name
     end
 
-    # @return [String, nil] the triggered event, if this query is a subscription update
+    # **Returns**
+    #
+    # - `String, nil` — the triggered event, if this query is a subscription update
     attr_reader :subscription_topic
 
     attr_reader :tracers
 
     # Prepare query `query_string` on `schema`
-    # @param schema [GraphQL::Schema]
-    # @param query_string [String]
-    # @param context [#[]] an arbitrary hash of values which you can access in {GraphQL::Field#resolve}
-    # @param variables [Hash] values for `$variables` in the query
-    # @param operation_name [String] if the query string contains many operations, this is the one which should be executed
-    # @param root_value [Object] the object used to resolve fields on the root type
-    # @param max_depth [Numeric] the maximum number of nested selections allowed for this query (falls back to schema-level value)
-    # @param max_complexity [Numeric] the maximum field complexity for this query (falls back to schema-level value)
-    # @param visibility_profile [Symbol] Another way to assign `context[:visibility_profile]`
+    #
+    # **Parameters**
+    #
+    # - `schema` (`GraphQL::Schema`)
+    # - `query_string` (`String`)
+    # - `context` (`#[]`) — an arbitrary hash of values which you can access in [Schema::Field#resolve](rdoc-ref:GraphQL::Schema::Field#resolve)
+    # - `variables` (`Hash`) — values for `$variables` in the query
+    # - `operation_name` (`String`) — if the query string contains many operations, this is the one which should be executed
+    # - `root_value` (`Object`) — the object used to resolve fields on the root type
+    # - `max_depth` (`Numeric`) — the maximum number of nested selections allowed for this query (falls back to schema-level value)
+    # - `max_complexity` (`Numeric`) — the maximum field complexity for this query (falls back to schema-level value)
+    # - `visibility_profile` (`Symbol`) — Another way to assign `context[:visibility_profile]`
+    #
+    # :call-seq:
+    #   initialize(GraphQL::Schema schema, String query_string, query:, document:, #[] context:, Hash variables:, multiplex:, validate:, static_validator:, Symbol visibility_profile:, subscription_topic:, String operation_name:, Object root_value:, Numeric max_depth:, Numeric max_complexity:, warden:, use_visibility_profile:)
     def initialize(schema, query_string = nil, query: nil, document: nil, context: nil, variables: nil, multiplex: nil, validate: true, static_validator: nil, visibility_profile: nil, subscription_topic: nil, operation_name: nil, root_value: nil, max_depth: schema.max_depth, max_complexity: schema.max_complexity, warden: nil, use_visibility_profile: nil)
       # Even if `variables: nil` is passed, use an empty hash for simpler logic
       variables ||= {}
@@ -216,12 +293,19 @@ module GraphQL
       @query_string ||= (document ? document.to_query_string : nil)
     end
 
-    # @return [Symbol, nil]
+    # **Returns**
+    #
+    # - `Symbol, nil`
     attr_reader :visibility_profile
 
     attr_accessor :multiplex
 
-    # @return [GraphQL::Tracing::Trace]
+    # **Returns**
+    #
+    # - `GraphQL::Tracing::Trace`
+    #
+    # :call-seq:
+    #   current_trace() -> GraphQL::Tracing::Trace
     def current_trace
       @current_trace ||= context[:trace] || (multiplex ? multiplex.current_trace : schema.new_trace(multiplex: multiplex, query: self))
     end
@@ -231,7 +315,13 @@ module GraphQL
     end
 
     # A lookahead for the root selections of this query
-    # @return [GraphQL::Execution::Lookahead]
+    #
+    # **Returns**
+    #
+    # - `GraphQL::Execution::Lookahead`
+    #
+    # :call-seq:
+    #   lookahead() -> GraphQL::Execution::Lookahead
     def lookahead
       @lookahead ||= begin
         if selected_operation.nil?
@@ -242,8 +332,7 @@ module GraphQL
       end
     end
 
-    # @api private
-    def result_values=(result_hash)
+    def result_values=(result_hash) # :nodoc:
       if @executed
         raise "Invariant: Can't reassign result"
       else
@@ -252,8 +341,7 @@ module GraphQL
       end
     end
 
-    # @api private
-    attr_reader :result_values
+    attr_reader :result_values # :nodoc:
 
     def fragments
       with_prepared_ast { @fragments }
@@ -272,10 +360,19 @@ module GraphQL
     # where the path references a field in the AST and the object will be treated
     # as the return value from that field. Subfields of the field named by `path`
     # will be executed with `object` as the starting point
-    # @param partials_hashes [Array<Hash{Symbol => Object}>] Hashes with `path:` and `object:` keys
-    # @return [Array<GraphQL::Query::Result>]
+    #
+    # **Parameters**
+    #
+    # - `partials_hashes` (`Array<Hash{Symbol => Object}>`) — Hashes with `path:` and `object:` keys
+    #
+    # **Returns**
+    #
+    # - `Array<GraphQL::Query::Result>`
+    #
+    # :call-seq:
+    #   run_partials(Array[Hash[Symbol, Object]] partials_hashes) -> Array[GraphQL::Query::Result]
     def run_partials(partials_hashes)
-      partials = partials_hashes.map { |partial_options| Partial.new(query: self, **partial_options) }
+      partials = partials_hashes.map { |partial_options| Partial.new(**partial_options, query: self) }
       if context[:__graphql_execute_next]
         Execution::Next.run_all(@schema, partials, context: @context)
       else
@@ -284,10 +381,17 @@ module GraphQL
     end
 
     # Get the result for this query, executing it once
-    # @return [GraphQL::Query::Result] A Hash-like GraphQL response, with `"data"` and/or `"errors"` keys
+    #
+    # **Returns**
+    #
+    # - `GraphQL::Query::Result` — A Hash-like GraphQL response, with `"data"` and/or `"errors"` keys
+    #
+    # :call-seq:
+    #   result() -> GraphQL::Query::Result
     def result
       if !@executed
-        Execution::Interpreter.run_all(@schema, [self], context: @context)
+        execution_engine = @schema.default_execution_next ? Execution::Next : Execution::Interpreter
+        execution_engine.run_all(@schema, [self], context: @context)
       end
       @result ||= Query::Result.new(query: self, values: @result_values)
     end
@@ -302,7 +406,13 @@ module GraphQL
 
     # This is the operation to run for this query.
     # If more than one operation is present, it must be named at runtime.
-    # @return [GraphQL::Language::Nodes::OperationDefinition, nil]
+    #
+    # **Returns**
+    #
+    # - `GraphQL::Language::Nodes::OperationDefinition, nil`
+    #
+    # :call-seq:
+    #   selected_operation() -> GraphQL::Language::Nodes::OperationDefinition | nil
     def selected_operation
       with_prepared_ast { @selected_operation }
     end
@@ -310,9 +420,14 @@ module GraphQL
     # Determine the values for variables of this query, using default values
     # if a value isn't provided at runtime.
     #
-    # If some variable is invalid, errors are added to {#validation_errors}.
+    # If some variable is invalid, errors are added to the query's validation errors.
+    #
+    # **Returns**
+    #
+    # - `GraphQL::Query::Variables` — Variables to apply to this query
     #
-    # @return [GraphQL::Query::Variables] Variables to apply to this query
+    # :call-seq:
+    #   variables() -> GraphQL::Query::Variables
     def variables
       @variables ||= begin
         with_prepared_ast {
@@ -328,7 +443,13 @@ module GraphQL
     # A version of the given query string, with:
     # - Variables inlined to the query
     # - Strings replaced with `<REDACTED>`
-    # @return [String, nil] Returns nil if the query is invalid.
+    #
+    # **Returns**
+    #
+    # - `String, nil` — Returns nil if the query is invalid.
+    #
+    # :call-seq:
+    #   sanitized_query_string(inline_variables:) -> String | nil
     def sanitized_query_string(inline_variables: true)
       with_prepared_ast {
         schema.sanitized_printer.new(self, inline_variables: inline_variables).sanitized_query_string
@@ -344,19 +465,34 @@ module GraphQL
     #
     # This fingerprint can be used to track runs of the same operation-variables combination over time.
     #
-    # @see operation_fingerprint
-    # @see variables_fingerprint
-    # @return [String] An opaque hash identifying this operation-variables combination
+    # See `operation_fingerprint` and `variables_fingerprint` for the components.
+    #
+    # **Returns**
+    #
+    # - `String` — An opaque hash identifying this operation-variables combination
+    #
+    # :call-seq:
+    #   fingerprint() -> String
     def fingerprint
       @fingerprint ||= "#{operation_fingerprint}/#{variables_fingerprint}"
     end
 
-    # @return [String] An opaque hash for identifying this query's given query string and selected operation
+    # **Returns**
+    #
+    # - `String` — An opaque hash for identifying this query's given query string and selected operation
+    #
+    # :call-seq:
+    #   operation_fingerprint() -> String
     def operation_fingerprint
       @operation_fingerprint ||= "#{selected_operation_name || "anonymous"}/#{Fingerprint.generate(query_string || "")}"
     end
 
-    # @return [String] An opaque hash for identifying this query's given a variable values (not including defaults)
+    # **Returns**
+    #
+    # - `String` — An opaque hash for identifying this query's given a variable values (not including defaults)
+    #
+    # :call-seq:
+    #   variables_fingerprint() -> String
     def variables_fingerprint
       @variables_fingerprint ||= "#{provided_variables.size}/#{Fingerprint.generate(provided_variables.to_json)}"
     end
@@ -410,10 +546,19 @@ module GraphQL
       @visibility_profile || warden.visibility_profile
     end
 
-    # @param abstract_type [GraphQL::UnionType, GraphQL::InterfaceType]
-    # @param value [Object] Any runtime value
-    # @return [GraphQL::ObjectType, nil] The runtime type of `value` from {Schema#resolve_type}
-    # @see {#possible_types} to apply filtering from `only` / `except`
+    # See [possible_types](rdoc-ref:#possible_types) to apply filtering from `only` / `except`
+    #
+    # **Parameters**
+    #
+    # - `abstract_type` (`GraphQL::UnionType, GraphQL::InterfaceType`)
+    # - `value` (`Object`) — Any runtime value
+    #
+    # **Returns**
+    #
+    # - `GraphQL::ObjectType, nil` — The runtime type of `value` from [Schema.resolve_type](rdoc-ref:GraphQL::Schema::resolve_type)
+    #
+    # :call-seq:
+    #   resolve_type(GraphQL::UnionType | GraphQL::InterfaceType abstract_type, Object value) -> GraphQL::ObjectType | nil
     def resolve_type(abstract_type, value = NOT_CONFIGURED)
       if value.is_a?(Symbol) && value == NOT_CONFIGURED
         # Old method signature