Changes to docs as suggested

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`
 

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

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.
 

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`.

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