From 0dac9701bc3c1048d155d089167659ebcc152199 Mon Sep 17 00:00:00 2001
From: Eugen Wissner <belka@caraus.de>
Date: Thu, 30 Jun 2022 11:10:46 +0200
Subject: [PATCH] Document usage of the json flag

---
 CHANGELOG.md                           |  5 +++++
 graphql.cabal                          |  2 +-
 src/Language/GraphQL.hs                | 22 ++++++++++++++++++++++
 src/Language/GraphQL/Error.hs          | 12 ++++++------
 src/Language/GraphQL/Execute/Coerce.hs |  5 +++++
 5 files changed, 39 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ff33b3c..d6b856f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,11 @@ and this project adheres to
 ### Changed
 - Removed deprecated `Language.GraphQL.Error` functions: `addErr`, `addErrMsg`,
   `singleError`.
+- Deprecate `Resolution`, `CollectErrsT` and `runCollectErrs` in the `Error`
+  module. It was already noted in the documentation that these symbols are
+  deprecated, now a pragma is added.
+- `Language.GraphQL`: Added information about the *json* flag and switching to
+  *graphql-spice* for JSON support.
 
 ## [1.0.3.0] - 2022-03-27
 ### Fixed
diff --git a/graphql.cabal b/graphql.cabal
index 073b4db..0dd16b2 100644
--- a/graphql.cabal
+++ b/graphql.cabal
@@ -22,7 +22,7 @@ extra-source-files:
   README.md
 tested-with:
   GHC == 8.10.7,
-  GHC == 9.2.2
+  GHC == 9.2.3
 
 source-repository head
   type: git
diff --git a/src/Language/GraphQL.hs b/src/Language/GraphQL.hs
index b64cf42..d54ae60 100644
--- a/src/Language/GraphQL.hs
+++ b/src/Language/GraphQL.hs
@@ -4,6 +4,28 @@
 
 #ifdef WITH_JSON
 -- | This module provides the functions to parse and execute @GraphQL@ queries.
+--
+-- The content of this module depends on the value of the __json__ flag, which
+-- is currently on by default. This behavior will change in the future, the flag
+-- will be switched off by default and then removed.
+--
+-- This documentation is generated with the enabled __json__ flag and functions
+-- described here support JSON and are deprecated. JSON instances are provided
+-- now by an additional package, __graphql-spice__. To start using the new
+-- package create __cabal.project__ in the root directory of your project with
+-- the following contents:
+--
+-- @
+-- packages: .
+-- constraints: graphql -json
+-- @
+--
+-- Then add __graphql-spice__ as dependency.
+--
+-- The new version of this module defines only one function, @graphql@, which
+-- works with the internal GraphQL value representation used by this lbirary.
+-- Refer to @Language.GraphQL.JSON.graphql@ in __graphql-spice__ for the
+-- function that accepts and returns JSON.
 module Language.GraphQL
     ( graphql
     , graphqlSubs
diff --git a/src/Language/GraphQL/Error.hs b/src/Language/GraphQL/Error.hs
index ffd3a78..403aaf6 100644
--- a/src/Language/GraphQL/Error.hs
+++ b/src/Language/GraphQL/Error.hs
@@ -103,8 +103,8 @@ instance Exception ResolverException
 -- | Runs the given query computation, but collects the errors into an error
 -- list, which is then sent back with the data.
 --
--- /runCollectErrs was part of the old executor and isn't used anymore, it will
--- be deprecated in the future and removed./
+-- {-# DEPRECATED runCollectErrs was part of the old executor and isn't used
+-- anymore #-}
 runCollectErrs :: (Monad m, Serialize a)
     => HashMap Name (Schema.Type m)
     -> CollectErrsT m a
@@ -116,8 +116,8 @@ runCollectErrs types' res = do
 
 -- | Executor context.
 --
--- /Resolution was part of the old executor and isn't used anymore, it will be
--- deprecated in the future and removed./
+-- {-# DEPRECATED Resolution was part of the old executor and isn't used
+-- anymore #-}
 data Resolution m = Resolution
     { errors :: Seq Error
     , types :: HashMap Name (Schema.Type m)
@@ -125,6 +125,6 @@ data Resolution m = Resolution
 
 -- | A wrapper to pass error messages around.
 --
--- /CollectErrsT was part of the old executor and isn't used anymore, it will be
--- deprecated in the future and removed./
+-- {-# DEPRECATED CollectErrsT was part of the old executor and isn't used
+-- anymore #-}
 type CollectErrsT m = StateT (Resolution m) m
diff --git a/src/Language/GraphQL/Execute/Coerce.hs b/src/Language/GraphQL/Execute/Coerce.hs
index 9bc6b10..4725d74 100644
--- a/src/Language/GraphQL/Execute/Coerce.hs
+++ b/src/Language/GraphQL/Execute/Coerce.hs
@@ -8,6 +8,11 @@
 {-# LANGUAGE CPP #-}
 
 -- | Types and functions used for input and result coercion.
+--
+-- JSON instances in this module are only available with the __json__
+-- flag that is currently on by default, but will be disabled in the future.
+-- Refer to the documentation in the 'Language.GraphQL' module and to
+-- the __graphql-spice__ package.
 module Language.GraphQL.Execute.Coerce
     ( Output(..)
     , Serialize(..)