@@ -10,12 +10,56 @@
1010-- This is an easy-to-use, type-safe, expandable, high-level HTTP library
1111-- that just works without fooling around.
1212--
13+-- /(A modest intro goes here, click on 'req' to start making requests.)/
14+--
15+-- What does the “easy-to-use” phrase mean? It means that the library is
16+-- designed to be beginner-friendly, so it's simple to add it to your monad
17+-- stack, intuitive to work with, well-documented, and does not get in your
18+-- way. On this path certain compromises were made. For example one cannot
19+-- currently modify 'L.ManagerSettings' of default manager because the
20+-- library always use the same implicit global manager for simplicity and
21+-- maximal connection sharing. There is a way to use your own manager with
22+-- different settings, but it requires a bit more typing. Just like with my
23+-- other library, Megaparsec, I spent considerable amount of time working on
24+-- the documentation and examples, because doing HTTP requests is a common
25+-- task and Haskell library for this should be very approachable and clear
26+-- to beginners.
27+--
28+-- “Type-safe” means that the library is protective and eliminates certain
29+-- class of errors compared to alternative libraries like @wreq@ or vanilla
30+-- @http-client@. For example it makes sure user does not send request body
31+-- when using methods like 'GET' or 'DELETE', minimizes amount of implicit
32+-- assumptions making user specify his\/her intentions in explicit form (for
33+-- example it's not possible to avoid specifying body or method of a
34+-- request). It carefully hides underlying types from lower-level
35+-- @http-client@ package because it's not type safe enough (for example
36+-- 'L.Request' is an instance of 'Data.String.IsString' and if it's
37+-- malformed, it will blow up at run-time).
38+--
39+-- “Expandable” refers to the ability of the library to be expanded without
40+-- ugly hacking. For example it's possible to define your own HTTP methods,
41+-- new ways to construct body of request, new authorization options, new
42+-- ways to actually perform request and how to represent\/parse it. As user
43+-- extends the library to satisfy his\/her special needs, the new solutions
44+-- work just like built-ins. That said, all common cases are covered by the
45+-- library out-of-the-box.
46+--
47+-- “High-level” means that there are less details to worry about. The
48+-- library is a result of my experiences as a Haskell consultant, working
49+-- for several clients who have very different projects and so the library
50+-- adapts easily to any particular style of writing Haskell applications.
51+-- For example some people prefer throwing exceptions, while others are
52+-- concerned with purity: just define 'handleHttpException' accordingly when
53+-- making your monad instance of 'MonadHttp' and it will play seamlessly.
54+-- Finally, the library cuts boilerplate considerably and helps write
55+-- concise, easy to read code, thanks to its minimal and very uniform API.
56+--
1357-- The documentation below is structured in such a way that most important
1458-- information goes first: you learn how to do HTTP requests, then how to
1559-- embed them any monad you have, then it goes on giving you details about
1660-- less-common things you may want to know about. The documentation is
17−-- written with sufficient coverage of details and with examples, it's
18−-- designed to be a complete tutorial on its own.
61+-- written with sufficient coverage of details and examples, it's designed
62+-- to be a complete tutorial on its own.
1963--
2064-- The library uses the following well-known and mature packages under the
2165-- hood to guarantee you best experience without bugs or other funny
@@ -106,7 +150,6 @@ import Data.Text (Text)
106150import Data.Typeable (Typeable)
107151import GHC.Generics
108152import GHC.TypeLits
109−-- import Numeric.Natural
110153import System.IO.Unsafe (unsafePerformIO)
111154import qualified Data.ByteString as B
112155import qualified Data.ByteString.Lazy as BL
@@ -187,8 +230,9 @@ class MonadIO m => MonadHttp m where
187230
188231 -- | This method describes how to deal with 'L.HttpException' that was
189232 -- caught by the library. One option is to re-throw it if you are OK with
190− -- exceptions, but if you prefer working with something like 'MonadError',
191− -- this is the right place to pass it to 'throwError' for example.
233+ -- exceptions, but if you prefer working with something like
234+ -- 'Control.Monad.Error.MonadError', this is the right place to pass it to
235+ -- 'Control.Monad.Error.throwError' for example.
192236
193237 handleHttpException :: L.HttpException -> m a
194238
@@ -196,8 +240,8 @@ class MonadIO m => MonadHttp m where
196240 -- implementation returns its 'def' value, which is described in the
197241 -- documentation for the type. Common usage pattern with manually defined
198242 -- 'getHttpConfig' is to return some hard-coded value, or value extracted
199− -- from 'MonadReader' if a more flexible approach to configuration is
200− -- desirable.
243+ -- from 'Control.Monad.Reader.MonadReader' if a more flexible approach to
244+ -- configuration is desirable.
201245
202246 getHttpConfig :: m HttpConfig
203247 getHttpConfig = return def
@@ -316,7 +360,7 @@ instance HttpMethod PATCH where
316360-- > data COPY = COPY
317361-- >
318362-- > instance HttpMethod COPY where
319−-- > type AllowsMody COPY = 'CanHaveBody
363+-- > type AllowsBody COPY = 'CanHaveBody
320364-- > httpMethodName Proxy = "COPY"
321365
322366class HttpMethod a where