graphql 2.6.12 → 2.6.13

data/lib/graphql/schema/field.rb

@@ -1,9 +1,279 @@
 # frozen_string_literal: true
+# typed: true
 require "graphql/schema/field/connection_extension"
 require "graphql/schema/field/scope_extension"
 
 module GraphQL
   class Schema
+    # Field definitions are the primary way to expose data from an object type.
+    # Keep field-specific behavior and examples here; the guide is only an
+    # entry point for the broader fields documentation.
+    #
+    # Object fields expose data about that object or connect the object to other objects. You can add fields to your object types with the `field(...)` class method, for example:
+    #
+    # ```ruby
+    # field :name, String, "The unique name of this list", null: false
+    # ```
+    #
+    # [Objects](/type_definitions/objects) and [Interfaces](/type_definitions/interfaces) have fields.
+    #
+    # The different elements of field definition are addressed below:
+    #
+    # - [Names](#class-graphql-schema-field-field-names) identify the field in GraphQL
+    # - [Return types](#class-graphql-schema-field-field-return-type) say what kind of data this field returns
+    # - [Documentation](#class-graphql-schema-field-field-documentation) includes description, comments and deprecation notes
+    # - [Resolution behavior](#class-graphql-schema-field-field-resolution) hooks up the GraphQL field to Ruby code
+    # - [Arguments](#class-graphql-schema-field-field-arguments) allow fields to take input when they're queried
+    # - [Extra field metadata](#class-graphql-schema-field-extra-field-metadata) for low-level access to the GraphQL-Ruby runtime
+    # - [Add default values for field parameters](#class-graphql-schema-field-field-parameter-default-values)
+    #
+    # ## Field Names
+    #
+    # A field's name is provided as the first argument or as the `name:` option:
+    #
+    # ```ruby
+    # field :team_captain, ...
+    # # or:
+    # field ..., name: :team_captain
+    # ```
+    #
+    # Under the hood, GraphQL-Ruby **camelizes** field names, so `field :team_captain, ...` would be `{ teamCaptain }` in GraphQL. You can disable this behavior by adding `camelize: false` to your field definition or to the [default field options](#class-graphql-schema-field-field-parameter-default-values).
+    #
+    # The field's name is also used as the basis of [field resolution](#class-graphql-schema-field-field-resolution).
+    #
+    # ## Field Return Type
+    #
+    # The second argument to `field(...)` is the return type. This can be:
+    #
+    # - A built-in GraphQL type (`Integer`, `Float`, `String`, `ID`, or `Boolean`)
+    # - A GraphQL type from your application
+    # - An _array_ of any of the above, which denotes a [list type](/type_definitions/lists).
+    #
+    # [Nullability](/type_definitions/non_nulls) is expressed with the `null:` keyword:
+    #
+    # - `null: true` (default) means that the field _may_ return `nil`
+    # - `null: false` means the field is non-nullable; it may not return `nil`. If the implementation returns `nil`, GraphQL-Ruby will return an error to the client.
+    #
+    # Additionally, list types maybe nullable by adding `[..., null: true]` to the definition.
+    #
+    # Here are some examples:
+    #
+    # ```ruby
+    # field :name, String # `String`, may return a `String` or `nil`
+    # field :id, ID, null: false # `ID!`, always returns an `ID`, never `nil`
+    # field :teammates, [Types::User], null: false # `[User!]!`, always returns a list containing `User`s
+    # field :scores, [Integer, null: true] # `[Int]`, may return a list or `nil`, the list may contain a mix of `Integer`s and `nil`s
+    # ```
+    #
+    # ## Field Documentation
+    #
+    # Fields may be documented with a __description__, __comment__ and may be __deprecated__.
+    #
+    # __Descriptions__ can be added with the `field(...)` method as a positional argument, a keyword argument, or inside the block:
+    #
+    # ```ruby
+    # # 3rd positional argument
+    # field :name, String, "The name of this thing", null: false
+    #
+    # # `description:` keyword
+    # field :name, String, null: false,
+    #   description: "The name of this thing"
+    #
+    # # inside the block
+    # field :name, String, null: false do
+    #   description "The name of this thing"
+    # end
+    # ```
+    #
+    # __Comments__ can be added with the `field(...)` method as a keyword argument, or inside the block:
+    # ```ruby
+    # # `comment:` keyword
+    # field :name, String, null: false, comment: "Rename to full name"
+    #
+    # # inside the block
+    # field :name, String, null: false do
+    #   comment "Rename to full name"
+    # end
+    # ```
+    #
+    # Generates field name with comment above "Rename to full name" above.
+    #
+    # ```graphql
+    # type Foo {
+    #     # Rename to full name
+    #     name: String!
+    # }
+    # ```
+    #
+    # __Deprecated__ fields can be marked by adding a `deprecation_reason:` keyword argument:
+    #
+    # ```ruby
+    # field :email, String,
+    #   deprecation_reason: "Users may have multiple emails, use `User.emails` instead."
+    # ```
+    #
+    # Fields with a `deprecation_reason:` will appear as "deprecated" in GraphiQL.
+    #
+    # ## Field Resolution
+    #
+    # In general, fields return Ruby values corresponding to their GraphQL return types. For example, a field with the return type `String` should return a Ruby string, and a field with the return type `[User!]!` should return a Ruby array with zero or more `User` objects in it.
+    #
+    # By default, fields return values by:
+    #
+    # - Trying to call a method on the underlying object; _OR_
+    # - If the underlying object is a `Hash`, lookup a key in that hash.
+    # - An optional `:fallback_value` can be supplied that will be used if the above fail.
+    #
+    # The method name or hash key corresponds to the field name, so in this example:
+    #
+    # ```ruby
+    # field :top_score, Integer, null: false
+    # ```
+    #
+    # The default behavior is to look for a `#top_score` method, or lookup a `Hash` key, `:top_score` (symbol) or `"top_score"` (string).
+    #
+    # You can override the method name with the `method:` keyword, or override the hash key(s) with the `hash_key:` or `dig:` keyword, for example:
+    #
+    # ```ruby
+    # # Use the `#best_score` method to resolve this field
+    # field :top_score, Integer, null: false,
+    #   method: :best_score
+    #
+    # # Lookup `hash["allPlayers"]` to resolve this field
+    # field :players, [User], null: false,
+    #   hash_key: "allPlayers"
+    #
+    # # Use the `#dig` method on the hash with `:nested` and `:movies` keys
+    # field :movies, [Movie], null: false,
+    #   dig: [:nested, :movies]
+    # ```
+    #
+    # To pass-through the underlying object without calling a method on it, you can use `method: :itself`:
+    #
+    # ```ruby
+    # field :player, User, null: false,
+    #   method: :itself
+    # ```
+    #
+    # This is equivalent to:
+    #
+    # ```ruby
+    # field :player, User, null: false
+    #
+    # def player
+    #   object
+    # end
+    # ```
+    #
+    # If you don't want to delegate to the underlying object, you can define a method for each field:
+    #
+    # ```ruby
+    # # Use the custom method below to resolve this field
+    # field :total_games_played, Integer, null: false
+    #
+    # def total_games_played
+    #   object.games.count
+    # end
+    # ```
+    #
+    # Inside the method, you can access some helper methods:
+    #
+    # - `object` is the underlying application object (formerly `obj` to resolve functions)
+    # - `context` is the query context (passed as `context:` when executing queries, formerly `ctx` to resolve functions)
+    #
+    # Additionally, when you define arguments (see below), they're passed to the method definition, for example:
+    #
+    # ```ruby
+    # # Call the custom method with incoming arguments
+    # field :current_winning_streak, Integer, null: false do
+    #   argument :include_ties, Boolean, required: false, default_value: false
+    # end
+    #
+    # def current_winning_streak(include_ties:)
+    #   # Business logic goes here
+    # end
+    # ```
+    #
+    # As the examples above show, by default the custom method name must match the field name. If you want to use a different custom method, the `resolver_method` option is available:
+    #
+    # ```ruby
+    # # Use the custom method with a non-default name below to resolve this field
+    # field :total_games_played, Integer, null: false, resolver_method: :games_played
+    #
+    # def games_played
+    #   object.games.count
+    # end
+    # ```
+    #
+    # `resolver_method` has two main use cases:
+    #
+    # 1. resolver re-use between multiple fields
+    # 2. dealing with method conflicts (specifically if you have fields named `context` or `object`)
+    #
+    # Note that `resolver_method` _cannot_ be used in combination with `method` or `hash_key`.
+    #
+    # ## Field Arguments
+    #
+    # _Arguments_ allow fields to take input to their resolution. For example:
+    #
+    # - A `search()` field may take a `term:` argument, which is the query to use for searching, eg `search(term: "GraphQL")`
+    # - A `user()` field may take an `id:` argument, which specifies which user to find, eg `user(id: 1)`
+    # - An `attachments()` field may take a `type:` argument, which filters the result by file type, eg `attachments(type: PHOTO)`
+    #
+    # Read more in the [Arguments guide](/fields/arguments)
+    #
+    # ## Extra Field Metadata
+    #
+    # Inside a field method, you can access some low-level objects from the GraphQL-Ruby runtime. Be warned, these APIs are subject to change, so check the changelog when updating.
+    #
+    # A few `extras` are available:
+    #
+    # - `ast_node`
+    # - `graphql_name` (the field's name)
+    # - `owner` (the type that this field belongs to)
+    # - `lookahead` (see [Lookahead](/queries/lookahead))
+    # - `execution_errors`, whose `#add(err_or_msg)` method should be used for adding errors
+    # - `argument_details` (Interpreter only), an instance of [GraphQL::Execution::Interpreter::Arguments](rdoc-ref:GraphQL::Execution::Interpreter::Arguments) with argument metadata
+    # - `parent` (the previous `object` in the query)
+    # - Custom extras, see below
+    #
+    # To inject them into your field method, first, add the `extras:` option to the field definition:
+    #
+    # ```ruby
+    # field :my_field, String, null: false, extras: [:ast_node]
+    # ```
+    #
+    # Then add `ast_node:` keyword to the method signature:
+    #
+    # ```ruby
+    # def my_field(ast_node:)
+    #   # ...
+    # end
+    # ```
+    #
+    # At runtime, the requested runtime object will be passed to the field.
+    #
+    # __Custom extras__ are also possible. Any method on your field class can be passed to `extras: [...]`, and the value will be injected into the method. For example, `extras: [:owner]` will inject the object type who owns the field. Any new methods on your custom field class may be used, too.
+    #
+    # ## Field Parameter Default Values
+    #
+    # The field method requires you to pass `null:` keyword argument to determine whether the field is nullable or not. For another field you may want to override `camelize`, which is `true` by default. You can override this behavior by adding a custom field with overwritten `camelize` option, which is `true` by default.
+    #
+    # ```ruby
+    # class CustomField < GraphQL::Schema::Field
+    #   # Add `null: false` and `camelize: false` which provide default values
+    #   # in case the caller doesn't pass anything for those arguments.
+    #   # **kwargs is a catch-all that will get everything else
+    #   def initialize(*args, null: false, camelize: false, **kwargs, &block)
+    #     # Then, call super _without_ any args, where Ruby will take
+    #     # _all_ the args originally passed to this method and pass it to the super method.
+    #     super
+    #   end
+    # end
+    # ```
+    #
+    # To use `CustomField` in your Objects and Interfaces, you'll need to register it as a `field_class` on those classes. See  [Customizing Fields](https://graphql-ruby.org/type_definitions/extensions#customizing-fields) for more information on how to do so.
+    #
     class Field
       include GraphQL::Schema::Member::HasArguments
       include GraphQL::Schema::Member::HasArguments::FieldConfigured
