doc(Scalar) improve scalar description

Author: rmosolgo

lib/graphql/scalar_type.rb

@@ -1,5 +1,28 @@
 module GraphQL
-  # The parent type for scalars, eg {GraphQL::STRING_TYPE}, {GraphQL::INT_TYPE}
+  # # GraphQL::ScalarType
+  #
+  # Scalars are plain values. They are leaf nodes in a GraphQL query tree.
+  #
+  # ## Built-in Scalars
+  #
+  # `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`
+  #
+  # (`types` is an instance of `GraphQL::Definition::TypeDefiner`; `.String`, `.Float`, etc are methods which return built-in scalars.)
+  #
+  # ## Custom Scalars
+  #
+  # You can define custom scalars for your GraphQL server. It requires some special functions:
+  #
+  # - `coerce_input` is used to prepare incoming values for GraphQL execution. (Incoming values come from variables or literal values in the query string.)
+  # - `coerce_result` is used to turn Ruby values _back_ into serializable values for query responses.
   #
   # @example defining a type for Time
   #   TimeType = GraphQL::ScalarType.define do