@@ -17,11 +17,25 @@ import Servant.Common.Req
1717import Servant.Docs
1818import Servant.Server
1919
20−-- | Endpoint for simple GET requests. The server doesn't receive any arguments
21−-- and serves the contained type as JSON.
20+-- | Endpoint for simple GET requests. Serves the result as JSON.
21+--
22+-- Example:
23+--
24+-- > type MyApi = "books" :> Get [Book]
2225data Get a
2326 deriving Typeable
2427
28+-- | When implementing the handler for a 'Get' endpoint,
29+-- just like for 'Servant.API.Delete.Delete', 'Servant.API.Post.Post'
30+-- and 'Servant.API.Put.Put', the handler code runs in the
31+-- @EitherT (Int, String) IO@ monad, where the 'Int' represents
32+-- the status code and the 'String' a message, returned in case of
33+-- failure. You can quite handily use 'Control.Monad.Trans.EitherT.left'
34+-- to quickly fail if some conditions are not met.
35+--
36+-- If successfully returning a value, we just require that its type has
37+-- a 'ToJSON' instance and servant takes care of encoding it for you,
38+-- yielding status code 200 along the way.
2539instance ToJSON result => HasServer (Get result) where
2640 type Server (Get result) = EitherT (Int, String) IO result
2741 route Proxy action request respond
@@ -36,6 +50,10 @@ instance ToJSON result => HasServer (Get result) where
3650 respond $ failWith WrongMethod
3751 | otherwise = respond $ failWith NotFound
3852
53+-- | If you have a 'Get' endpoint in your API, the client
54+-- side querying function that is created when calling 'client'
55+-- will just require an argument that specifies the scheme, host
56+-- and port to send the request to.
3957instance FromJSON result => HasClient (Get result) where
4058 type Client (Get result) = BaseUrl -> EitherT String IO result
4159 clientWithRoute Proxy req host =