3 files changed, 33 insertions, 6 deletions

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(..)