From c47f4ae0020e324051322496ea312541072ef066 Mon Sep 17 00:00:00 2001
From: Alp Mestanogullari <alpmestan@gmail.com>
Date: Sat, 22 Nov 2014 18:16:55 +0100
Subject: [PATCH] haddocks for ReqBody

---
 src/Servant/API/Capture.hs |  2 +-
 src/Servant/API/ReqBody.hs | 41 +++++++++++++++++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/src/Servant/API/Capture.hs b/src/Servant/API/Capture.hs
index f6841911..fb27600c 100644
--- a/src/Servant/API/Capture.hs
+++ b/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
diff --git a/src/Servant/API/ReqBody.hs b/src/Servant/API/ReqBody.hs
index 2479844a..5067fa85 100644
--- a/src/Servant/API/ReqBody.hs
+++ b/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