From 8b993b9d114c376cfcf1762997107335d32f8d36 Mon Sep 17 00:00:00 2001 From: David Turner Date: Wed, 17 May 2017 08:24:04 +0000 Subject: [PATCH] Changes to docs as suggested --- doc/tutorial/ApiType.lhs | 3 ++- doc/tutorial/Client.lhs | 5 +++-- doc/tutorial/Docs.lhs | 2 ++ doc/tutorial/Javascript.lhs | 3 +++ doc/tutorial/Server.lhs | 5 +++-- 5 files changed, 13 insertions(+), 5 deletions(-) diff --git a/doc/tutorial/ApiType.lhs b/doc/tutorial/ApiType.lhs index b770dcde..cc2d3717 100644 --- a/doc/tutorial/ApiType.lhs +++ b/doc/tutorial/ApiType.lhs @@ -345,7 +345,8 @@ type UserAPI12Alone = UserAPI12 EmptyAPI ``` 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` diff --git a/doc/tutorial/Client.lhs b/doc/tutorial/Client.lhs index 93ba56f3..94aee690 100644 --- a/doc/tutorial/Client.lhs +++ b/doc/tutorial/Client.lhs @@ -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. -If there is an `EmptyAPI` within your API, this matches the `EmptyClient` -constructor: +If you have an `EmptyAPI` in your API, servant-client will hand you a value of +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 type API' = API :<|> EmptyAPI diff --git a/doc/tutorial/Docs.lhs b/doc/tutorial/Docs.lhs index 67f6f60c..1d428698 100644 --- a/doc/tutorial/Docs.lhs +++ b/doc/tutorial/Docs.lhs @@ -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. +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. diff --git a/doc/tutorial/Javascript.lhs b/doc/tutorial/Javascript.lhs index 6a7aa6bb..033735ed 100644 --- a/doc/tutorial/Javascript.lhs +++ b/doc/tutorial/Javascript.lhs @@ -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, 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 javascript with just a simple function call to `jsForAPI` from `Servant.JS`. diff --git a/doc/tutorial/Server.lhs b/doc/tutorial/Server.lhs index 831eed1f..e287a26b 100644 --- a/doc/tutorial/Server.lhs +++ b/doc/tutorial/Server.lhs @@ -1020,8 +1020,9 @@ serverFor = error "..." -- or the mailing list if you get stuck! ``` -If the API contains the `EmptyAPI` combinator, the corresponding server is -called `emptyServer`: +When your API contains the `EmptyAPI` combinator, you'll want to use +`emptyServer` in the corresponding slot for your server, which will simply fail +with 404 whenever a request reaches it: ``` haskell type CombinedAPI2 = API :<|> "empty" :> EmptyAPI