@@ -18,22 +288,33 @@ module GraphQL
 
       class FieldImplementationFailed < GraphQL::Error; end
 
-      # @return [String] the GraphQL name for this field, camelized unless `camelize: false` is provided
+      # **Returns**
+      #
+      # - `String` — the GraphQL name for this field, camelized unless `camelize: false` is provided
       attr_reader :name
       alias :graphql_name :name
 
       attr_writer :description
 
-      # @return [Symbol] Method or hash key on the underlying object to look up
+      # **Returns**
+      #
+      # - `Symbol` — Method or hash key on the underlying object to look up
       attr_reader :method_sym
 
-      # @return [String] Method or hash key on the underlying object to look up
+      # **Returns**
+      #
+      # - `String` — Method or hash key on the underlying object to look up
       attr_reader :method_str
 
       attr_reader :hash_key
       attr_reader :dig_keys
 
-      # @return [Symbol] The method on the type to look up
+      # **Returns**
+      #
+      # - `Symbol` — The method on the type to look up
+      #
+      # :call-seq:
+      #   resolver_method() -> Symbol
       def resolver_method
         if @resolver_class
           @resolver_class.resolver_method
@@ -42,7 +323,12 @@ module GraphQL
         end
       end
 
-      # @return [String, nil]
+      # **Returns**
+      #
+      # - `String, nil`
+      #
+      # :call-seq:
+      #   deprecation_reason() -> String | nil
       def deprecation_reason
         super || @resolver_class&.deprecation_reason
       end
