Add doc comment for variantMatch

Also move it up in the file so it's seen first on the docs page

Author: garyb

src/Data/Codec/Argonaut/Variant.purs

@@ -22,11 +22,52 @@ import Type.Data.RowList (RLProxy(..))
 import Type.Equality as TE
 import Unsafe.Coerce (unsafeCoerce)
 
--- | Allows building codecs for variants in combination with variantCase.
+-- | Builds a codec for a variant from a record, similar to the way
+-- | `Variant.match` works to pattern match on a variant.
 -- |
 -- | Commonly used to write decoders for sum-types, by providing a mapping from
 -- | and to a Variant from that type and then using `dimap`.
 -- |
+-- | Each field in the record accepts an `Either`, where `Right` is used to
+-- | specify a codec used for the constructor, and `Left` is used to specify a
+-- | static value (generally as `Left unit` for nullary constructors).
+-- |
+-- | The variant will be encoded as a JSON object of the form
+-- | `{ "tag": <name>, "value": <value> }`, where `<name>` is the name of the
+-- | variant case, and `<value>` is the associated value (omitted in the case
+-- | of static `Left`-defined values).
+-- |
+-- |```purescript
+-- | codecMaybeMatch ∷ ∀ a. JA.JsonCodec a → JA.JsonCodec (Maybe a)
+-- | codecMaybeMatch codecA =
+-- |   dimap toVariant fromVariant
+-- |     (JAV.variantMatch
+-- |       { just: Right codecA
+-- |       , nothing: Left unit
+-- |       })
+-- |   where
+-- |   toVariant = case _ of
+-- |     Just a → V.inj (SProxy ∷ _ "just") a
+-- |     Nothing → V.inj (SProxy ∷ _ "nothing") unit
+-- |   fromVariant = V.match
+-- |     { just: Just
+-- |     , nothing: \_ → Nothing
+-- |     }
+-- |```
+variantMatch
+  ∷ ∀ rl ri ro
+  . RL.RowToList ri rl
+  ⇒ VariantCodec rl ri ro
+  ⇒ Record ri
+  → JsonCodec (Variant ro)
+variantMatch = variantCodec (RLProxy ∷ RLProxy rl)
+
+-- | Builds codecs for variants in combination with `variantCase`.
+-- |
+-- | Provides an alternative means of building variant codecs to that of
+-- | `variantMatch`, often for cases where the codec is being constructed
+-- | with a fold or some other similar technique.
+-- |
 -- |```purescript
 -- | codecMaybe ∷ ∀ a. JA.JsonCodec a → JA.JsonCodec (Maybe a)
 -- | codecMaybe codecA =
@@ -85,6 +126,8 @@ variantCase proxy eacodec (GCodec dec enc) = GCodec dec' enc'
   coerceR ∷ Variant r → Variant r'
   coerceR = unsafeCoerce
 
+-- | The class used to enable the building of `Variant` codecs from a record of
+-- | codecs.
 class VariantCodec (rl ∷ RL.RowList) (ri ∷ # Type) (ro ∷ # Type) | rl → ri ro where
   variantCodec ∷ RLProxy rl → Record ri → JsonCodec (Variant ro)
 
@@ -106,11 +149,3 @@ instance variantCodecCons ∷
 
     tail ∷ JsonCodec (Variant ro')
     tail = variantCodec (RLProxy ∷ RLProxy rs) ((unsafeCoerce ∷ Record ri → Record ri') codecs)
-
-variantMatch
-  ∷ ∀ rl ri ro
-  . RL.RowToList ri rl
-  ⇒ VariantCodec rl ri ro
-  ⇒ Record ri
-  → JsonCodec (Variant ro)
-variantMatch = variantCodec (RLProxy ∷ RLProxy rl)

test/Test/Variant.purs

@@ -31,6 +31,11 @@ main = do
     propCodec
       (GenC.genMaybe genAsciiString)
       (codecMaybe JA.string)
+  log "Checking Maybe-variantMatch codec"
+  quickCheck $
+    propCodec
+      (GenC.genMaybe genAsciiString)
+      (codecMaybeMatch JA.string)
 
   log "Checking Either-variant codec"
   quickCheck $
@@ -58,6 +63,22 @@ codecMaybe codecA =
   _Just = SProxy ∷ SProxy "just"
   _Nothing = SProxy ∷ SProxy "nothing"
 
+codecMaybeMatch ∷ ∀ a. JA.JsonCodec a → JA.JsonCodec (Maybe a)
+codecMaybeMatch codecA =
+  dimap toVariant fromVariant
+    (JAV.variantMatch
+      { just: Right codecA
+      , nothing: Left unit
+      })
+  where
+  toVariant = case _ of
+    Just a → V.inj (SProxy ∷ _ "just") a
+    Nothing → V.inj (SProxy ∷ _ "nothing") unit
+  fromVariant = V.match
+    { just: Just
+    , nothing: \_ → Nothing
+    }
+
 codecEither ∷ ∀ a b. JA.JsonCodec a → JA.JsonCodec b → JA.JsonCodec (Either a b)
 codecEither codecA codecB =
   dimap toVariant fromVariant