eeva/servant
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Changes to docs as suggested

Browse source
This commit is contained in:
David Turner 2017-05-17 08:24:04 +00:00
parent aa3716b6aa
commit 8b993b9d11
5 changed files with 13 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
doc/tutorial/ApiType.lhs
View file

@ -345,7 +345,8 @@ type UserAPI12Alone = UserAPI12 EmptyAPI
``` ```
This also works well as a placeholder for unfinished parts of an API while it This also works well as a placeholder for unfinished parts of an API while it
is under development. is under development, for when you know that there should be _something_ there
but you don't yet know what. Think of it as similar to the unit type `()`.
### Interoperability with `wai`: `Raw` ### Interoperability with `wai`: `Raw`

5
doc/tutorial/Client.lhs
View file

@ -93,8 +93,9 @@ position :<|> hello :<|> marketing = client api
`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. `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.
If there is an `EmptyAPI` within your API, this matches the `EmptyClient` If you have an `EmptyAPI` in your API, servant-client will hand you a value of
constructor: type `EmptyClient` in the corresponding slot, where `data EmptyClient =
EmptyClient`, as a way to indicate that you can't do anything useful with it.
``` haskell ignore ``` haskell ignore
type API' = API :<|> EmptyAPI type API' = API :<|> EmptyAPI

2
doc/tutorial/Docs.lhs
View file

@ -89,6 +89,8 @@ instance ToSample Email where
``` ```
Types 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. Types 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.
The `EmptyAPI` combinator needs no special treatment as it generates no
documentation: an empty API has no endpoints to document.
With all of this, we can derive docs for our API. With all of this, we can derive docs for our API.

3
doc/tutorial/Javascript.lhs
View file

@ -149,6 +149,9 @@ Why two different API types, proxies and servers though? Simply because we
don't want to generate javascript functions for the `Raw` part of our API type, don't want to generate javascript functions for the `Raw` part of our API type,
so we need a `Proxy` for our API type `API'` without its `Raw` endpoint. so we need a `Proxy` for our API type `API'` without its `Raw` endpoint.
The `EmptyAPI` combinator needs no special treatment as it generates no
Javascript functions: an empty API has no endpoints to access.
Very similarly to how one can derive haskell functions, we can derive the Very similarly to how one can derive haskell functions, we can derive the
javascript with just a simple function call to `jsForAPI` from javascript with just a simple function call to `jsForAPI` from
`Servant.JS`. `Servant.JS`.

5
doc/tutorial/Server.lhs
View file

@ -1020,8 +1020,9 @@ serverFor = error "..."
-- or the mailing list if you get stuck! -- or the mailing list if you get stuck!
``` ```
If the API contains the `EmptyAPI` combinator, the corresponding server is When your API contains the `EmptyAPI` combinator, you'll want to use
called `emptyServer`: `emptyServer` in the corresponding slot for your server, which will simply fail
with 404 whenever a request reaches it:
``` haskell ``` haskell
type CombinedAPI2 = API :<|> "empty" :> EmptyAPI type CombinedAPI2 = API :<|> "empty" :> EmptyAPI