ComprehensiveAPI: add some comments (and minor tweaks)

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

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

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
 

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

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
 

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