doc(InputObjectType) improve header and examples

Author: rmosolgo

lib/graphql/define.rb

@@ -19,7 +19,7 @@ module Define
     #   # After definition, read the key from metadata
     #   PostType.metadata[:resolves_to_class_names] # => [...]
     #
-    # @param [Object] the key to assign in metadata
+    # @param key [Object] the key to assign in metadata
     # @return [#call(defn, value)] an assignment for `.accepts_definitions` which writes `key` to `#metadata`
     def self.assign_metadata_key(key)
       GraphQL::Define::InstanceDefinable::AssignMetadataKey.new(key)

lib/graphql/field.rb

@@ -72,6 +72,16 @@ module GraphQL
   #     }
   #   end
   #
+  # Only certain types maybe used for inputs:
+  #
+  # - Scalars
+  # - Enums
+  # - Input Objects
+  # - Lists of those types
+  #
+  # Input types may also be non-null -- in that case, the query will fail
+  # if the input is not present.
+  #
   # ## Complexity
   #
   # Fields can have _complexity_ values which describe the computation cost of resolving the field.

lib/graphql/input_object_type.rb

@@ -1,13 +1,27 @@
 module GraphQL
-  # A complex input type for a field argument.
+  # {InputObjectType}s are key-value inputs for fields.
+  #
+  # Input objects have _arguments_ which are identical to {GraphQL::Field} arguments.
+  # They map names to types and support default values.
+  # Their input types can be any input types, including {InputObjectType}s.
   #
   # @example An input type with name and number
   #   PlayerInput = GraphQL::InputObjectType.define do
   #     name("Player")
-  #     input_field :name, !types.String
-  #     input_field :number, !types.Int
+  #     argument :name, !types.String
+  #     argument :number, !types.Int
   #   end
   #
+  # In a `resolve` function, you can access the values by making nested lookups on `args`.
+  #
+  # @example Accessing input values in a resolve function
+  #   resolve -> (obj, args, ctx) {
+  #     args[:player][:name]    # => "Tony Gwynn"
+  #     args[:player][:number]  # => 19
+  #     args[:player].to_h      # { "name" => "Tony Gwynn", "number" => 19 }
+  #     # ...
+  #   }
+  #
   class InputObjectType < GraphQL::BaseType
     accepts_definitions(
       input_field: GraphQL::Define::AssignArgument,