haddocks for ReqBody

src/Servant/API/Capture.hs

@@ -43,7 +43,7 @@ captured _ = fromText
 -- >
 -- > server :: Server MyApi
 -- > server = getBook
--- >   where getBook :: Text -> 'EitherT' (Int, String) IO Book
+-- >   where getBook :: Text -> EitherT (Int, String) IO Book
 -- >         getBook isbn = ...
 instance (KnownSymbol capture, FromText a, HasServer sublayout)
       => HasServer (Capture capture a :> sublayout) where

src/Servant/API/ReqBody.hs

@@ -15,9 +15,30 @@ import Servant.Common.Req
 import Servant.Docs
 import Servant.Server
 
--- * Request Body support
+-- | Extract the request body as a value of type @a@.
+--
+-- Example:
+--
+-- >            -- POST /books
+-- > type MyApi = "books" :> ReqBody Book :> Post Book
 data ReqBody a
 
+-- | If you use 'ReqBody' in one of the endpoints for your API,
+-- this automatically requires your server-side handler to be a function
+-- that takes an argument of the type specified by 'ReqBody'.
+-- This lets servant worry about extracting it from the request and turning
+-- it into a value of the type you specify.
+--
+-- All it asks is for a 'FromJSON' instance.
+--
+-- Example:
+--
+-- > type MyApi = "books" :> ReqBody Book :> Post Book
+-- >
+-- > server :: Server MyApi
+-- > server = postBook
+-- >   where postBook :: Book -> EitherT (Int, String) IO Book
+-- >         postBook book = ...insert into your db...
 instance (FromJSON a, HasServer sublayout)
       => HasServer (ReqBody a :> sublayout) where
 
@@ -30,6 +51,24 @@ instance (FromJSON a, HasServer sublayout)
       Nothing -> respond $ failWith InvalidBody
       Just v  -> route (Proxy :: Proxy sublayout) (subserver v) request respond
 
+-- | If you use a 'ReqBody' in one of your endpoints in your API,
+-- the corresponding querying function will automatically take
+-- an additional argument of the type specified by your 'ReqBody'.
+-- That function will take care of encoding this argument as JSON and
+-- of using it as the request body.
+--
+-- All you need is for your type to have a 'ToJSON' instance.
+--
+-- Example:
+--
+-- > type MyApi = "books" :> ReqBody Book :> Post Book
+-- >
+-- > myApi :: Proxy MyApi
+-- > myApi = Proxy
+-- >
+-- > addBook :: Book -> BaseUrl -> EitherT String IO Book
+-- > addBook = client myApi
+-- > -- then you can just use "addBook" to query that endpoint
 instance (ToJSON a, HasClient sublayout)
       => HasClient (ReqBody a :> sublayout) where