@@ -80,7 +80,12 @@ import Servant.Utils.Links (HasLink (..), IsElem, IsElem',
8080
8181-- | Turn an API type into its canonical form.
8282--
83−-- The canonical form is defined and will basically turn:
83+-- The canonical form of an API type is basically the all-flattened form
84+-- of the original type. More formally, it takes a type as input and hands you
85+-- back an /equivalent/ type formed of toplevel `:<|>`-separated chains of `:>`s,
86+-- i.e with all `:>`s distributed inside the `:<|>`s.
87+--
88+-- It basically turns:
8489--
8590-- > "hello" :> (Get Hello :<|> ReqBody Hello :> Put Hello)
8691--
@@ -101,5 +106,5 @@ type family Redex a b c :: * where
101106 Redex a a first = Canonicalize first :> a
102107 Redex a b first = Canonicalize (first :> b)
103108
104−canonicalize :: Canonicalize layout ~ t => Proxy layout -> Proxy t
109+canonicalize :: Proxy layout -> Proxy (Canonicalize layout)
105110canonicalize Proxy = Proxy