use Capture Description if available (#1423)

* use Capture Description if available

* update golden/comprehensive.md

This is technically a breaking change, because if a Capture has both a
Description and a ToCapture instance, the Description now takes
precedence. Since this Description wasn't doing anything before, I am
guessing that most projects currently only use Description to describe
their endpoints and not their Captures, and thus that few people will be
affected by this breaking change.

* test the "no ToCapture instance" case

The case in which there is both a Description and a ToCapture instance
seems like a corner case. The more interesting cases are the one in
which there is a Description but no ToCapture instance, and the case in
which there is a ToCapture instance but no description.

servant-docs/golden/comprehensive.md

@@ -52,11 +52,11 @@
 
 ```
 
-## GET /capture/:foo
+## GET /capture/:bar
 
 ### Captures:
 
-- *foo*: Capture foo Int
+- *bar*: example description
 
 ### Response:
 

servant-docs/src/Servant/Docs/Internal.hs

@@ -862,7 +862,7 @@ instance HasDocs EmptyAPI where
 -- | @"books" :> 'Capture' "isbn" Text@ will appear as
 -- @/books/:isbn@ in the docs.
 instance (KnownSymbol sym, ToCapture (Capture sym a), HasDocs api)
-      => HasDocs (Capture' mods sym a :> api) where
+      => HasDocs (Capture' '[] sym a :> api) where
 
   docsFor Proxy (endpoint, action) =
     docsFor subApiP (endpoint', action')
@@ -874,6 +874,28 @@ instance (KnownSymbol sym, ToCapture (Capture sym a), HasDocs api)
           endpoint' = over path (\p -> p ++ [":" ++ symbolVal symP]) endpoint
           symP = Proxy :: Proxy sym
 
+instance (KnownSymbol descr, KnownSymbol sym, HasDocs api)
+      => HasDocs (Capture' (Description descr ': mods) sym a :> api) where
+
+  docsFor Proxy (endpoint, action) =
+    docsFor subApiP (endpoint', action')
+
+    where subApiP = Proxy :: Proxy api
+
+          docCapture = DocCapture (symbolVal symP) (symbolVal descrP)
+          action' = over captures (|> docCapture) action
+          endpoint' = over path (\p -> p ++ [":" ++ symbolVal symP]) endpoint
+          descrP = Proxy :: Proxy descr
+          symP = Proxy :: Proxy sym
+
+instance {-# OVERLAPPABLE #-} HasDocs (Capture' mods sym a :> api)
+      => HasDocs (Capture' (mod ': mods) sym a :> api) where
+
+  docsFor Proxy =
+    docsFor apiP
+
+    where apiP = Proxy :: Proxy (Capture' mods sym a :> api)
+
 
 -- | @"books" :> 'CaptureAll' "isbn" Text@ will appear as
 -- @/books/:isbn@ in the docs.

servant/src/Servant/Test/ComprehensiveAPI.hs

@@ -48,7 +48,7 @@ comprehensiveAPIWithoutStreaming = Proxy
 type ComprehensiveAPIWithoutStreamingOrRaw' endpoint =
     GET
     :<|> "get-int"          :> Get '[JSON] Int
-    :<|> "capture"          :> Capture' '[Description "example description"] "foo" Int :> GET
+    :<|> "capture"          :> Capture' '[Description "example description"] "bar" Int :> GET
     :<|> "capture-lenient"  :> Capture' '[Lenient] "foo" Int :> GET
     :<|> "header"           :> Header "foo" Int :> GET
     :<|> "header-lenient"   :> Header' '[Required, Lenient] "bar" Int :> GET