@@ -239,9 +239,125 @@ import qualified Network.HTTP.Types as Y
239239--
240240-- To make an HTTP request you need only one function: 'req'.
241241
242−-- | Make an HTTP request.
242+-- | Make an HTTP request. The function takes 5 arguments, 4 of which
243+-- specify required parameters and the final 'Option' argument is a
244+-- collection of optional parameters.
243245--
244−-- TODO Finish docs of this function when the package is more developed.
246+-- Let's go through all the arguments first: @req method url body response
247+-- options@.
248+--
249+-- @method@ is an HTTP method such as 'GET' or 'POST'. The documentation has
250+-- a dedicated section about HTTP methods below.
251+--
252+-- @url@ is a URL that describes location of resource you want to interact
253+-- with. It's of type 'Url' (if you click the link it will tell everything
254+-- about construction of 'Url' things).
255+--
256+-- @body@ is a body option such as 'NoReqBody' or 'ReqBodyJson'. The
257+-- tutorial has a section about HTTP bodies, but usage in very
258+-- straightforward and should be clear from the examples below.
259+--
260+-- @response@ is a type hint how to make and interpret response of HTTP
261+-- request, out-of-the-box it can be the following: 'ignoreResponse',
262+-- 'jsonResponse', 'bsResponse' (to get strict 'ByteString'), 'lbsResponse'
263+-- (to get lazy 'BL.ByteString'), and 'returnRequest' (makes no request,
264+-- just returns response, used for testing).
265+--
266+-- Finally @options@ is a 'Monoid' that holds a composite 'Option' for all
267+-- other optional things like query parameters, headers, non-standard port
268+-- number, etc. There are quite a few things you can put there, see
269+-- corresponding section in the documentation. If you don't need anything at
270+-- all, pass 'mempty'.
271+--
272+-- See the examples below to get on the speed very quickly.
273+--
274+-- ==== __Examples__
275+--
276+-- First, this is a piece of boilerplate that should be in place before you
277+-- try the examples:
278+--
279+-- > {-# LANGUAGE OverloadedStrings #-}
280+-- >
281+-- > module Main (main) where
282+-- >
283+-- > import Control.Exception (throwIO)
284+-- > import Control.Monad
285+-- > import Data.Aeson
286+-- > import Data.Maybe (fromJust)
287+-- > import Data.Monoid ((<>))
288+-- > import Data.Text (Text)
289+-- > import GHC.Generics
290+-- > import Network.HTTP.Req
291+-- > import qualified Data.ByteString.Char8 as B
292+-- >
293+-- > instance MonadHttp IO where
294+-- > handleHttpException = throwIO
295+--
296+-- We will be making requests against the <https://httpbin.org> service.
297+--
298+-- Make a GET request, grab 5 random bytes:
299+--
300+-- > main :: IO ()
301+-- > main = do
302+-- > let n :: Int
303+-- > n = 5
304+-- > bs <- req GET (https "httpbin.org" /: "bytes" /~ n) NoReqBody bsResponse mempty
305+-- > B.putStrLn (responseBody bs)
306+--
307+-- The same, but now we use a query parameter named @\"seed\"@ to control
308+-- seed of the generator:
309+--
310+-- > main :: IO ()
311+-- > main = do
312+-- > let n, seed :: Int
313+-- > n = 5
314+-- > seed = 100
315+-- > bs <- req GET (https "httpbin.org" /: "bytes" /~ n) NoReqBody bsResponse $
316+-- > "seed" =: seed
317+-- > B.putStrLn (responseBody bs)
318+--
319+-- POST JSON data and get some info about the POST request:
320+--
321+-- > data MyData = MyData
322+-- > { size :: Int
323+-- > , color :: Text
324+-- > } deriving (Show, Generic)
325+-- >
326+-- > instance ToJSON MyData
327+-- > instance FromJSON MyData
328+-- >
329+-- > main :: IO ()
330+-- > main = do
331+-- > let myData = MyData
332+-- > { size = 6
333+-- > , color = "Green" }
334+-- > v <- req POST (https "httpbin.org" /: "post") (ReqBodyJson myData) jsonResponse mempty
335+-- > print (responseBody v :: Value)
336+--
337+-- Sending URL-encoded body:
338+--
339+-- > main :: IO ()
340+-- > main = do
341+-- > let params =
342+-- > "foo" =: ("bar" :: Text) <>
343+-- > queryFlag "baz"
344+-- > response <- req POST (https "httpbin.org" /: "post") (ReqBodyUrlEnc params) jsonResponse mempty
345+-- > print (responseBody response :: Value)
346+--
347+-- Using various optional parameters and URL that is not known in advance:
348+--
349+-- > main :: IO ()
350+-- > main = do
351+-- > -- This is an example of what to do when URL is given dynamically. Of
352+-- > -- course in a real application you may not want to use 'fromJust'.
353+-- > let (url, options) = fromJust (parseUrlHttps "https://httpbin.org/get?foo=bar")
354+-- > response <- req GET url NoReqBody jsonResponse $
355+-- > "from" =: (15 :: Int) <>
356+-- > "to" =: (67 :: Int) <>
357+-- > basicAuth "username" "password" <>
358+-- > options <> -- contains the ?foo=bar part
359+-- > port 443 -- here you can put any port of course
360+-- > print (responseBody response :: Value)
245361
246362req
247363 :: forall m method body response scheme.
@@ -499,16 +615,16 @@ instance HttpMethod method => RequestComponent (Womb "method" method) where
499615-- $url
500616--
501617-- We use 'Url's which are correct by construction, see 'Url'. To build a
502−-- 'Url' from 'ByteString', use 'parseUrlHttp' or 'parseUrlHttps'.
618+-- 'Url' from a 'ByteString', use 'parseUrlHttp' or 'parseUrlHttps'.
503619
504620-- | Request's 'Url'. Start constructing your 'Url' with 'http' or 'https'
505621-- specifying the scheme and host at the same time. Then use the @('/~')@
506622-- and @('/:')@ operators to grow path one piece at a time. Every single
507−-- piece of path will be url(percent)-encoded, so @('/:')@ is the only way
508−-- to have forward slashes between path segments. This approach makes
509−-- working with dynamic path segments easy and safe. See examples below how
510−-- to represent various 'Url's (make sure the @OverloadedStrings@ language
511−-- extension is enabled).
623+-- piece of path will be url(percent)-encoded, so using @('/~')@ and
624+-- @('/:')@ is the only way to have forward slashes between path segments.
625+-- This approach makes working with dynamic path segments easy and safe. See
626+-- examples below how to represent various 'Url's (make sure the
627+-- @OverloadedStrings@ language extension is enabled).
512628--
513629-- ==== __Examples__
514630--
@@ -675,17 +791,10 @@ instance HttpBody ReqBodyLbs where
675791-- | Form URL-encoded body. This can hold a collection of parameters which
676792-- are encoded similarly to query parameters at the end of query string,
677793-- with the only difference that they are stored in request body. The
678−-- similarity is reflected in API as well, as you can use the same
794+-- similarity is reflected in the API as well, as you can use the same
679795-- combinators you would use to add query parameters: @('=:')@ and
680796-- 'queryFlag'.
681797--
682−-- Here is an example of use:
683−--
684−-- > req POST (https "httpbin.org" /: "post") (ReqBodyUrlEnc params) mempty
685−-- > where params =
686−-- > "foo" =: "bar" <>
687−-- > queryFlag "baz"
688−--
689798-- This body option sets the @Content-Type@ header to
690799-- @\"application/x-www-from-urlencoded\"@ value.
691800
@@ -1051,7 +1160,7 @@ instance FromJSON a => HttpResponse (JsonResponse a) where
10511160-- | Use this as the forth argument of 'req' to specify that you want it to
10521161-- return the 'JsonResponse' interpretation.
10531162
1054−jsonResponse :: Proxy JsonResponse
1163+jsonResponse :: Proxy (JsonResponse a)
10551164jsonResponse = Proxy
10561165
10571166-- | Make a request and interpret body of response as a strict 'ByteString'.