@@ -15,14 +15,19 @@ module Servant.Server.Internal.Context where
1515import Data.Proxy
1616import GHC.TypeLits
1717
18−-- | When calling 'Servant.Server.serve' you have to supply a context
19−-- value of type @'Context' contextTypes@. This parameter is used to pass values
20−-- to combinators. (It shouldn't be confused with general configuration
21−-- parameters for your web app, like the port, etc.). If you don't use
22−-- combinators that require any context entries, you can just use `serve` (or
23−-- pass 'EmptyContext'). To create a context with entries, use the operator
24−-- @(':.')@. The parameter of the type 'Context' is a type-level list reflecting
25−-- the types of the contained context entries:
18+-- | 'Context's are used to pass values to combinators. (They are __not__ meant
19+-- to be used to pass parameters to your handlers, i.e. they should not replace
20+-- any custom 'Control.Monad.Trans.Reader.ReaderT'-monad-stack that you're using
21+-- with 'Servant.Server.Internal.Enter.enter'.) If you don't use combinators that
22+-- require any context entries, you can just use 'Servant.Server.serve' as always.
23+--
24+-- If you are using combinators that require a non-empty 'Context' you have to
25+-- use 'Servant.Server.serveWithContext' and pass it a 'Context' that contains all
26+-- the values your combinators need. A 'Context' is essentially a heterogenous
27+-- list and accessing the elements is being done by type (see 'getContextEntry').
28+-- The parameter of the type 'Context' is a type-level list reflecting the types
29+-- of the contained context entries. To create a 'Context' with entries, use the
30+-- operator @(':.')@:
2631--
2732-- >>> :type True :. () :. EmptyContext
2833-- True :. () :. EmptyContext :: Context '[Bool, ()]