ff40b32 · typeable/servant

git.iko.soy/typeable/servant

Merge pull request #504 from haskell-servant/jkarni/doc-fixes

Doc fixes

commitff40b327bc752cd68b2989d660341a1d7a017822 authorJulian Arni <jkarni@gmail.com> dateThu 12 May 2016, 09:53 (10 years ago) parentd8a4cce aed6f7b

3 files changed+58−64

compare with master

unifiedsplit

doc/tutorial/Server.lhs+26−26 doc/tutorial/index.rst+2−8 servant-server/src/Servant/Server/Internal/ServantErr.hs+30−30

doc/tutorial/Server.lhs+26−26

@@ -809,7 +809,7 @@ type UserAPI3 = -- view the user with given userid, in JSON

809809 Capture "userid" Int :> Get '[JSON] User

810810

811811 :<|> -- delete the user with given userid. empty response

812− Capture "userid" Int :> Delete '[] ()

812+ Capture "userid" Int :> DeleteNoContent '[JSON] NoContent

813813```

814814

815815We can instead factor out the `userid`:

@@ -817,7 +817,7 @@ We can instead factor out the `userid`:

817817``` haskell

818818type UserAPI4 = Capture "userid" Int :>

819819 ( Get '[JSON] User

820− :<|> Delete '[] ()

820+ :<|> DeleteNoContent '[JSON] NoContent

821821 )

822822```

823823

@@ -826,10 +826,10 @@ corresponding `Server`:

826826

827827``` haskell ignore

828828Server UserAPI3 = (Int -> Handler User)

829− :<|> (Int -> Handler ())

829+ :<|> (Int -> Handler NoContent)

830830

831831Server UserAPI4 = Int -> ( Handler User

832− :<|> Handler ()

832+ :<|> Handler NoContent

833833 )

834834```

835835

@@ -844,7 +844,7 @@ server8 = getUser :<|> deleteUser

844844 where getUser :: Int -> Handler User

845845 getUser _userid = error "..."

846846

847− deleteUser :: Int -> Handler ()

847+ deleteUser :: Int -> Handler NoContent

848848 deleteUser _userid = error "..."

849849

850850-- notice how getUser and deleteUser

@@ -856,7 +856,7 @@ server9 userid = getUser userid :<|> deleteUser userid

856856 where getUser :: Int -> Handler User

857857 getUser = error "..."

858858

859− deleteUser :: Int -> Handler ()

859+ deleteUser :: Int -> Handler NoContent

860860 deleteUser = error "..."

861861```

862862

@@ -875,13 +875,13 @@ type API1 = "users" :>

875875-- we factor out the Request Body

876876type API2 = ReqBody '[JSON] User :>

877877 ( Get '[JSON] User -- just display the same user back, don't register it

878− :<|> Post '[JSON] () -- register the user. empty response

878+ :<|> PostNoContent '[JSON] NoContent -- register the user. empty response

879879 )

880880

881881-- we factor out a Header

882882type API3 = Header "Authorization" Token :>

883883 ( Get '[JSON] SecretData -- get some secret data, if authorized

884− :<|> ReqBody '[JSON] SecretData :> Post '[] () -- add some secret data, if authorized

884+ :<|> ReqBody '[JSON] SecretData :> PostNoContent '[JSON] NoContent -- add some secret data, if authorized

885885 )

886886

887887newtype Token = Token ByteString

@@ -894,11 +894,11 @@ API type only at the end.

894894``` haskell

895895type UsersAPI =

896896 Get '[JSON] [User] -- list users

897− :<|> ReqBody '[JSON] User :> Post '[] () -- add a user

897+ :<|> ReqBody '[JSON] User :> PostNoContent '[JSON] NoContent -- add a user

898898 :<|> Capture "userid" Int :>

899899 ( Get '[JSON] User -- view a user

900− :<|> ReqBody '[JSON] User :> Put '[] () -- update a user

901− :<|> Delete '[] () -- delete a user

900+ :<|> ReqBody '[JSON] User :> PutNoContent '[JSON] NoContent -- update a user

901+ :<|> DeleteNoContent '[JSON] NoContent -- delete a user

902902 )

903903

904904usersServer :: Server UsersAPI

@@ -907,7 +907,7 @@ usersServer = getUsers :<|> newUser :<|> userOperations

907907 where getUsers :: Handler [User]

908908 getUsers = error "..."

909909

910− newUser :: User -> Handler ()

910+ newUser :: User -> Handler NoContent

911911 newUser = error "..."

912912

913913 userOperations userid =

@@ -917,21 +917,21 @@ usersServer = getUsers :<|> newUser :<|> userOperations

917917 viewUser :: Int -> Handler User

918918 viewUser = error "..."

919919

920− updateUser :: Int -> User -> Handler ()

920+ updateUser :: Int -> User -> Handler NoContent

921921 updateUser = error "..."

922922

923− deleteUser :: Int -> Handler ()

923+ deleteUser :: Int -> Handler NoContent

924924 deleteUser = error "..."

925925```