@@ -68,10 +354,17 @@ module GraphQL
         end
       end
 
-      # @return [Class] The thing this field was defined on (type, mutation, resolver)
+      # **Returns**
+      #
+      # - `Class` — The thing this field was defined on (type, mutation, resolver)
       attr_accessor :owner
 
-      # @return [Class] The GraphQL type this field belongs to. (For fields defined on mutations, it's the payload type)
+      # **Returns**
+      #
+      # - `Class` — The GraphQL type this field belongs to. (For fields defined on mutations, it's the payload type)
+      #
+      # :call-seq:
+      #   owner_type() -> Class
       def owner_type
         @owner_type ||= if owner.nil?
           raise GraphQL::InvariantError, "Field #{original_name.inspect} (graphql name: #{graphql_name.inspect}) has no owner, but all fields should have an owner. How did this happen?!"
@@ -82,15 +375,27 @@ module GraphQL
         end
       end
 
-      # @return [Symbol] the original name of the field, passed in by the user
+      # **Returns**
+      #
+      # - `Symbol` — the original name of the field, passed in by the user
       attr_reader :original_name
 
-      # @return [Class, nil] The {Schema::Resolver} this field was derived from, if there is one
+      # **Returns**
+      #
+      # - `Class, nil` — The [Schema::Resolver](rdoc-ref:Schema::Resolver) this field was derived from, if there is one
+      #
+      # :call-seq:
+      #   resolver() -> Class | nil
       def resolver
         @resolver_class
       end
 
-      # @return [Boolean] Is this field a predefined introspection field?
+      # **Returns**
+      #
+      # - `Boolean` — Is this field a predefined introspection field?
+      #
+      # :call-seq:
+      #   introspection?() -> bool
       def introspection?
         @introspection
       end
@@ -101,17 +406,30 @@ module GraphQL
 
       alias :mutation :resolver
 
-      # @return [Boolean] Apply tracing to this field? (Default: skip scalars, this is the override value)
+      # **Returns**
+      #
+      # - `Boolean` — Apply tracing to this field? (Default: skip scalars, this is the override value)
       attr_reader :trace
 
-      # @return [String, nil]
+      # **Returns**
+      #
+      # - `String, nil`
+      #
+      # :call-seq:
+      #   subscription_scope() -> String | nil
       def subscription_scope
         @subscription_scope || (@resolver_class.respond_to?(:subscription_scope) ? @resolver_class.subscription_scope : nil)
       end
       attr_writer :subscription_scope
 
       # Can be set with `connection: true|false` or inferred from a type name ending in `*Connection`
-      # @return [Boolean] if true, this field will be wrapped with Relay connection behavior
+      #
+      # **Returns**
+      #
+      # - `Boolean` — if true, this field will be wrapped with Relay connection behavior
+      #
+      # :call-seq:
+      #   connection?() -> bool
       def connection?
         if @connection.nil?
           # Provide default based on type name
@@ -134,7 +452,12 @@ module GraphQL
         end
       end
 
-      # @return [Boolean] if true, the return type's `.scope_items` method will be applied to this field's return value
+      # **Returns**
+      #
+      # - `Boolean` — if true, the return type's `.scope_items` method will be applied to this field's return value
+      #
+      # :call-seq:
+      #   scoped?() -> bool
       def scoped?
         if !@scope.nil?
           # The default was overridden
@@ -154,14 +477,26 @@ module GraphQL
         end
       end
 
