Add explanations of (Raw m a) to the tutorial in the markdown files

tutorial/api-type.md

@@ -276,15 +276,18 @@ type UserAPI = "users" :> Get '[JSON] (Headers [Header "User-Count" Integer] [Us
 
 ### Interoperability with other WAI `Application`s: `Raw`
 
-Finally, we also include a combinator named `Raw` that can be used for two reasons:
+Finally, we include a combinator named `Raw` for handing control to the underlying
+framework. `Raw` endpoints trade away the type safety of normal Servant endpoints
+in return for direct access to the HTTP request and response. This can be useful for
+two reasons:
 
 - You want to serve static files from a given directory. In that case you can just say:
 
     ``` haskell
     type UserAPI = "users" :> Get '[JSON] [User]
                    -- a /users endpoint
 
-              :<|> Raw
+              :<|> Raw IO Application
                    -- requests to anything else than /users
                    -- go here, where the server will try to
                    -- find a file with the right name
@@ -296,6 +299,11 @@ into your webservice. Static file serving is a specific example of that. The API
 same as above though. (You can even combine *servant* with other web frameworks
 this way!)
 
+`Raw` takes two type arguments `m` and `a` corresponding to the underlying monad your
+web handler will run in and the handler's return type. This information is often needed
+by an API's server but ignored by other interpretations. As we will see later, it can be
+useful to have a version of your API that is free of `Raw` combinators.
+
 <div style="text-align: center;">
   <a href="/tutorial/server.html">Next page: Serving an API</a>
 </div>

tutorial/docs.md

@@ -181,7 +181,7 @@ docsBS = encodeUtf8
 We can now serve the API *and* the API docs with a simple server.
 
 ``` haskell
-type DocsAPI = T3.API :<|> Raw
+type DocsAPI = T3.API :<|> Raw IO Application
 
 api :: Proxy DocsAPI
 api = Proxy

tutorial/javascript.md

@@ -13,7 +13,7 @@ Let's start with the API type(s) and the accompanying datatypes.
 type API = "point" :> Get '[JSON] Point
       :<|> "books" :> QueryParam "q" Text :> Get '[JSON] (Search Book)
 
-type API' = API :<|> Raw
+type API' = API :<|> Raw IO Application
 
 data Point = Point
   { x :: Double

tutorial/server.md

@@ -816,13 +816,13 @@ myHandler = return $ addHeader 1797 someUser
 
 *servant-server* also provides a way to just serve the content of a directory
 under some path in your web API. As mentioned earlier in this document, the
-`Raw` combinator can be used in your APIs to mean "plug here any WAI
-application". Well, servant-server provides a function to get a file and
+`Raw m a` combinator can be used in your APIs to mean "plug here any handler
+running in monad `m` returning `a`". Well, servant-server provides a function to get a file and
 directory serving WAI application, namely:
 
 ``` haskell
 -- exported by Servant and Servant.Server
-serveDirectory :: FilePath -> Server Raw
+serveDirectory :: FilePath -> Server (Raw IO Application)
 ```
 
 `serveDirectory`'s argument must be a path to a valid directory. You can see an
@@ -834,7 +834,7 @@ getting-started.
 The API type will be the following.
 
 ``` haskell
-type API = "code" :> Raw
+type API = "code" :> Raw IO Application
 ```
 
 And the server: