@@ -17,10 +17,22 @@ import Servant.Common.Req
1717import Servant.Docs
1818import Servant.Server
1919
20−-- | Endpoint for PUT requests.
20+-- | Endpoint for PUT requests. The type @a@ is the type of the
21+-- response body that's returned.
2122data Put a
2223 deriving Typeable
2324
25+-- | When implementing the handler for a 'Put' endpoint,
26+-- just like for 'Servant.API.Delete.Delete', 'Servant.API.Get.Get'
27+-- and 'Servant.API.Post.Post', the handler code runs in the
28+-- @EitherT (Int, String) IO@ monad, where the 'Int' represents
29+-- the status code and the 'String' a message, returned in case of
30+-- failure. You can quite handily use 'Control.Monad.Trans.EitherT.left'
31+-- to quickly fail if some conditions are not met.
32+--
33+-- If successfully returning a value, we just require that its type has
34+-- a 'ToJSON' instance and servant takes care of encoding it for you,
35+-- yielding status code 200 along the way.
2436instance ToJSON a => HasServer (Put a) where
2537 type Server (Put a) = EitherT (Int, String) IO a
2638
@@ -37,6 +49,10 @@ instance ToJSON a => HasServer (Put a) where
3749
3850 | otherwise = respond $ failWith NotFound
3951
52+-- | If you have a 'Put' endpoint in your API, the client
53+-- side querying function that is created when calling 'client'
54+-- will just require an argument that specifies the scheme, host
55+-- and port to send the request to.
4056instance FromJSON a => HasClient (Put a) where
4157 type Client (Put a) = BaseUrl -> EitherT String IO a
4258