-      # This extension is applied to fields when {#connection?} is true.
+      # This extension is applied to fields when [connection?](rdoc-ref:#connection?) is true.
       #
       # You can override it in your base field definition.
-      # @return [Class] A {FieldExtension} subclass for implementing pagination behavior.
-      # @example Configuring a custom extension
-      #   class Types::BaseField < GraphQL::Schema::Field
-      #     connection_extension(MyCustomExtension)
-      #   end
+      #
+      # **Returns**
+      #
+      # - `Class` — A [FieldExtension](rdoc-ref:FieldExtension) subclass for implementing pagination behavior.
+      #
+      # **Examples**
+      #
+      # **Example: Configuring a custom extension**
+      #
+      # ```ruby
+      # class Types::BaseField < GraphQL::Schema::Field
+      #   connection_extension(MyCustomExtension)
+      # end
+      # ```
+      #
+      # :call-seq:
+      #   connection_extension(new_extension_class) -> Class
       def self.connection_extension(new_extension_class = nil)
         if new_extension_class
           @connection_extension = new_extension_class
@@ -170,57 +505,115 @@ module GraphQL
         end
       end
 
-      # @return Boolean
+      # **Returns**
+      #
+      # - `Object` — Boolean
       attr_reader :relay_node_field
-      # @return Boolean
+      # **Returns**
+      #
+      # - `Object` — Boolean
       attr_reader :relay_nodes_field
 
-      # @return [Boolean] Should we warn if this field's name conflicts with a built-in method?
+      # **Returns**
+      #
+      # - `Boolean` — Should we warn if this field's name conflicts with a built-in method?
+      #
+      # :call-seq:
+      #   method_conflict_warning?() -> bool
       def method_conflict_warning?
         @method_conflict_warning
       end
 
