git.iko.soy/typeable/servant
on master help sign in
Changes to docs as suggested
commit8b993b9d114c376cfcf1762997107335d32f8d36 authorDavid Turner <dave.c.turner@gmail.com> dateWed 17 May 2017, 08:24 (9 years ago) parentaa3716b
5 files changed+13−5
compare with master
unifiedsplit
doc/tutorial/ApiType.lhs+2−1 doc/tutorial/Client.lhs+3−2 doc/tutorial/Docs.lhs+2 doc/tutorial/Javascript.lhs+3 doc/tutorial/Server.lhs+3−2
doc/tutorial/ApiType.lhs+2−1
@@ -345,7 +345,8 @@ type UserAPI12Alone = UserAPI12 EmptyAPI
345345```
346346
347347This also works well as a placeholder for unfinished parts of an API while it
348−is under development.
348+is under development, for when you know that there should be _something_ there
349+but you don't yet know what. Think of it as similar to the unit type `()`.
349350
350351### Interoperability with `wai`: `Raw`
351352
doc/tutorial/Client.lhs+3−2
@@ -93,8 +93,9 @@ position :<|> hello :<|> marketing = client api
9393
9494`client api` returns client functions for our _entire_ API, combined with `:<|>`, which we can pattern match on as above. You could say `client` "calculates" the correct type and number of client functions for the API type it is given (via a `Proxy`), as well as their implementations.
9595
96−If there is an `EmptyAPI` within your API, this matches the `EmptyClient`
97−constructor:
96+If you have an `EmptyAPI` in your API, servant-client will hand you a value of
97+type `EmptyClient` in the corresponding slot, where `data EmptyClient =
98+EmptyClient`, as a way to indicate that you can't do anything useful with it.
9899
99100``` haskell ignore
100101type API' = API :<|> EmptyAPI
doc/tutorial/Docs.lhs+2
@@ -89,6 +89,8 @@ instance ToSample Email where
8989```
9090
9191Types that are used as request or response bodies have to instantiate the `ToSample` typeclass which lets you specify one or more examples of values. `Capture`s and `QueryParam`s have to instantiate their respective `ToCapture` and `ToParam` classes and provide a name and some information about the concrete meaning of that argument, as illustrated in the code above.
92+The `EmptyAPI` combinator needs no special treatment as it generates no
93+documentation: an empty API has no endpoints to document.
9294
9395With all of this, we can derive docs for our API.
9496
doc/tutorial/Javascript.lhs+3
@@ -149,6 +149,9 @@ Why two different API types, proxies and servers though? Simply because we
149149don't want to generate javascript functions for the `Raw` part of our API type,
150150so we need a `Proxy` for our API type `API'` without its `Raw` endpoint.
151151
152+The `EmptyAPI` combinator needs no special treatment as it generates no
153+Javascript functions: an empty API has no endpoints to access.
154+
152155Very similarly to how one can derive haskell functions, we can derive the
153156javascript with just a simple function call to `jsForAPI` from
154157`Servant.JS`.
doc/tutorial/Server.lhs+3−2
@@ -1020,8 +1020,9 @@ serverFor = error "..."
10201020-- or the mailing list if you get stuck!
10211021```
10221022
1023−If the API contains the `EmptyAPI` combinator, the corresponding server is
1024−called `emptyServer`:
1023+When your API contains the `EmptyAPI` combinator, you'll want to use
1024+`emptyServer` in the corresponding slot for your server, which will simply fail
1025+with 404 whenever a request reaches it:
10251026
10261027``` haskell
10271028type CombinedAPI2 = API :<|> "empty" :> EmptyAPI