926926

927927``` haskell

928928type ProductsAPI =

929929 Get '[JSON] [Product] -- list products

930− :<|> ReqBody '[JSON] Product :> Post '[] () -- add a product

930+ :<|> ReqBody '[JSON] Product :> PostNoContent '[JSON] NoContent -- add a product

931931 :<|> Capture "productid" Int :>

932932 ( Get '[JSON] Product -- view a product

933− :<|> ReqBody '[JSON] Product :> Put '[] () -- update a product

934− :<|> Delete '[] () -- delete a product

933+ :<|> ReqBody '[JSON] Product :> PutNoContent '[JSON] NoContent -- update a product

934+ :<|> DeleteNoContent '[JSON] NoContent -- delete a product

935935 )

936936

937937data Product = Product { productId :: Int }

@@ -942,7 +942,7 @@ productsServer = getProducts :<|> newProduct :<|> productOperations

942942 where getProducts :: Handler [Product]

943943 getProducts = error "..."

944944

945− newProduct :: Product -> Handler ()

945+ newProduct :: Product -> Handler NoContent

946946 newProduct = error "..."

947947

948948 productOperations productid =

@@ -952,10 +952,10 @@ productsServer = getProducts :<|> newProduct :<|> productOperations

952952 viewProduct :: Int -> Handler Product

953953 viewProduct = error "..."

954954

955− updateProduct :: Int -> Product -> Handler ()

955+ updateProduct :: Int -> Product -> Handler NoContent

956956 updateProduct = error "..."

957957

958− deleteProduct :: Int -> Handler ()

958+ deleteProduct :: Int -> Handler NoContent

959959 deleteProduct = error "..."

960960```

961961

@@ -975,20 +975,20 @@ abstract that away:

975975-- indexed by values of type 'i'

976976type APIFor a i =

977977 Get '[JSON] [a] -- list 'a's

978− :<|> ReqBody '[JSON] a :> Post '[] () -- add an 'a'

978+ :<|> ReqBody '[JSON] a :> PostNoContent '[JSON] NoContent -- add an 'a'

979979 :<|> Capture "id" i :>

980980 ( Get '[JSON] a -- view an 'a' given its "identifier" of type 'i'

981− :<|> ReqBody '[JSON] a :> Put '[] () -- update an 'a'

982− :<|> Delete '[] () -- delete an 'a'

981+ :<|> ReqBody '[JSON] a :> PutNoContent '[JSON] NoContent -- update an 'a'

982+ :<|> DeleteNoContent '[JSON] NoContent -- delete an 'a'

983983 )

984984

985985-- Build the appropriate 'Server'

986986-- given the handlers of the right type.

987987serverFor :: Handler [a] -- handler for listing of 'a's

988− -> (a -> Handler ()) -- handler for adding an 'a'

988+ -> (a -> Handler NoContent) -- handler for adding an 'a'

989989 -> (i -> Handler a) -- handler for viewing an 'a' given its identifier of type 'i'

990− -> (i -> a -> Handler ()) -- updating an 'a' with given id

991− -> (i -> Handler ()) -- deleting an 'a' given its id

990+ -> (i -> a -> Handler NoContent) -- updating an 'a' with given id

991+ -> (i -> Handler NoContent) -- deleting an 'a' given its id

992992 -> Server (APIFor a i)

993993serverFor = error "..."

994994-- implementation left as an exercise. contact us on IRC

doc/tutorial/index.rst+2−8

@@ -3,14 +3,8 @@ Tutorial

44This is an introductory tutorial to **servant**.

6−.. note::

7− This tutorial is for the latest version of servant. The tutorial for

8− servant-0.4 can be viewed

9− `here <https://haskell-servant.github.io/tutorial/>`_.

10−

11−(Any comments, issues or feedback about the tutorial can be handled

12−through

13−`servant's issue tracker <http://github.com/haskell-servant/servant/issues>`_.)

6+(Any comments, issues or feedback about the tutorial can be submitted

7+to `servant's issue tracker <http://github.com/haskell-servant/servant/issues>`_.)

