diff --git a/src/Servant/API/Alternative.hs b/src/Servant/API/Alternative.hs
index 6b62fa0d..a3cba824 100644
--- a/src/Servant/API/Alternative.hs
+++ b/src/Servant/API/Alternative.hs
@@ -9,9 +9,25 @@ import Servant.Docs
 import Servant.Server
 
 -- | Union of two APIs, first takes precedence in case of overlap.
+--
+-- Example:
+--
+-- > type MyApi = "books" :> Get [Book] -- GET /books
+-- >         :<|> "books" :> ReqBody Book :> Post Book -- POST /books
 data a :<|> b = a :<|> b
 infixr 8 :<|>
 
+-- | A server for @a ':<|>' b@ first tries to match the request again the route
+--   represented by @a@ and if it fails tries @b@. You must provide a request
+--   handler for each route.
+--
+-- > type MyApi = "books" :> Get [Book] -- GET /books
+-- >         :<|> "books" :> ReqBody Book :> Post Book -- POST /books
+-- >
+-- > server :: Server MyApi
+-- > server = listAllBooks :<|> postBook
+-- >   where listAllBooks = ...
+-- >         postBook book = ...
 instance (HasServer a, HasServer b) => HasServer (a :<|> b) where
   type Server (a :<|> b) = Server a :<|> Server b
   route Proxy (a :<|> b) request respond =
@@ -23,12 +39,27 @@ instance (HasServer a, HasServer b) => HasServer (a :<|> b) where
     where pa = Proxy :: Proxy a
           pb = Proxy :: Proxy b
 
+-- | A client querying function for @a ':<|>' b@ will actually hand you
+--   one function for querying @a@ and another one for querying @b@,
+--   stitching them together with ':<|>', which really is just like a pair.
+--
+-- > type MyApi = "books" :> Get [Book] -- GET /books
+-- >         :<|> "books" :> ReqBody Book :> Post Book -- POST /books
+-- >
+-- > myApi :: Proxy MyApi
+-- > myApi = Proxy
+-- >
+-- > getAllBooks :: BaseUrl -> EitherT String IO [Book]
+-- > postNewBook :: Book -> BaseUrl -> EitherT String IO Book
+-- > (getAllBooks :<|> postNewBook) = client myApi
 instance (HasClient a, HasClient b) => HasClient (a :<|> b) where
   type Client (a :<|> b) = Client a :<|> Client b
   clientWithRoute Proxy req =
     clientWithRoute (Proxy :: Proxy a) req :<|>
     clientWithRoute (Proxy :: Proxy b) req
 
+-- | The generated docs for @a ':<|>' b@ just append the docs
+--   for @a@ with the docs for @b@.
 instance (HasDocs layout1, HasDocs layout2)
       => HasDocs (layout1 :<|> layout2) where