From ac930ef198ee00a257e32c85839b6691817e5aa9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=B6nke=20Hahn?= <soenkehahn@gmail.com>
Date: Mon, 18 Jan 2016 19:55:14 +0100
Subject: [PATCH] ComprehensiveAPI: add some comments (and minor tweaks)

---
 servant-client/test/Servant/ClientSpec.hs                 | 1 +
 servant-docs/test/Servant/DocsSpec.hs                     | 1 +
 servant-js/test/Servant/JSSpec.hs                         | 3 ++-
 servant-mock/test/Servant/MockSpec.hs                     | 1 +
 servant-server/test/Servant/ServerSpec.hs                 | 3 ++-
 servant/src/Servant/API/Internal/Test/ComprehensiveAPI.hs | 3 +++
 6 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/servant-client/test/Servant/ClientSpec.hs b/servant-client/test/Servant/ClientSpec.hs
index 06cf7ca..c8726cf 100644
--- a/servant-client/test/Servant/ClientSpec.hs
+++ b/servant-client/test/Servant/ClientSpec.hs
@@ -53,6 +53,7 @@ import           Servant.API.Internal.Test.ComprehensiveAPI
 import           Servant.Client
 import           Servant.Server
 
+-- This declaration simply checks that all instances are in place.
 _ = client comprehensiveAPI
 
 spec :: Spec
diff --git a/servant-docs/test/Servant/DocsSpec.hs b/servant-docs/test/Servant/DocsSpec.hs
index e49aeaa..018fd46 100644
--- a/servant-docs/test/Servant/DocsSpec.hs
+++ b/servant-docs/test/Servant/DocsSpec.hs
@@ -23,6 +23,7 @@ import           Servant.Docs.Internal
 
 -- * comprehensive api
 
+-- This declaration simply checks that all instances are in place.
 _ = docs comprehensiveAPI
 
 instance ToParam (QueryParam "foo" Int) where
diff --git a/servant-js/test/Servant/JSSpec.hs b/servant-js/test/Servant/JSSpec.hs
index 4249e93..371d39d 100644
--- a/servant-js/test/Servant/JSSpec.hs
+++ b/servant-js/test/Servant/JSSpec.hs
@@ -32,7 +32,8 @@ import           Servant.JSSpec.CustomHeaders
 
 -- * comprehensive api
 
-_ = (jsForAPI comprehensiveAPI vanillaJS :: Text)
+-- This declaration simply checks that all instances are in place.
+_ = jsForAPI comprehensiveAPI vanillaJS :: Text
 
 -- * specs
 
diff --git a/servant-mock/test/Servant/MockSpec.hs b/servant-mock/test/Servant/MockSpec.hs
index ff7d969..24cad32 100644
--- a/servant-mock/test/Servant/MockSpec.hs
+++ b/servant-mock/test/Servant/MockSpec.hs
@@ -20,6 +20,7 @@ import           Servant
 import           Servant.API.Internal.Test.ComprehensiveAPI
 import           Servant.Mock
 
+-- This declaration simply checks that all instances are in place.
 _ = mock comprehensiveAPI
 
 data Body
diff --git a/servant-server/test/Servant/ServerSpec.hs b/servant-server/test/Servant/ServerSpec.hs
index aee31d1..e583523 100644
--- a/servant-server/test/Servant/ServerSpec.hs
+++ b/servant-server/test/Servant/ServerSpec.hs
@@ -63,7 +63,8 @@ import           Servant.Server.Internal.Router
 
 -- * comprehensive api test
 
-_ = serve comprehensiveAPI (error "unused") (error "unused")
+-- This declaration simply checks that all instances are in place.
+_ = serve comprehensiveAPI
 
 -- * Specs
 
diff --git a/servant/src/Servant/API/Internal/Test/ComprehensiveAPI.hs b/servant/src/Servant/API/Internal/Test/ComprehensiveAPI.hs
index 2eade8e..1914df8 100644
--- a/servant/src/Servant/API/Internal/Test/ComprehensiveAPI.hs
+++ b/servant/src/Servant/API/Internal/Test/ComprehensiveAPI.hs
@@ -1,6 +1,9 @@
 {-# LANGUAGE DataKinds #-}
 {-# LANGUAGE TypeOperators #-}
 
+-- | This is a module containing an API with all `Servant.API` combinators. It
+-- is used for testing only (in particular, checking that instances exist for
+-- the core servant classes for each combinator), and should not be imported.
 module Servant.API.Internal.Test.ComprehensiveAPI where
 
 import           Data.Proxy