doc(Enum, Directive) add better docs and examples

Author: rmosolgo

lib/graphql/argument.rb

@@ -9,9 +9,9 @@ module GraphQL
   #     argument :favoriteFood, types.String, "Favorite thing to eat", default_value: "pizza"
   #   end
   #
-  # @example defining an input field for an {InputObjectType}
+  # @example defining an argument for an {InputObjectType}
   #   GraphQL::InputObjectType.define do
-  #     input_field :newName, !types.String
+  #     argument :newName, !types.String
   #   end
   #
   class Argument

lib/graphql/directive.rb

@@ -1,4 +1,10 @@
 module GraphQL
+  # Directives are server-defined hooks for modifying execution.
+  #
+  # Two directives are included out-of-the-box:
+  # - `@skip(if: ...)` Skips the tagged field if the value of `if` is true
+  # - `@include(if: ...)` Includes the tagged field _only_ if `if` is true
+  #
   class Directive
     include GraphQL::Define::InstanceDefinable
     accepts_definitions :locations, :name, :description, :include_proc, argument: GraphQL::Define::AssignArgument

lib/graphql/enum_type.rb

@@ -1,16 +1,60 @@
 module GraphQL
-  # A finite set of possible values, represented in query strings with
-  # SCREAMING_CASE_NAMES
+  # Represents a collection of related values.
+  # By convention, enum names are `SCREAMING_CASE_NAMES`,
+  # but other identifiers are supported too.
   #
-  # @example An enum of programming languages
+  # You can use as return types _or_ as inputs.
+  #
+  # By default, enums are passed to `resolve` functions as
+  # the strings that identify them, but you can provide a
+  # custom Ruby value with the `value:` keyword.
   #
+  # @example An enum of programming languages
   #   LanguageEnum = GraphQL::EnumType.define do
   #     name "Languages"
   #     description "Programming languages for Web projects"
   #     value("PYTHON", "A dynamic, function-oriented language")
   #     value("RUBY", "A very dynamic language aimed at programmer happiness")
   #     value("JAVASCRIPT", "Accidental lingua franca of the web")
   #   end
+  #
+  # @example Using an enum as a return type
+  #    field :favoriteLanguage, LanguageEnum, "This person's favorite coding language"
+  #    # ...
+  #    # In a query:
+  #    Schema.execute("{ coder(id: 1) { favoriteLanguage } }")
+  #    # { "data" => { "coder" => { "favoriteLanguage" => "RUBY" } } }
+  #
+  # @example Defining an enum input
+  #    field :coders, types[CoderType] do
+  #      argument :knowing, types[LanguageType]
+  #      resolve -> (obj, args, ctx) {
+  #        Coder.where(language: args[:knowing])
+  #      }
+  #    end
+  #
+  # @example Using an enum as input
+  #   {
+  #     # find coders who know Python and Ruby
+  #     coders(knowing: [PYTHON, RUBY]) {
+  #       name
+  #       hourlyRate
+  #     }
+  #   }
+  #
+  # @example Enum whose values are different in Ruby-land
+  #   GraphQL::EnumType.define do
+  #     # ...
+  #     # use the `value:` keyword:
+  #     value("RUBY", "Lisp? Smalltalk?", value: :rb)
+  #   end
+  #
+  #   # Now, resolve functions will receive `:rb` instead of `"RUBY"`
+  #   field :favoriteLanguage, LanguageEnum
+  #   resolve -> (obj, args, ctx) {
+  #     args[:favoriteLanguage] # => :rb
+  #   }
+  #
   class EnumType < GraphQL::BaseType
     accepts_definitions value: GraphQL::Define::AssignEnumValue
 

lib/graphql/scalar_type.rb

@@ -7,13 +7,13 @@ module GraphQL
   #
   # `GraphQL` comes with standard built-in scalars:
   #
-  # Constant | `.define` helper
-  # =========|==================
-  # `GraphQL::STRING_TYPE` | `types.String`
-  # `GraphQL::INT_TYPE` | `types.Int`
-  # `GraphQL::FLOAT_TYPE` | `types.Float`
-  # `GraphQL::ID_TYPE` | `types.ID`
-  # `GraphQL::BOOLEAN_TYPE` | `types.Boolean`
+  # |Constant | `.define` helper|
+  # |-------|--------|
+  # |`GraphQL::STRING_TYPE` | `types.String`|
+  # |`GraphQL::INT_TYPE` | `types.Int`|
+  # |`GraphQL::FLOAT_TYPE` | `types.Float`|
+  # |`GraphQL::ID_TYPE` | `types.ID`|
+  # |`GraphQL::BOOLEAN_TYPE` | `types.Boolean`|
   #
   # (`types` is an instance of `GraphQL::Definition::TypeDefiner`; `.String`, `.Float`, etc are methods which return built-in scalars.)
   #