From 470580affde2af5bfce2a38c5d0c8867b7b114bb Mon Sep 17 00:00:00 2001
From: Eugen Wissner <belka@caraus.de>
Date: Fri, 19 Jul 2024 12:55:36 +0200
Subject: [PATCH] Document derivation functions

---
 src/Language/GraphQL/Class.hs | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/src/Language/GraphQL/Class.hs b/src/Language/GraphQL/Class.hs
index e08ec65..df52d2b 100644
--- a/src/Language/GraphQL/Class.hs
+++ b/src/Language/GraphQL/Class.hs
@@ -311,6 +311,15 @@ instance FromGraphQL LocalTime
 stringLE :: Name -> Q Exp
 stringLE = litE . stringL . nameBase
 
+-- | Given a type derives a 'FromGraphQL' instance for it.
+--
+-- The derivation can only work when all nested types already have 'FromGraphQL'
+-- instances.
+--
+-- The following cases are supported:
+--
+-- * Records encode input objects.
+-- * Sum types with all data constructors without parameters encode Enums.
 deriveFromGraphQL :: Name -> Q [Dec]
 deriveFromGraphQL typeName = do
     TyConI plainConstructor <- reify typeName
@@ -362,6 +371,16 @@ deriveFromGraphQL typeName = do
     makeRecordBody dataConE _ [] = dataConE
     conTName = conT typeName
 
+-- | Given a type derives a 'ToGraphQL' instance for it.
+--
+-- The derivation can only work when all nested types already have 'ToGraphQL'
+-- instances.
+--
+-- The following cases are supported:
+--
+-- * Records are decoded as objects.
+-- * Sum types with all data constructors without parameters are decoded as Enums.
+-- * Sum types whose data constructors have exactly one parameter are decoded as Unions.
 deriveToGraphQL :: Name -> Q [Dec]
 deriveToGraphQL typeName = do
     TyConI plainConstructor <- reify typeName