-      # @param name [Symbol] The underscore-cased version of this field name (will be camelized for the GraphQL API)
-      # @param type [Class, GraphQL::BaseType, Array] The return type of this field
-      # @param owner [Class] The type that this field belongs to
-      # @param null [Boolean] (defaults to `true`) `true` if this field may return `null`, `false` if it is never `null`
-      # @param description [String] Field description
-      # @param comment [String] Field comment
-      # @param deprecation_reason [String] If present, the field is marked "deprecated" with this message
-      # @param method [Symbol] The method to call on the underlying object to resolve this field (defaults to `name`)
-      # @param hash_key [String, Symbol] The hash key to lookup on the underlying object (if its a Hash) to resolve this field (defaults to `name` or `name.to_s`)
-      # @param dig [Array<String, Symbol>] The nested hash keys to lookup on the underlying hash to resolve this field using dig
-      # @param resolver_method [Symbol] The method on the type to call to resolve this field (defaults to `name`)
-      # @param connection [Boolean] `true` if this field should get automagic connection behavior; default is to infer by `*Connection` in the return type name
-      # @param connection_extension [Class] The extension to add, to implement connections. If `nil`, no extension is added.
-      # @param resolve_static [Symbol, true, nil] Used by {Schema.execute_next} to produce a single value, shared by all objects which resolve this field. Called on the owner type class with `context, **arguments`
-      # @param resolve_batch [Symbol, true, nil] Used by {Schema.execute_next} map `objects` to a same-sized Array of results. Called on the owner type class with `objects, context, **arguments`.
-      # @param resolve_each [Symbol, true, nil] Used by {Schema.execute_next} to get a value value for each item. Called on the owner type class with `object, context, **arguments`.
-      # @param resolve_legacy_instance_method [Symbol, true, nil] Used by {Schema.execute_next} to get a value value for each item. Calls an instance method on the object type class.
-      # @param dataload [Class, Hash] Shorthand for making dataloader calls
-      # @param max_page_size [Integer, nil] For connections, the maximum number of items to return from this field, or `nil` to allow unlimited results.
-      # @param default_page_size [Integer, nil] For connections, the default number of items to return from this field, or `nil` to return unlimited results.
-      # @param introspection [Boolean] If true, this field will be marked as `#introspection?` and the name may begin with `__`
-      # @param resolver_class [Class] (Private) A {Schema::Resolver} which this field was derived from. Use `resolver:` to create a field with a resolver.
-      # @param arguments [{String=>GraphQL::Schema::Argument, Hash}] Arguments for this field (may be added in the block, also)
-      # @param camelize [Boolean] If true, the field name will be camelized when building the schema
-      # @param complexity [Numeric] When provided, set the complexity for this field
-      # @param scope [Boolean] If true, the return type's `.scope_items` method will be called on the return value
-      # @param subscription_scope [Symbol, String] A key in `context` which will be used to scope subscription payloads
-      # @param extensions [Array<Class, Hash<Class => Object>>] Named extensions to apply to this field (see also {#extension})
-      # @param directives [Hash{Class => Hash}] Directives to apply to this field
-      # @param trace [Boolean] If true, a {GraphQL::Tracing} tracer will measure this scalar field
-      # @param broadcastable [Boolean] Whether or not this field can be distributed in subscription broadcasts
-      # @param ast_node [Language::Nodes::FieldDefinition, nil] If this schema was parsed from definition, this AST node defined the field
-      # @param method_conflict_warning [Boolean] If false, skip the warning if this field's method conflicts with a built-in method
-      # @param validates [Array<Hash>] Configurations for validating this field
-      # @param fallback_value [Object] A fallback value if the method is not defined
-      # @param dynamic_introspection [Boolean] (Private, used by GraphQL-Ruby)
-      # @param relay_node_field [Boolean] (Private, used by GraphQL-Ruby)
-      # @param relay_nodes_field [Boolean] (Private, used by GraphQL-Ruby)
-      # @param extras [Array<:ast_node, :parent, :lookahead, :owner, :execution_errors, :graphql_name, :argument_details, Symbol>] Extra arguments to be injected into the resolver for this field
-      # @param definition_block [Proc] an additional block for configuring the field. Receive the field as a block param, or, if no block params are defined, then the block is `instance_eval`'d on the new {Field}.
-      def initialize(type: nil, name: nil, owner: nil, null: nil, description: NOT_CONFIGURED, comment: NOT_CONFIGURED, deprecation_reason: nil, method: nil, resolve_legacy_instance_method: nil, resolve_static: nil, resolve_each: nil, resolve_batch: nil, hash_key: nil, dig: nil, resolver_method: nil, connection: nil, max_page_size: NOT_CONFIGURED, default_page_size: NOT_CONFIGURED, scope: nil, introspection: false, camelize: true, trace: nil, complexity: nil, dataload: nil, ast_node: nil, extras: EMPTY_ARRAY, extensions: EMPTY_ARRAY, connection_extension: self.class.connection_extension, resolver_class: nil, subscription_scope: nil, relay_node_field: false, relay_nodes_field: false, method_conflict_warning: true, broadcastable: NOT_CONFIGURED, arguments: EMPTY_HASH, directives: EMPTY_HASH, validates: EMPTY_ARRAY, fallback_value: NOT_CONFIGURED, dynamic_introspection: false, &definition_block)
+      # **Parameters**
+      #
+      # - `name` (`Symbol`) — The underscore-cased version of this field name (will be camelized for the GraphQL API)
+      # - `type` (`Class, GraphQL::BaseType, Array`) — The return type of this field
+      # - `owner` (`Class`) — The type that this field belongs to
+      # - `null` (`Boolean`) — (defaults to `true`) `true` if this field may return `null`, `false` if it is never `null`
+      # - `description` (`String`) — Field description
+      # - `comment` (`String`) — Field comment
+      # - `deprecation_reason` (`String`) — If present, the field is marked "deprecated" with this message
+      # - `method` (`Symbol`) — The method to call on the underlying object to resolve this field (defaults to `name`)
+      # - `hash_key` (`String, Symbol`) — The hash key to lookup on the underlying object (if its a Hash) to resolve this field (defaults to `name` or `name.to_s`)
+      # - `dig` (`Array<String, Symbol>`) — The nested hash keys to lookup on the underlying hash to resolve this field using dig
+      # - `resolver_method` (`Symbol`) — The method on the type to call to resolve this field (defaults to `name`)
+      # - `connection` (`Boolean`) — `true` if this field should get automagic connection behavior; default is to infer by `*Connection` in the return type name
+      # - `connection_extension` (`Class`) — The extension to add, to implement connections. If `nil`, no extension is added.
+      # - `resolve_static` (`Symbol, true, nil`) — Used by `Schema.execute_next` to produce a single value, shared by all objects which resolve this field. Called on the owner type class with `context, **arguments`
+      # - `resolve_batch` (`Symbol, true, nil`) — Used by `Schema.execute_next` map `objects` to a same-sized Array of results. Called on the owner type class with `objects, context, **arguments`.
+      # - `resolve_each` (`Symbol, true, nil`) — Used by `Schema.execute_next` to get a value value for each item. Called on the owner type class with `object, context, **arguments`.
+      # - `resolve_legacy_instance_method` (`Symbol, true, nil`) — Used by `Schema.execute_next` to get a value value for each item. Calls an instance method on the object type class.
+      # - `dataload` (`Class, Hash`) — Shorthand for making dataloader calls
+      # - `max_page_size` (`Integer, nil`) — For connections, the maximum number of items to return from this field, or `nil` to allow unlimited results.
+      # - `default_page_size` (`Integer, nil`) — For connections, the default number of items to return from this field, or `nil` to return unlimited results.
+      # - `introspection` (`Boolean`) — If true, this field will be marked as `#introspection?` and the name may begin with `__`
+      # - `resolver_class` (`Class`) — (Private) A [Schema::Resolver](rdoc-ref:Schema::Resolver) which this field was derived from. Use `resolver:` to create a field with a resolver.
+      # - `arguments` (`{String=>GraphQL::Schema::Argument, Hash}`) — Arguments for this field (may be added in the block, also)
+      # - `camelize` (`Boolean`) — If true, the field name will be camelized when building the schema
+      # - `complexity` (`Numeric`) — When provided, set the complexity for this field
+      # - `scope` (`Boolean`) — If true, the return type's `.scope_items` method will be called on the return value
+      # - `subscription_scope` (`Symbol, String`) — A key in `context` which will be used to scope subscription payloads
+      # - `extensions` (`Array<Class, Hash<Class => Object>>`) — Named extensions to apply to this field (see also [extension](rdoc-ref:GraphQL::Schema::Field#extension))
+      # - `directives` (`Hash{Class => Hash}`) — Directives to apply to this field
+      # - `trace` (`Boolean`) — If true, a [GraphQL::Tracing](rdoc-ref:GraphQL::Tracing) tracer will measure this scalar field
+      # - `broadcastable` (`Boolean`) — Whether or not this field can be distributed in subscription broadcasts
+      # - `ast_node` (`Language::Nodes::FieldDefinition, nil`) — If this schema was parsed from definition, this AST node defined the field
+      # - `method_conflict_warning` (`Boolean`) — If false, skip the warning if this field's method conflicts with a built-in method
+      # - `validates` (`Array<Hash>`) — Configurations for validating this field
+      # - `fallback_value` (`Object`) — A fallback value if the method is not defined
+      # - `dynamic_introspection` (`Boolean`) — (Private, used by GraphQL-Ruby)
+      # - `relay_node_field` (`Boolean`) — (Private, used by GraphQL-Ruby)
+      # - `relay_nodes_field` (`Boolean`) — (Private, used by GraphQL-Ruby)
+      # - `extras` (`Array<:ast_node, :parent, :lookahead, :owner, :execution_errors, :graphql_name, :argument_details, Symbol>`) — Extra arguments to be injected into the resolver for this field
+      # - `definition_block` (`Proc`) — an additional block for configuring the field. Receive the field as a block param, or, if no block params are defined, then the block is `instance_eval`'d on the new [Field](rdoc-ref:Field).
+      #
+      # :call-seq:
+      #   initialize(Class | GraphQL::BaseType | Array type:, Symbol name:, Class owner:, bool null:, String description:, String comment:, String deprecation_reason:, Symbol method:, Symbol | true | nil resolve_legacy_instance_method:, Symbol | true | nil resolve_static:, Symbol | true | nil resolve_each:, Symbol | true | nil resolve_batch:, String | Symbol hash_key:, Array[String | Symbol] dig:, Symbol resolver_method:, bool connection:, Integer | nil max_page_size:, Integer | nil default_page_size:, Array[:ast_node | :parent | :lookahead | :owner | :execution_errors | :graphql_name | :argument_details | Symbol] extras:, Array[Class | Hash[Class, Object]] extensions:, Class connection_extension:, Class resolver_class:, Symbol | String subscription_scope:, bool relay_node_field:, bool relay_nodes_field:, bool method_conflict_warning:, bool broadcastable:, {String=>GraphQL::Schema::Argument | Hash} arguments:, Hash[Class, Hash] directives:, Array[Hash] validates:, Object fallback_value:, bool dynamic_introspection:, bool scope:, bool introspection:, bool camelize:, bool trace:, Numeric complexity:, Class | Hash dataload:, Language::Nodes::FieldDefinition | nil ast_node:, Proc &definition_block)
+      def initialize(
+        type: nil,
+        name: nil,
+        owner: nil,
+        null: nil,
+        description: NOT_CONFIGURED,
+        comment: NOT_CONFIGURED,
+        deprecation_reason: nil,
+        method: nil,
+        resolve_legacy_instance_method: nil,
+        resolve_static: nil,
+        resolve_each: nil,
+        resolve_batch: nil,
+        hash_key: nil,
+        dig: nil,
+        resolver_method: nil,
+        connection: nil,
+        max_page_size: NOT_CONFIGURED,
+        default_page_size: NOT_CONFIGURED,
+        extras: EMPTY_ARRAY,
+        extensions: EMPTY_ARRAY,
+        connection_extension: self.class.connection_extension,
+        resolver_class: nil,
+        subscription_scope: nil,
+        relay_node_field: false,
+        relay_nodes_field: false,
+        method_conflict_warning: true,
+        broadcastable: NOT_CONFIGURED,
+        arguments: EMPTY_HASH,
+        directives: EMPTY_HASH,
+        validates: EMPTY_ARRAY,
+        fallback_value: NOT_CONFIGURED,
+        # Keywords below this line must have literal defaults (`nil`, `true`, `false`, a number or a symbol).
+        # Ruby uses a 31-bit bitmap to track which keywords with non-literal defaults were given.
+        # If one comes after the 31st keyword, Ruby allocates a Hash on every call.
+        dynamic_introspection: false,
+        scope: nil,
+        introspection: false,
+        camelize: true,
+        trace: nil,
+        complexity: nil,
+        dataload: nil,
+        ast_node: nil,
+        &definition_block
+      )
         if name.nil?
           raise ArgumentError, "missing first `name` argument or keyword `name:`"
         end
