graphql 2.6.12 → 2.6.13

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,7 +381,13 @@ 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_engine = @schema.default_execution_next ? Execution::Next : Execution::Interpreter
@@ -303,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
@@ -311,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 {
@@ -329,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
@@ -345,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
@@ -411,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

data/lib/graphql/railtie.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
+# typed: true
 
 module GraphQL
-  # Support {GraphQL::Parser::Cache} and {GraphQL.eager_load!}
+  # Support [GraphQL::Language::Cache](rdoc-ref:GraphQL::Language::Cache) and [GraphQL.eager_load!](rdoc-ref:GraphQL.eager_load!)
   #
-  # @example Enable the parser cache with default directory
+  # **Examples**
   #
-  #   config.graphql.parser_cache = true
+  # **Example: Enable the parser cache with default directory**
   #
+  # ```ruby
+  # config.graphql.parser_cache = true
+  # ```
   class Railtie < Rails::Railtie
     config.graphql = ActiveSupport::OrderedOptions.new
     config.graphql.parser_cache = false

data/lib/graphql/rake_task/validate.rb

@@ -1,21 +1,83 @@
 # frozen_string_literal: true
+# typed: true
+require "digest/sha2"
+require "net/http"
+require "erb"
 
 module GraphQL
   class RakeTask
     extend Rake::DSL
 
+    # Helpers for `graphql:pro:validate`.
+    # Credentials are never passed to a subprocess, so they can't leak into the process list or logs.
+    module Validate
+      CREDENTIALS_PATTERN = /\A[a-z0-9]{11}:[a-z0-9]{11}\z/
+      DIGEST_PATTERN = /\A\h{128}\z/
+
+      module_function
+
+      # Returns a normalized version string, or `nil` if `version` isn't a valid gem version.
+      def normalize_version(version)
+        # `Gem::Version.correct?` accepts `nil` and `""`, so check those first
+        if !version.is_a?(String) || version.strip.empty? || !Gem::Version.correct?(version)
+          nil
+        else
+          # Strips surrounding whitespace, leaving only `[0-9a-zA-Z.]`
+          Gem::Version.new(version).to_s
+        end
+      end
+
+      # Returns `user:pass` for gems.graphql.pro, or `nil` if it isn't configured.
+      def credentials
+        creds = if defined?(Bundler) && Bundler.respond_to?(:settings)
+          Bundler.settings["gems.graphql.pro"]
+        end
+        if creds.nil?
+          # Array form doesn't use a shell, and no secrets are in the arguments
+          output = IO.popen(["bundle", "config", "get", "gems.graphql.pro", "--parseable"], err: File::NULL, &:read)
+          creds = output[/[a-z0-9]{11}:[a-z0-9]{11}/]
+        end
+        creds = creds&.strip
+        creds && creds.match?(CREDENTIALS_PATTERN) ? creds : nil
+      rescue SystemCallError
+        nil
+      end
+
+      # Returns the SHA512 hex digest of the downloaded gem, or `nil` if the download failed.
+      def fetch_gem_digest(version, creds)
+        user, pass = creds.split(":", 2)
+        uri = URI.parse("https://gems.graphql.pro/gems/graphql-pro-#{version}.gem")
+        req = Net::HTTP::Get.new(uri)
+        req.basic_auth(user, pass)
+        res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
+        res.is_a?(Net::HTTPSuccess) ? Digest::SHA512.hexdigest(res.body.to_s) : nil
+      end
+
+      # Returns the published digest at `uri`, or `nil` if it couldn't be fetched.
+      def fetch_published_digest(uri)
+        res = Net::HTTP.get_response(uri)
+        return nil unless res.is_a?(Net::HTTPSuccess)
+        # Remove final newline from .txt file
+        digest = res.body.to_s.strip
+        digest.match?(DIGEST_PATTERN) ? digest : nil
+      end
+    end
+
     desc "Get the checksum of a graphql-pro version and compare it to published versions on GitHub and graphql-ruby.org"
     task "graphql:pro:validate", [:gem_version] do |t, args|
-      version = args[:gem_version]
-      if version.nil?
+      if args[:gem_version].nil?
         raise ArgumentError, "A specific version is required, eg `rake graphql:pro:validate[1.12.0]`"
       end
+      version = Validate.normalize_version(args[:gem_version])
+      if version.nil?
+        raise ArgumentError, "Invalid version #{args[:gem_version].inspect}, expected a gem version like `rake graphql:pro:validate[1.12.0]`"
+      end
       check = "\e[32m✓\e[0m"
       ex = "\e[31m✘\e[0m"
       puts "Validating graphql-pro v#{version}"
       puts "  - Checking for graphql-pro credentials..."
 
-      creds = `bundle config gems.graphql.pro --parseable`[/[a-z0-9]{11}:[a-z0-9]{11}/]
+      creds = Validate.credentials
       if creds.nil?
         puts "    #{ex} failed, please set with `bundle config gems.graphql.pro $MY_CREDENTIALS`"
         exit(1)
@@ -24,8 +86,8 @@ module GraphQL
       end
 
       puts "  - Fetching the gem..."
-      fetch_result = `gem fetch graphql-pro -v #{version} --source https://#{creds}@gems.graphql.pro`
-      if fetch_result.empty?
+      gem_digest = Validate.fetch_gem_digest(version, creds)
+      if gem_digest.nil?
         puts "    #{ex} failed to fetch v#{version}"
         exit(1)
       else
@@ -33,15 +95,8 @@ module GraphQL
       end
 
       puts "  - Validating digest..."
-      require "digest/sha2"
-      gem_digest = Digest::SHA512.new.hexdigest(File.read("graphql-pro-#{version}.gem"))
-      require "net/http"
-      github_uri = URI("https://raw.githubusercontent.com/rmosolgo/graphql-ruby/master/guides/pro/checksums/graphql-pro-#{version}.txt")
-      # Remove final newline from .txt file
-      github_digest = Net::HTTP.get(github_uri).chomp
-
-      docs_uri = URI("https://graphql-ruby.org/pro/checksums/graphql-pro-#{version}.txt")
-      docs_digest = Net::HTTP.get(docs_uri).chomp
+      github_digest = Validate.fetch_published_digest(URI("https://raw.githubusercontent.com/rmosolgo/graphql-ruby/master/guides/pro/checksums/graphql-pro-#{version}.txt"))
+      docs_digest = Validate.fetch_published_digest(URI("https://graphql-ruby.org/pro/checksums/graphql-pro-#{version}.txt"))
 
       if docs_digest == gem_digest && github_digest == gem_digest
         puts "    #{check} validated from GitHub"
@@ -49,11 +104,11 @@ module GraphQL
       else
         puts "    #{ex} SHA mismatch:"
         puts "      Downloaded:       #{gem_digest}"
-        puts "      GitHub:           #{github_digest}"
-        puts "      graphql-ruby.org: #{docs_digest}"
+        puts "      GitHub:           #{github_digest || "(not found)"}"
+        puts "      graphql-ruby.org: #{docs_digest || "(not found)"}"
         puts ""
         puts "      This download of graphql-pro is invalid, please open an issue:"
-        puts "      https://github.com/rmosolgo/graphql-ruby/issues/new?title=graphql-pro%20digest%20mismatch%20(#{version})"
+        puts "      https://github.com/rmosolgo/graphql-ruby/issues/new?title=#{ERB::Util.url_encode("graphql-pro digest mismatch (#{version})")}"
         exit(1)
       end
 

data/lib/graphql/rake_task.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# typed: true
 require "fileutils"
 require "rake"
 require "graphql/rake_task/validate"
@@ -11,21 +12,32 @@ module GraphQL
   #
   # Use `load_context:` and `visible?` to dump schemas under certain visibility constraints.
   #
-  # @example Dump a Schema to .graphql + .json files
-  #   require "graphql/rake_task"
-  #   GraphQL::RakeTask.new(schema_name: "MySchema")
+  # **Examples**
   #
-  #   # $ rake graphql:schema:dump
-  #   # Schema IDL dumped to ./schema.graphql
-  #   # Schema JSON dumped to ./schema.json
+  # **Example: Dump a Schema to .graphql + .json files**
   #
-  # @example Invoking the task from Ruby
-  #   require "rake"
-  #   Rake::Task["graphql:schema:dump"].invoke
+  # ```ruby
+  # require "graphql/rake_task"
+  # GraphQL::RakeTask.new(schema_name: "MySchema")
   #
-  # @example Providing arguments to build the introspection query
-  #   require "graphql/rake_task"
-  #   GraphQL::RakeTask.new(schema_name: "MySchema", include_is_one_of: true)
+  # # $ rake graphql:schema:dump
+  # # Schema IDL dumped to ./schema.graphql
+  # # Schema JSON dumped to ./schema.json
+  # ```
+  #
+  # **Example: Invoking the task from Ruby**
+  #
+  # ```ruby
+  # require "rake"
+  # Rake::Task["graphql:schema:dump"].invoke
+  # ```
+  #
+  # **Example: Providing arguments to build the introspection query**
+  #
+  # ```ruby
+  # require "graphql/rake_task"
+  # GraphQL::RakeTask.new(schema_name: "MySchema", include_is_one_of: true)
+  # ```
   class RakeTask
     include Rake::DSL
 
@@ -45,37 +57,57 @@ module GraphQL
       include_is_one_of: false
     }
 
-    # @return [String] Namespace for generated tasks
+    # **Returns**
+    #
+    # - `String` — Namespace for generated tasks
     attr_writer :namespace
 
     def rake_namespace
       @namespace
     end
 
-    # @return [Array<String>]
+    # **Returns**
+    #
+    # - `Array<String>`
     attr_accessor :dependencies
 
-    # @return [String] By default, used to find the schema as a constant.
-    # @see {#load_schema} for loading a schema another way
+    # See [load_schema](rdoc-ref:#load_schema) for loading a schema another way
+    #
+    # **Returns**
+    #
+    # - `String` — By default, used to find the schema as a constant.
     attr_accessor :schema_name
 
-    # @return [<#call(task)>] A proc for loading the target GraphQL schema
+    # **Returns**
+    #
+    # - `<#call(task)>` — A proc for loading the target GraphQL schema
     attr_accessor :load_schema
 
-    # @return [<#call(task)>] A callable for loading the query context
+    # **Returns**
+    #
+    # - `<#call(task)>` — A callable for loading the query context
     attr_accessor :load_context
 
-    # @return [String] target for IDL task
+    # **Returns**
+    #
+    # - `String` — target for IDL task
     attr_accessor :idl_outfile
 
-    # @return [String] target for JSON task
+    # **Returns**
+    #
+    # - `String` — target for JSON task
     attr_accessor :json_outfile
 
-    # @return [String] directory for IDL & JSON files
+    # **Returns**
+    #
+    # - `String` — directory for IDL & JSON files
     attr_accessor :directory
 
-    # @return [Boolean] Options for additional fields in the introspection query JSON response
-    # @see GraphQL::Schema.as_json
+    # See [GraphQL::Schema.as_json](rdoc-ref:GraphQL::Schema.as_json).
+    #
+    # **Returns**
+    #
+    # - `Boolean` — Options for additional fields in the introspection query JSON response
     attr_accessor :include_deprecated_args, :include_schema_description, :include_is_repeatable, :include_specified_by_url, :include_is_one_of
 
     # Set the parameters of this task by passing keyword arguments