Deprecate UVerb

doc/cookbook/uverb/UVerb.lhs

@@ -1,3 +1,8 @@
+
+
+# WARNING: UVerb is deprecated.  Please use MultiVerb instead!
+
+
 # Listing alternative responses and exceptions in your API types
 
 Servant allows you to talk about the exceptions you throw in your API

servant-client-core/src/Servant/Client/Core/HasClient.hs

@@ -349,6 +349,7 @@ instance {-# OVERLAPPING #-} UnrenderResponse cts a
   => UnrenderResponse cts (WithStatus n a) where
   unrenderResponse hs body = (map . fmap) WithStatus . unrenderResponse hs body
 
+-- | WARNING: UVerb is deprecated.  Please use MultiVerb instead!
 instance {-# OVERLAPPING #-}
   ( RunClient m,
     contentTypes ~ (contentType ': otherContentTypes),

servant-client/src/Servant/Client/Internal/HttpClient/Streaming.hs

@@ -173,7 +173,6 @@ performRequest acceptStatus req = do
         throwError $ mkFailureResponse burl req ourResponse
       return ourResponse
 
--- | TODO: support UVerb ('acceptStatus' argument, like in 'performRequest' above).
 performWithStreamingRequest :: Request -> (StreamingResponse -> IO a) -> ClientM a
 performWithStreamingRequest req k = do
   ClientEnv m burl cookieJar' createClientRequest _ <- ask

servant-server/src/Servant/Server/UVerb.hs

@@ -15,6 +15,7 @@
 {-# OPTIONS_GHC -Wno-orphans #-}
 {-# OPTIONS_GHC -Wno-redundant-constraints #-}
 
+-- | WARNING: UVerb is deprecated.  Please use MultiVerb instead!
 module Servant.Server.UVerb
   ( respond,
     IsServerResource,
@@ -73,6 +74,7 @@ encodeResource request cts res = (statusOf (Proxy @a),
 
 type IsServerResourceWithStatus cts = IsServerResource cts `And` HasStatus
 
+-- | WARNING: UVerb is deprecated.  Please use MultiVerb instead!
 instance
   ( ReflectMethod method,
     AllMime contentTypes,

servant-swagger/src/Servant/Swagger/Internal.hs

@@ -184,24 +184,27 @@
 instance SwaggerMethod 'HEAD    where swaggerMethod _ = head_
 instance SwaggerMethod 'PATCH   where swaggerMethod _ = patch
 
+-- | WARNING: UVerb is deprecated.  Please use MultiVerb instead!
 instance HasSwagger (UVerb method cs '[]) where
   toSwagger _ = mempty
 
--- | @since <TODO>
+-- | WARNING: UVerb is deprecated.  Please use MultiVerb instead!
 instance
   {-# OVERLAPPABLE #-}
   ( ToSchema a,
     HasStatus a,
     AllAccept cs,
     SwaggerMethod method,
     HasSwagger (UVerb method cs as)
   ) =>
   HasSwagger (UVerb method cs (a ': as))
   where
   toSwagger _ =
     toSwagger (Proxy :: Proxy (Verb method (StatusOf a) cs a))
       `combineSwagger` toSwagger (Proxy :: Proxy (UVerb method cs as))
 
+-- | WARNING: UVerb is deprecated.  Please use MultiVerb instead!
+--
 -- ATTENTION: do not remove this instance!
 -- A similar instance above will always use the more general
 -- polymorphic -- HasSwagger instance and will result in a type error
@@ -210,13 +213,13 @@
   ( KnownNat status,
     AllAccept cs,
     SwaggerMethod method,
     HasSwagger (UVerb method cs as)
   ) =>
   HasSwagger (UVerb method cs (WithStatus status NoContent ': as))
   where
   toSwagger _ =
     toSwagger (Proxy :: Proxy (Verb method status cs NoContent))
       `combineSwagger` toSwagger (Proxy :: Proxy (UVerb method cs as))
 
 
 -- workaround for https://github.com/GetShopTV/swagger2/issues/218

servant/src/Servant/API/MultiVerb.hs

@@ -223,7 +223,7 @@ type family ResponseTypes (as :: [Type]) where
 
 
 -- | 'MultiVerb' produces an endpoint which can return
--- multiple values with various content types and status codes. It is similar to
+-- multiple values with various content types and status codes. It is similar to the deprecated
 -- 'Servant.API.UVerb.UVerb' and behaves similarly, but it has some important differences:
 --
 --  * Descriptions and statuses can be attached to individual responses without

servant/src/Servant/API/TypeLevel.hs

@@ -275,6 +275,7 @@ class FragmentUnique api => AtMostOneFragment api
 
 instance AtMostOneFragment (Verb m s ct typ)
 
+-- | WARNING: UVerb is deprecated.  Please use MultiVerb instead!
 instance AtMostOneFragment (UVerb m cts as)
 
 instance AtMostOneFragment (Fragment a)

servant/src/Servant/API/UVerb.hs

@@ -12,7 +12,9 @@
 {-# LANGUAGE UndecidableInstances #-}
 
 
--- | An alternative to 'Verb' for end-points that respond with a resource value of any of an
+-- | **WARNING: UVerb is deprecated.  Please use MultiVerb instead!**
+--
+-- An alternative to 'Verb' for end-points that respond with a resource value of any of an
 -- open union of types, and specific status codes for each type in this union.  (`UVerb` is
 -- short for `UnionVerb`)
 --
@@ -91,16 +93,10 @@ instance KnownStatus n => HasStatus (WithStatus n a) where
 instance HasStatus a => HasStatus (Headers ls a) where
   type StatusOf (Headers ls a) = StatusOf a
 
--- | A variant of 'Verb' that can have any of a number of response values and status codes.
---
--- FUTUREWORK: it would be nice to make 'Verb' a special case of 'UVerb', and only write
--- instances for 'HasServer' etc. for the latter, getting them for the former for free.
--- Something like:
---
--- @type Verb method statusCode contentTypes a = UVerb method contentTypes [WithStatus statusCode a]@
+-- | WARNING: UVerb is deprecated.  Please use MultiVerb instead!
 --
--- Backwards compatibility is tricky, though: this type alias would mean people would have to
--- use 'respond' instead of 'pure' or 'return', so all old handlers would have to be rewritten.
+-- A variant of 'Verb' that can have any of a number of response values and status codes.
+{-# DEPRECATED UVerb "Use MultiVerb instead; if you find that `MultiVerb` doesn't allow you to do the things you're doing with `UVerb`, please [open an issue](https://github.com/haskell-servant/servant/issues)" #-}
 data UVerb (method :: StdMethod) (contentTypes :: [Type]) (as :: [Type])
 
 instance {-# OVERLAPPING #-} MimeRender JSON a => MimeRender JSON (WithStatus _status a) where

servant/src/Servant/Links.hs

@@ -600,11 +600,10 @@ instance HasLink (Stream m status fr ct a) where
     type MkLink (Stream m status fr ct a) r = r
     toLink toA _ = toA
 
--- UVerb instances
+-- | WARNING: UVerb is deprecated.  Please use MultiVerb instead!
 instance HasLink (UVerb m ct a) where
     type MkLink (UVerb m ct a) r = r
     toLink toA _ = toA
--- Instance for NamedRoutes combinator
 
 type GLinkConstraints routes a =
   ( MkLink (ToServant routes AsApi) a ~ ToServant routes (AsLink a)