@@ -232,7 +625,6 @@ module GraphQL
         @original_name = name
         name_s = -name.to_s
 
-        @underscored_name = -Member::BuildType.underscore(name_s)
         @name = -(camelize ? Member::BuildType.camelize(name_s) : name_s)
         NameValidator.validate!(@name)
         @description = description
@@ -368,15 +760,16 @@ module GraphQL
         end
       end
 
-      # @api private
-      attr_reader :execution_mode_key, :execution_mode
+      attr_reader :execution_mode_key, :execution_mode # :nodoc:
 
       # Calls the definition block, if one was given.
       # This is deferred so that references to the return type
       # can be lazily evaluated, reducing Rails boot time.
-      # @return [self]
-      # @api private
-      def ensure_loaded
+      #
+      # **Returns**
+      #
+      # - `self`
+      def ensure_loaded # :nodoc:
         if @definition_block
           if @definition_block.arity == 1
             @definition_block.call(self)
@@ -393,8 +786,14 @@ module GraphQL
       attr_accessor :dynamic_introspection
 
       # If true, subscription updates with this field can be shared between viewers
-      # @return [Boolean, nil]
-      # @see GraphQL::Subscriptions::BroadcastAnalyzer
+      # See `GraphQL::Subscriptions::BroadcastAnalyzer`.
+      #
+      # **Returns**
+      #
+      # - `Boolean, nil`
+      #
+      # :call-seq:
+      #   broadcastable?() -> bool | nil
       def broadcastable?
         if !NOT_CONFIGURED.equal?(@broadcastable)
           @broadcastable
@@ -405,8 +804,16 @@ module GraphQL
         end
       end
 
