diff --git a/src/Servant/API/Sub.hs b/src/Servant/API/Sub.hs
index c3eb68a4..66bf40d0 100644
--- a/src/Servant/API/Sub.hs
+++ b/src/Servant/API/Sub.hs
@@ -15,9 +15,17 @@ import Servant.Server
 
 -- | The contained API (second argument) can be found under @("/" ++ path)@
 -- (path being the first argument).
+--
+-- Example:
+--
+-- > -- GET /hello/world
+-- > -- returning a JSON encoded World value
+-- > type MyApi = "hello" :> "world" :> Get World
 data (path :: k) :> a = Proxy path :> a
 infixr 9 :>
 
+-- | Make sure the incoming request starts with @"/path"@, strip it and
+-- pass the rest of the request path to @sublayout@.
 instance (KnownSymbol path, HasServer sublayout) => HasServer (path :> sublayout) where
   type Server (path :> sublayout) = Server sublayout
   route Proxy subserver request respond = case pathInfo request of
@@ -30,6 +38,7 @@ instance (KnownSymbol path, HasServer sublayout) => HasServer (path :> sublayout
 
     where proxyPath = Proxy :: Proxy path
 
+-- | Make the querying function append @path@ to the request path.
 instance (KnownSymbol path, HasClient sublayout) => HasClient (path :> sublayout) where
   type Client (path :> sublayout) = Client sublayout