Clarify our approach to union type resolving

Author: Totktonada

graphql/accessor_general.lua

@@ -614,7 +614,6 @@ local function set_connection_index(c, c_name, c_type, collection_name,
     }
 end
 
-
 --- Build `connection_indexes` table (part of `index_cache`) to use in the
 --- @{get_index_name} function.
 ---

graphql/core/execute.lua

@@ -70,7 +70,12 @@ end
 
 local evaluateSelections
 
---@todo resolveType optional comments
+-- @param[opt] resolvedType a type to be used instead of one returned by
+-- `fieldType.resolveType(result)` in case when the `fieldType` is Interface or
+-- Union; that is needed to increase flexibility of an union type resolving
+-- (e.g. resolving by a parent object instead of a current object) via
+-- returning it from the `fieldType.resolve` function, which called before
+-- `resolvedType` and may need to determine the type itself for its needs
 local function completeValue(fieldType, result, subSelections, context, resolvedType)
   local fieldTypeName = fieldType.__type
 
@@ -112,7 +117,6 @@ local function completeValue(fieldType, result, subSelections, context, resolved
     local fields = evaluateSelections(fieldType, result, subSelections, context)
     return next(fields) and fields or context.schema.__emptyObject
   elseif fieldTypeName == 'Interface' or fieldTypeName == 'Union' then
-
     local objectType = resolvedType or fieldType.resolveType(result)
     while objectType.__type == 'NonNull' do
       objectType = objectType.ofType
@@ -156,11 +160,11 @@ local function getFieldEntry(objectType, object, fields, context)
     variableValues = context.variables,
     qcontext = context.qcontext
   }
-  --@todo add comment
+
+  -- resolvedType is optional return value
   local resolvedObject, resolvedType = (fieldType.resolve or defaultResolver)(object, arguments, info)
   local subSelections = query_util.mergeSelectionSets(fields)
 
-  --@todo add comment
   return completeValue(fieldType.kind, resolvedObject, subSelections, context, resolvedType)
 end
 

graphql/tarantool_graphql.lua

@@ -11,21 +11,24 @@
 ---
 --- * Unions: as GraphQL specification says "...no fields may be queried on
 ---   Union type without the use of typed fragments." Tarantool_graphql
----   behaves this way. So 'common fields' are not supported. This does NOT work:
+---   behaves this way. So 'common fields' are not supported. This does NOT
+---   work:
 ---
----  hero {
----       hero_id -- common field
----       ... on human {
----           name
----       }
----       ... on droid {
----           model
----       }
----  }
----  (GraphQL spec: http://facebook.github.io/graphql/October2016/#sec-Unions)
----  Also, no arguments are currently allowed for fragments.
----  See issue about this (https://github.com/facebook/graphql/issues/204)
+--- ```
+--- hero {
+---     hero_id -- common field; does NOT work
+---     ... on human {
+---         name
+---     }
+---     ... on droid {
+---         model
+---     }
+--- }
+--- ```
 ---
+--- (GraphQL spec: http://facebook.github.io/graphql/October2016/#sec-Unions)
+--- Also, no arguments are currently allowed for fragments.
+--- See issue about this (https://github.com/facebook/graphql/issues/204)
 
 local json = require('json')
 local yaml = require('yaml')
@@ -536,7 +539,7 @@ local function convert_union_connection(state, connection, collection_name)
             name = c.name,
             types = union_types,
         }),
-        arguments = nil,
+        arguments = nil, -- see Border cases/Unions at the top of the file
         resolve = function(parent, args_instance, info)
             local v, variant_num = resolve_variant(parent)
             local destination_type = union_types[variant_num]