148

159

1610.. toctree::

servant-server/src/Servant/Server/Internal/ServantErr.hs+30−30

@@ -31,7 +31,7 @@ responseServantErr ServantErr{..} = responseLBS status errHeaders errBody

3131-- Example:

3232--

3333-- > failingHandler :: Handler ()

34−-- > failingHandler = throwErr $ err300 { errBody = "I can't choose." }

34+-- > failingHandler = throwError $ err300 { errBody = "I can't choose." }

3535--

3636err300 :: ServantErr

3737err300 = ServantErr { errHTTPCode = 300

@@ -45,7 +45,7 @@ err300 = ServantErr { errHTTPCode = 300

4545-- Example:

4646--

4747-- > failingHandler :: Handler ()

48−-- > failingHandler = throwErr err301

48+-- > failingHandler = throwError err301

4949--

5050err301 :: ServantErr

5151err301 = ServantErr { errHTTPCode = 301

@@ -59,7 +59,7 @@ err301 = ServantErr { errHTTPCode = 301

5959-- Example:

6060--

6161-- > failingHandler :: Handler ()

62−-- > failingHandler = throwErr err302

62+-- > failingHandler = throwError err302

6363--

6464err302 :: ServantErr

6565err302 = ServantErr { errHTTPCode = 302

@@ -73,7 +73,7 @@ err302 = ServantErr { errHTTPCode = 302

7373-- Example:

7474--

7575-- > failingHandler :: Handler ()

76−-- > failingHandler = throwErr err303

76+-- > failingHandler = throwError err303

7777--

7878err303 :: ServantErr

7979err303 = ServantErr { errHTTPCode = 303

@@ -87,7 +87,7 @@ err303 = ServantErr { errHTTPCode = 303

8787-- Example:

8888--

8989-- > failingHandler :: Handler ()

90−-- > failingHandler = throwErr err304

90+-- > failingHandler = throwError err304

9191--

9292err304 :: ServantErr

9393err304 = ServantErr { errHTTPCode = 304

@@ -101,7 +101,7 @@ err304 = ServantErr { errHTTPCode = 304

101101-- Example:

102102--

103103-- > failingHandler :: Handler ()

104−-- > failingHandler = throwErr err305

104+-- > failingHandler = throwError err305

105105--

106106err305 :: ServantErr

107107err305 = ServantErr { errHTTPCode = 305

@@ -115,7 +115,7 @@ err305 = ServantErr { errHTTPCode = 305

115115-- Example:

116116--

117117-- > failingHandler :: Handler ()

118−-- > failingHandler = throwErr err307

118+-- > failingHandler = throwError err307

119119--

120120err307 :: ServantErr

121121err307 = ServantErr { errHTTPCode = 307

@@ -129,7 +129,7 @@ err307 = ServantErr { errHTTPCode = 307

129129-- Example:

130130--

131131-- > failingHandler :: Handler ()

132−-- > failingHandler = throwErr $ err400 { errBody = "Your request makes no sense to me." }

132+-- > failingHandler = throwError $ err400 { errBody = "Your request makes no sense to me." }

133133--

134134err400 :: ServantErr

135135err400 = ServantErr { errHTTPCode = 400

@@ -143,7 +143,7 @@ err400 = ServantErr { errHTTPCode = 400

143143-- Example:

144144--

145145-- > failingHandler :: Handler ()

146−-- > failingHandler = throwErr $ err401 { errBody = "Your credentials are invalid." }

146+-- > failingHandler = throwError $ err401 { errBody = "Your credentials are invalid." }

147147--

148148err401 :: ServantErr

149149err401 = ServantErr { errHTTPCode = 401

@@ -157,7 +157,7 @@ err401 = ServantErr { errHTTPCode = 401

157157-- Example:

158158--

159159-- > failingHandler :: Handler ()

160−-- > failingHandler = throwErr $ err402 { errBody = "You have 0 credits. Please give me $$$." }

160+-- > failingHandler = throwError $ err402 { errBody = "You have 0 credits. Please give me $$$." }

161161--

162162err402 :: ServantErr

163163err402 = ServantErr { errHTTPCode = 402

@@ -171,7 +171,7 @@ err402 = ServantErr { errHTTPCode = 402

171171-- Example:

172172--

173173-- > failingHandler :: Handler ()

174−-- > failingHandler = throwErr $ err403 { errBody = "Please login first." }

174+-- > failingHandler = throwError $ err403 { errBody = "Please login first." }

175175--

176176err403 :: ServantErr

177177err403 = ServantErr { errHTTPCode = 403

@@ -185,7 +185,7 @@ err403 = ServantErr { errHTTPCode = 403

185185-- Example:

186186--

187187-- > failingHandler :: Handler ()

188−-- > failingHandler = throwErr $ err404 { errBody = "(╯°□°）╯︵ ┻━┻)." }

188+-- > failingHandler = throwError $ err404 { errBody = "(╯°□°）╯︵ ┻━┻)." }

189189--

190190err404 :: ServantErr

191191err404 = ServantErr { errHTTPCode = 404

@@ -199,7 +199,7 @@ err404 = ServantErr { errHTTPCode = 404

199199-- Example:

200200--

201201-- > failingHandler :: Handler ()

202−-- > failingHandler = throwErr $ err405 { errBody = "Your account privileges does not allow for this. Please pay $$$." }

202+-- > failingHandler = throwError $ err405 { errBody = "Your account privileges does not allow for this. Please pay $$$." }

203203--

204204err405 :: ServantErr

205205err405 = ServantErr { errHTTPCode = 405

@@ -213,7 +213,7 @@ err405 = ServantErr { errHTTPCode = 405

213213-- Example:

214214--

215215-- > failingHandler :: Handler ()

216−-- > failingHandler = throwErr err406

216+-- > failingHandler = throwError err406

217217--

218218err406 :: ServantErr

219219err406 = ServantErr { errHTTPCode = 406

@@ -227,7 +227,7 @@ err406 = ServantErr { errHTTPCode = 406

227227-- Example:

228228--

229229-- > failingHandler :: Handler ()

230−-- > failingHandler = throwErr err407

230+-- > failingHandler = throwError err407

231231--

232232err407 :: ServantErr

233233err407 = ServantErr { errHTTPCode = 407

@@ -241,7 +241,7 @@ err407 = ServantErr { errHTTPCode = 407

241241-- Example:

242242--

243243-- > failingHandler :: Handler ()

244−-- > failingHandler = throwErr $ err409 { errBody = "Transaction conflicts with 59879cb56c7c159231eeacdd503d755f7e835f74" }

244+-- > failingHandler = throwError $ err409 { errBody = "Transaction conflicts with 59879cb56c7c159231eeacdd503d755f7e835f74" }

245245--

246246err409 :: ServantErr

247247err409 = ServantErr { errHTTPCode = 409

@@ -255,7 +255,7 @@ err409 = ServantErr { errHTTPCode = 409

255255-- Example:

256256--

257257-- > failingHandler :: Handler ()

258−-- > failingHandler = throwErr $ err410 { errBody = "I know it was here at some point, but.. I blame bad luck." }

258+-- > failingHandler = throwError $ err410 { errBody = "I know it was here at some point, but.. I blame bad luck." }

259259--

260260err410 :: ServantErr

261261err410 = ServantErr { errHTTPCode = 410

@@ -269,7 +269,7 @@ err410 = ServantErr { errHTTPCode = 410

269269-- Example:

270270--

271271-- > failingHandler :: Handler ()

272−-- > failingHandler = throwErr err411

272+-- > failingHandler = throwError err411

273273--

274274err411 :: ServantErr

275275err411 = ServantErr { errHTTPCode = 411

@@ -283,7 +283,7 @@ err411 = ServantErr { errHTTPCode = 411

283283-- Example:

284284--

285285-- > failingHandler :: Handler ()

286−-- > failingHandler = throwErr $ err412 { errBody = "Precondition fail: x < 42 && y > 57" }

286+-- > failingHandler = throwError $ err412 { errBody = "Precondition fail: x < 42 && y > 57" }

287287--

288288err412 :: ServantErr

289289err412 = ServantErr { errHTTPCode = 412

@@ -297,7 +297,7 @@ err412 = ServantErr { errHTTPCode = 412

297297-- Example:

298298--

299299-- > failingHandler :: Handler ()

300−-- > failingHandler = throwErr $ err413 { errBody = "Request exceeded 64k." }

300+-- > failingHandler = throwError $ err413 { errBody = "Request exceeded 64k." }

301301--

302302err413 :: ServantErr

303303err413 = ServantErr { errHTTPCode = 413

@@ -311,7 +311,7 @@ err413 = ServantErr { errHTTPCode = 413

311311-- Example:

312312--

313313-- > failingHandler :: Handler ()

314−-- > failingHandler = throwErr $ err414 { errBody = "Maximum length is 64." }

314+-- > failingHandler = throwError $ err414 { errBody = "Maximum length is 64." }

315315--

316316err414 :: ServantErr

317317err414 = ServantErr { errHTTPCode = 414

@@ -325,7 +325,7 @@ err414 = ServantErr { errHTTPCode = 414

325325-- Example:

326326--

327327-- > failingHandler :: Handler ()

328−-- > failingHandler = throwErr $ err415 { errBody = "Supported media types: gif, png" }

328+-- > failingHandler = throwError $ err415 { errBody = "Supported media types: gif, png" }

329329--

330330err415 :: ServantErr

331331err415 = ServantErr { errHTTPCode = 415

@@ -339,7 +339,7 @@ err415 = ServantErr { errHTTPCode = 415

339339-- Example:

340340--

341341-- > failingHandler :: Handler ()

342−-- > failingHandler = throwErr $ err416 { errBody = "Valid range is [0, 424242]." }

342+-- > failingHandler = throwError $ err416 { errBody = "Valid range is [0, 424242]." }

343343--

344344err416 :: ServantErr

345345err416 = ServantErr { errHTTPCode = 416

@@ -353,7 +353,7 @@ err416 = ServantErr { errHTTPCode = 416

353353-- Example:

354354--

355355-- > failingHandler :: Handler ()

356−-- > failingHandler = throwErr $ err417 { errBody = "I found a quux in the request. This isn't going to work." }

356+-- > failingHandler = throwError $ err417 { errBody = "I found a quux in the request. This isn't going to work." }

357357--

358358err417 :: ServantErr

359359err417 = ServantErr { errHTTPCode = 417

@@ -367,7 +367,7 @@ err417 = ServantErr { errHTTPCode = 417

367367-- Example:

368368--

369369-- > failingHandler :: Handler ()

370−-- > failingHandler = throwErr $ err500 { errBody = "Exception in module A.B.C:55. Have a great day!" }

370+-- > failingHandler = throwError $ err500 { errBody = "Exception in module A.B.C:55. Have a great day!" }

371371--

372372err500 :: ServantErr

373373err500 = ServantErr { errHTTPCode = 500

@@ -381,7 +381,7 @@ err500 = ServantErr { errHTTPCode = 500

381381-- Example:

382382--

383383-- > failingHandler :: Handler ()

384−-- > failingHandler = throwErr $ err501 { errBody = "/v1/foo is not supported with quux in the request." }

384+-- > failingHandler = throwError $ err501 { errBody = "/v1/foo is not supported with quux in the request." }

385385--

386386err501 :: ServantErr

387387err501 = ServantErr { errHTTPCode = 501

@@ -395,7 +395,7 @@ err501 = ServantErr { errHTTPCode = 501

395395-- Example:

396396--

397397-- > failingHandler :: Handler ()

398−-- > failingHandler = throwErr $ err502 { errBody = "Tried gateway foo, bar, and baz. None responded." }

398+-- > failingHandler = throwError $ err502 { errBody = "Tried gateway foo, bar, and baz. None responded." }

399399--

400400err502 :: ServantErr

401401err502 = ServantErr { errHTTPCode = 502

@@ -409,7 +409,7 @@ err502 = ServantErr { errHTTPCode = 502

409409-- Example:

410410--

411411-- > failingHandler :: Handler ()

412−-- > failingHandler = throwErr $ err503 { errBody = "We're rewriting in PHP." }

412+-- > failingHandler = throwError $ err503 { errBody = "We're rewriting in PHP." }

413413--

414414err503 :: ServantErr

415415err503 = ServantErr { errHTTPCode = 503

@@ -423,7 +423,7 @@ err503 = ServantErr { errHTTPCode = 503

423423-- Example:

424424--

425425-- > failingHandler :: Handler ()

426−-- > failingHandler = throwErr $ err504 { errBody = "Backend foobar did not respond in 5 seconds." }

426+-- > failingHandler = throwError $ err504 { errBody = "Backend foobar did not respond in 5 seconds." }

427427--

428428err504 :: ServantErr

429429err504 = ServantErr { errHTTPCode = 504

@@ -437,7 +437,7 @@ err504 = ServantErr { errHTTPCode = 504

437437-- Example usage:

438438--

439439-- > failingHandler :: Handler ()

440−-- > failingHandler = throwErr $ err505 { errBody = "I support HTTP/4.0 only." }

440+-- > failingHandler = throwError $ err505 { errBody = "I support HTTP/4.0 only." }

441441--

442442err505 :: ServantErr

443443err505 = ServantErr { errHTTPCode = 505