Documentation and Reexport module

ilya-murzinov · Sep 14, 2017 · e8b9814 · e8b9814
1 parent 6be78e0
commit e8b9814
Show file tree

Hide file tree

Showing 10 changed files with 627 additions and 38 deletions.
diff --git a/servant-client-core/servant-client-core.cabal b/servant-client-core/servant-client-core.cabal
@@ -24,12 +24,14 @@ source-repository head
 library
   exposed-modules:
       Servant.Client.Core
+      Servant.Client.Core.Reexport
       Servant.Client.Core.Internal.Auth
       Servant.Client.Core.Internal.BaseUrl
       Servant.Client.Core.Internal.BasicAuth
-      Servant.Client.Core.Internal.Class
       Servant.Client.Core.Internal.Generic
+      Servant.Client.Core.Internal.HasClient
       Servant.Client.Core.Internal.Request
+      Servant.Client.Core.Internal.RunClient
   build-depends:
       base                  >= 4.7      && < 4.11
     , base-compat           >= 0.9.1    && < 0.10

diff --git a/servant-client-core/src/Servant/Client/Core.hs b/servant-client-core/src/Servant/Client/Core.hs
@@ -1,29 +1,33 @@
-{-# LANGUAGE CPP                   #-}
-{-# LANGUAGE DataKinds             #-}
-{-# LANGUAGE FlexibleContexts      #-}
-{-# LANGUAGE FlexibleInstances     #-}
-{-# LANGUAGE InstanceSigs          #-}
-{-# LANGUAGE MultiParamTypeClasses #-}
-{-# LANGUAGE OverloadedStrings     #-}
-{-# LANGUAGE PolyKinds             #-}
-{-# LANGUAGE ScopedTypeVariables   #-}
-{-# LANGUAGE TypeFamilies          #-}
-{-# LANGUAGE TypeOperators         #-}
-{-# LANGUAGE UndecidableInstances  #-}
-
-#include "overlapping-compat.h"
--- | This module provides 'client' which can automatically generate
--- querying functions for each endpoint just from the type representing your
--- API.
+-- | This module provides backend-agnostic functionality for generating clients
+-- from @servant@ APIs. By "backend," we mean something that concretely
+-- executes the request, such as:
+--
+--  * The 'http-client' library
+--  * The 'haxl' library
+--  * GHCJS via FFI
+--
+-- etc.
+--
+-- Each backend is encapsulated in a monad that is an instance of the
+-- 'RunClient' class.
+--
+-- This library is primarily of interest to backend-writers, who are encouraged
+-- to re-export the parts of the
 module Servant.Client.Core
   (
   -- * Client generation
     clientIn
   , HasClient(..)
 
+  -- * Request
+  , Request(..)
+  , defaultRequest
+  , RequestBody(..)
+
   -- * Authentication
-  , mkAuthenticateReq
-  , AuthenticateReq(..)
+  , mkAuthenticatedRequest
+  , basicAuthReq
+  , AuthenticatedRequest(..)
   , AuthClientData
 
   -- * Generic Client
@@ -33,24 +37,33 @@ module Servant.Client.Core
   , ServantError(..)
   , EmptyClient(..)
 
-  -- * Request
-  , Request(..)
-  , defaultRequest
-  , RequestBody(..)
 
   -- * Response
   , Response(..)
   , RunClient(..)
   , module Servant.Client.Core.Internal.BaseUrl
 
   -- * Writing HasClient instances
+  -- | These functions need not be re-exported by backend libraries.
   , addHeader
   , appendToQueryString
   , appendToPath
   , setRequestBodyLBS
   , setRequestBody
   ) where
+import           Servant.Client.Core.Internal.Auth
+import           Servant.Client.Core.Internal.BaseUrl   (BaseUrl (..),
+                                                         InvalidBaseUrlException,
+                                                         Scheme (..),
+                                                         parseBaseUrl,
+                                                         showBaseUrl)
+import           Servant.Client.Core.Internal.BasicAuth
+import           Servant.Client.Core.Internal.HasClient
+import           Servant.Client.Core.Internal.Generic
+import           Servant.Client.Core.Internal.Request
+import           Servant.Client.Core.Internal.RunClient
 
+{-
 import           Control.Monad.Error.Class              (throwError)
 import           Data.List                              (foldl')
 import           Data.Proxy                             (Proxy (Proxy))
@@ -581,3 +594,4 @@ non-empty lists, but is otherwise more specific, no instance will be overall
 more specific. This in turn generally means adding yet another instance (one
 for empty and one for non-empty lists).
 -}
+-}
diff --git a/servant-client-core/src/Servant/Client/Core/Internal/Auth.hs b/servant-client-core/src/Servant/Client/Core/Internal/Auth.hs
@@ -20,13 +20,13 @@ type family AuthClientData a :: *
 -- data to a request
 --
 -- NOTE: THIS API IS EXPERIMENTAL AND SUBJECT TO CHANGE
-newtype AuthenticateReq a =
-  AuthenticateReq { unAuthReq :: (AuthClientData a, AuthClientData a -> Request -> Request) }
+newtype AuthenticatedRequest a =
+  AuthenticatedRequest { unAuthReq :: (AuthClientData a, AuthClientData a -> Request -> Request) }
 
 -- | Handy helper to avoid wrapping datatypes in tuples everywhere.
 --
 -- NOTE: THIS API IS EXPERIMENTAL AND SUBJECT TO CHANGE
-mkAuthenticateReq :: AuthClientData a
+mkAuthenticatedRequest :: AuthClientData a
                   -> (AuthClientData a -> Request -> Request)
-                  -> AuthenticateReq a
-mkAuthenticateReq val func = AuthenticateReq (val, func)
+                  -> AuthenticatedRequest a
+mkAuthenticatedRequest val func = AuthenticatedRequest (val, func)