-      # @param text [String]
-      # @return [String]
+      # **Parameters**
+      #
+      # - `text` (`String`)
+      #
+      # **Returns**
+      #
+      # - `String`
+      #
+      # :call-seq:
+      #   description(String text) -> String
       def description(text = nil)
         if text
           @description = text
@@ -419,8 +826,16 @@ module GraphQL
         end
       end
 
-      # @param text [String]
-      # @return [String, nil]
+      # **Parameters**
+      #
+      # - `text` (`String`)
+      #
+      # **Returns**
+      #
+      # - `String, nil`
+      #
+      # :call-seq:
+      #   comment(String text) -> String | nil
       def comment(text = nil)
         if text
           @comment = text
@@ -437,17 +852,36 @@ module GraphQL
       # or add new classes/options to be initialized on this field.
       # Extensions are executed in the order they are added.
       #
-      # @example adding an extension
-      #   extensions([MyExtensionClass])
+      # **Examples**
+      #
+      # **Example: adding an extension**
+      #
+      # ```ruby
+      # extensions([MyExtensionClass])
+      # ```
+      #
+      # **Example: adding multiple extensions**
       #
-      # @example adding multiple extensions
-      #   extensions([MyExtensionClass, AnotherExtensionClass])
+      # ```ruby
+      # extensions([MyExtensionClass, AnotherExtensionClass])
+      # ```
       #
-      # @example adding an extension with options
-      #   extensions([MyExtensionClass, { AnotherExtensionClass => { filter: true } }])
+      # **Example: adding an extension with options**
       #
-      # @param extensions [Array<Class, Hash<Class => Hash>>] Add extensions to this field. For hash elements, only the first key/value is used.
-      # @return [Array<GraphQL::Schema::FieldExtension>] extensions to apply to this field
+      # ```ruby
+      # extensions([MyExtensionClass, { AnotherExtensionClass => { filter: true } }])
+      # ```
+      #
+      # **Parameters**
+      #
+      # - `extensions` (`Array<Class, Hash<Class => Hash>>`) — Add extensions to this field. For hash elements, only the first key/value is used.
+      #
+      # **Returns**
+      #
+      # - `Array<GraphQL::Schema::FieldExtension>` — extensions to apply to this field
+      #
+      # :call-seq:
+      #   extensions(new_extensions) -> Array[GraphQL::Schema::FieldExtension]
       def extensions(new_extensions = nil)
         if new_extensions
           new_extensions.each do |extension_config|
@@ -464,15 +898,31 @@ module GraphQL
 
       # Add `extension` to this field, initialized with `options` if provided.
       #
-      # @example adding an extension
-      #   extension(MyExtensionClass)
+      # **Examples**
+      #
+      # **Example: adding an extension**
       #
-      # @example adding an extension with options
-      #   extension(MyExtensionClass, filter: true)
+      # ```ruby
+      # extension(MyExtensionClass)
+      # ```
       #
-      # @param extension_class [Class] subclass of {Schema::FieldExtension}
-      # @param options [Hash] if provided, given as `options:` when initializing `extension`.
-      # @return [void]
+      # **Example: adding an extension with options**
+      #
+      # ```ruby
+      # extension(MyExtensionClass, filter: true)
+      # ```
+      #
+      # **Parameters**
+      #
+      # - `extension_class` (`Class`) — subclass of [Schema::FieldExtension](rdoc-ref:Schema::FieldExtension)
+      # - `options` (`Hash`) — if provided, given as `options:` when initializing `extension`.
+      #
+      # **Returns**
+      #
+      # - `void`
+      #
+      # :call-seq:
+      #   extension(Class extension_class, Hash **options) -> void
       def extension(extension_class, **options)
         extension_inst = extension_class.new(field: self, options: options)
         if @extensions.frozen?
@@ -488,8 +938,16 @@ module GraphQL
       # Read extras (as symbols) from this field,
       # or add new extras to be opted into by this field's resolver.
       #
-      # @param new_extras [Array<Symbol>] Add extras to this field
-      # @return [Array<Symbol>]
+      # **Parameters**
+      #
+      # - `new_extras` (`Array<Symbol>`) — Add extras to this field
+      #
+      # **Returns**
+      #
+      # - `Array<Symbol>`
+      #
+      # :call-seq:
+      #   extras(Array[Symbol] new_extras) -> Array[Symbol]
       def extras(new_extras = nil)
         if new_extras.nil?
           # Read the value
@@ -536,14 +994,22 @@ module GraphQL
           else
             metadata_complexity = 0
             lookahead = GraphQL::Execution::Lookahead.new(query: query, field: self, ast_nodes: nodes, owner_type: owner)
+            # `QueryComplexity` doesn't add skipped introspection fields to `child_complexity`,
+            # so they must not be subtracted from it here, either.
+            count_introspection_fields = query.schema.max_complexity_count_introspection_fields
 
             lookahead.selections.each do |next_lookahead|
+              next if !count_introspection_fields && next_lookahead.field.introspection?
               # this includes `pageInfo`, `nodes` and `edges` and any custom fields
               # TODO this doesn't support procs yet -- unlikely to need it.
               metadata_complexity += next_lookahead.field.complexity
               if next_lookahead.name != :nodes && next_lookahead.name != :edges
                 # subfields, eg, for pageInfo -- assumes no subselections
-                metadata_complexity += next_lookahead.selections.size
+                if count_introspection_fields
+                  metadata_complexity += next_lookahead.selections.size
+                else
+                  metadata_complexity += next_lookahead.selections.count { |s| !s.field.introspection? }
+                end
               end
             end
 
@@ -582,12 +1048,22 @@ module GraphQL
         end
       end
 
