Add doctests (and changelog)

servant/CHANGELOG.md

@@ -30,6 +30,8 @@
    [#767](https://github.com/haskell-servant/servant/pull/767)
    [#790](https://github.com/haskell-servant/servant/pull/790)
    [#788](https://github.com/haskell-servant/servant/pull/788))
+- Add `addLinks` to generate all links for unnested APIs.
+  ([#851](https://github.com/haskell-servant/servant/pull/851))
 - Allow newest dependencies
  ([#772](https://github.com/haskell-servant/servant/pull/772)
   [#842](https://github.com/haskell-servant/servant/pull/842))

servant/src/Servant/Utils/Links.hs

@@ -226,6 +226,20 @@ safeLink _ endpoint = toLink endpoint (Link mempty mempty)
 --
 -- Note that the @api@ type must be restricted to the endpoints that have
 -- valid links to them.
+--
+-- >>> type API = "foo" :> Capture "name" Text :> Get '[JSON] Text :<|> "bar" :> Capture "name" Int :> Get '[JSON] Double
+-- >>> let fooLink :<|> barLink = allLinks (Proxy :: Proxy API)
+-- >>> :t fooLink
+-- fooLink :: Text -> Link
+-- >>> :t barLink
+-- barLink :: Int -> Link
+--
+-- Note: nested APIs don't work well with this approach
+--
+-- >>> :kind! MkLink (Capture "nest" Char :> (Capture "x" Int :> Get '[JSON] Int :<|> Capture "y" Double :> Get '[JSON] Double))
+-- MkLink (Capture "nest" Char :> (Capture "x" Int :> Get '[JSON] Int :<|> Capture "y" Double :> Get '[JSON] Double)) :: *
+-- = Char -> (Int -> Link) :<|> (Double -> Link)
+--
 allLinks
     :: forall api. HasLink api
     => Proxy api
@@ -330,3 +344,4 @@ instance HasLink sub => HasLink (AuthProtect tag :> sub) where
 
 -- $setup
 -- >>> import Servant.API
+-- >>> import Data.Text (Text)