MAGETWO-81034: Address CR issues

 - Make description imperative on methods
 - Reduce nesting level on SchemaGenerator
 - Re-word descriptions for clarity
 - Add description of structure for return type of generate on
   SchemaGenerator

Author: Eric Bohanon

app/code/Magento/GraphQl/Model/Type/Generator.php

@@ -57,12 +57,13 @@ public function generateTypes(string $typeName)
         $mappedFields = $this->typeMap[$typeName];
         foreach ($mappedFields['fields'] as $fieldName => $values) {
             $arguments = [];
-            if (isset($values['args'])) {
-                foreach ($values['args'] as $argName => $argType) {
-                    // Replace '[]' with an 's' to express plurality
-                    $realArgName = str_replace('!', '', str_replace('[]', 's', $argName));
-                    $arguments[$realArgName] = ['type' => $this->decorateType($argName, $argType)];
-                }
+            if (!isset($values['args'])) {
+                $values['args'] = [];
+            }
+            foreach ($values['args'] as $argName => $argType) {
+                // Replace '[]' with an 's' to express plurality
+                $realArgName = str_replace('!', '', str_replace('[]', 's', $argName));
+                $arguments[$realArgName] = ['type' => $this->decorateType($argName, $argType)];
             }
 
             $fields[$fieldName] = ['type' => $this->typePool->getType($values['type']), 'args' => $arguments];

app/code/Magento/GraphQl/Model/Type/GeneratorInterface.php

@@ -7,15 +7,15 @@
 namespace Magento\GraphQl\Model\Type;
 
 /**
- * Generate configured top level GraphQL types, and their children types as defined by type handlers
+ * Generate configured GraphQL type schema and top-level fields of base query object
  */
 interface GeneratorInterface
 {
     /**
      * Generate type definitions for all fields of given GraphQl query or mutation name
      *
      * @param string $typeName
-     * @return array
+     * @return array Represented as ['fields' => ['fieldName' => Type, {...}], 'types' => Types[]]
      */
     public function generateTypes(string $typeName);
 }

app/code/Magento/GraphQl/Model/Type/HandlerFactory.php

@@ -6,10 +6,11 @@
 
 namespace Magento\GraphQl\Model\Type;
 
+use Magento\Framework\Exception\InputException;
 use Magento\Framework\ObjectManagerInterface;
 
 /**
- * Create TypeHandler from its name
+ * Create type handler from its name
  */
 class HandlerFactory
 {
@@ -31,12 +32,13 @@ public function __construct(ObjectManagerInterface $objectManager)
      *
      * @param string $typeClassName
      * @return HandlerInterface
+     * @throws InputException
      */
     public function create($typeClassName)
     {
         $typeHandlerClass = $this->objectManager->create($typeClassName);
         if (!($typeHandlerClass instanceof HandlerInterface)) {
-            throw new \InvalidArgumentException(__('Invalid type name. Type handler does not exist.'));
+            throw new InputException(__('Invalid type name. Type handler does not exist.'));
         }
 
         return $typeHandlerClass;

app/code/Magento/GraphQl/Model/Type/HandlerInterface.php

@@ -9,12 +9,12 @@
 use GraphQL\Type\Definition\Type;
 
 /**
- * Define a method for generating or retrieving a GraphQL's type
+ * Define a method for generating or retrieving a type for GraphQL
  */
 interface HandlerInterface
 {
     /**
-     * Returns GraphQL configuration of type.
+     * Return GraphQL configuration of type.
      *
      * @return Type
      * @throws \InvalidArgumentException No implementation found or type not implemented for interface with resolve type

app/code/Magento/GraphQl/Model/Type/Helper/ServiceContract/TypeGenerator.php

@@ -84,7 +84,7 @@ public function generate(
     }
 
     /**
-     * Gets service contract type data from associative service contract name
+     * Get service contract type data from associative service contract name
      *
      * @param string $type
      * @return array
@@ -190,7 +190,7 @@ private function generateNestedTypes(
     }
 
     /**
-     * Checks if array is associative
+     * Check if array is associative
      *
      * @param $arr
      * @return bool
@@ -201,7 +201,7 @@ private function isAssociativeArray($arr)
     }
 
     /**
-     * Transforms string from underscore to camelcase
+     * Transform string from underscore to camelcase
      *
      * @param string $value
      * @return string