-      # @return [Boolean] True if this field's {#max_page_size} should override the schema default.
+      # **Returns**
+      #
+      # - `Boolean` — True if this field's [max page size](rdoc-ref:#max_page_size) should override the schema default.
+      #
+      # :call-seq:
+      #   has_max_page_size?() -> bool
       def has_max_page_size?
         !NOT_CONFIGURED.equal?(@max_page_size) || (@resolver_class && @resolver_class.has_max_page_size?)
       end
 
-      # @return [Integer, nil] Applied to connections if {#has_max_page_size?}
+      # **Returns**
+      #
+      # - `Integer, nil` — Applied to connections if [has max page size?](rdoc-ref:#has_max_page_size?)
+      #
+      # :call-seq:
+      #   max_page_size() -> Integer | nil
       def max_page_size
         if !NOT_CONFIGURED.equal?(@max_page_size)
           @max_page_size
@@ -598,12 +1074,22 @@ module GraphQL
         end
       end
 
-      # @return [Boolean] True if this field's {#default_page_size} should override the schema default.
+      # **Returns**
+      #
+      # - `Boolean` — True if this field's [default page size](rdoc-ref:#default_page_size) should override the schema default.
+      #
+      # :call-seq:
+      #   has_default_page_size?() -> bool
       def has_default_page_size?
         !NOT_CONFIGURED.equal?(@default_page_size) || (@resolver_class && @resolver_class.has_default_page_size?)
       end
 
-      # @return [Integer, nil] Applied to connections if {#has_default_page_size?}
+      # **Returns**
+      #
+      # - `Integer, nil` — Applied to connections if [has default page size?](rdoc-ref:#has_default_page_size?)
+      #
+      # :call-seq:
+      #   default_page_size() -> Integer | nil
       def default_page_size
         if !NOT_CONFIGURED.equal?(@default_page_size)
           @default_page_size
@@ -628,8 +1114,17 @@ module GraphQL
       # Get or set the return type of this field.
       #
       # It may return nil if no type was configured or if the given definition block wasn't called yet.
-      # @param new_type [Module, GraphQL::Schema::NonNull, GraphQL::Schema::List] A GraphQL return type
-      # @return [Module, GraphQL::Schema::NonNull, GraphQL::Schema::List, nil] the configured type for this field
+      #
+      # **Parameters**
+      #
+      # - `new_type` (`Module, GraphQL::Schema::NonNull, GraphQL::Schema::List`) — A GraphQL return type
+      #
+      # **Returns**
+      #
+      # - `Module, GraphQL::Schema::NonNull, GraphQL::Schema::List, nil` — the configured type for this field
+      #
+      # :call-seq:
+      #   type(Module | GraphQL::Schema::NonNull | GraphQL::Schema::List new_type) -> Module | GraphQL::Schema::NonNull | GraphQL::Schema::List | nil
       def type(new_type = NOT_CONFIGURED)
         if NOT_CONFIGURED.equal?(new_type)
           if @resolver_class
@@ -716,15 +1211,21 @@ module GraphQL
 
       # This method is called by the interpreter for each field.
       # You can extend it in your base field classes.
-      # @param object [GraphQL::Schema::Object] An instance of some type class, wrapping an application object
-      # @param args [Hash] A symbol-keyed hash of Ruby keyword arguments. (Empty if no args)
-      # @param ctx [GraphQL::Query::Context]
+      #
+      # **Parameters**
+      #
+      # - `object` (`GraphQL::Schema::Object`) — An instance of some type class, wrapping an application object
+      # - `args` (`Hash`) — A symbol-keyed hash of Ruby keyword arguments. (Empty if no args)
+      # - `ctx` (`GraphQL::Query::Context`)
+      #
+      # :call-seq:
+      #   resolve(GraphQL::Schema::Object object, Hash args, query_ctx)
       def resolve(object, args, query_ctx)
         # Unwrap the GraphQL object to get the application object.
         application_object = object.object
-        method_receiver = nil
-        method_to_call = nil
-        method_args = nil
+        method_receiver = nil #: untyped
+        method_to_call = nil #: untyped
+        method_args = nil #: untyped
 
         @own_validators && Schema::Validator.validate!(validators, application_object, query_ctx, args)
 
@@ -824,7 +1325,12 @@ module GraphQL
         err
       end
 
-      # @param ctx [GraphQL::Query::Context]
+      # **Parameters**
+      #
+      # - `ctx` (`GraphQL::Query::Context`)
+      #
+      # :call-seq:
+      #   fetch_extra(extra_name, GraphQL::Query::Context ctx)
       def fetch_extra(extra_name, ctx)
         if extra_name != :path && extra_name != :ast_node && respond_to?(extra_name)
           self.public_send(extra_name)
@@ -841,7 +1347,7 @@ module GraphQL
         method_defn = receiver.method(method_name)
         unsatisfied_ruby_kwargs = ruby_kwargs.dup
         unsatisfied_method_params = []
-        encountered_keyrest = false
+        encountered_keyrest = false #: bool
         method_defn.parameters.each do |(param_type, param_name)|
           case param_type
           when :key
@@ -890,7 +1396,13 @@ ERR
 
       # Wrap execution with hooks.
       # Written iteratively to avoid big stack traces.
-      # @return [Object] Whatever the
+      #
+      # **Returns**
+      #
+      # - `Object` — Whatever the
+      #
+      # :call-seq:
+      #   with_extensions(obj, args, ctx) -> Object
       def with_extensions(obj, args, ctx)
         if @extensions.empty?
           yield(obj, args)