Improve comments and error messages

Author: nc6

example/Monad.hs

@@ -19,8 +19,8 @@ spec = huddleDef $ mdo
   transaction <-
     "transaction"
       =:= mp
-        [ idx 0 ==> set txIn,
-          idx 1 ==> set' <-- txOut
+        [ idx 0 ==> set txIn
+        , idx 1 ==> set' <-- txOut
         ]
   txIn <- "txIn" =:= arr ["transaction_id" ==> hash32, "index" ==> txId]
   txOut <- "txOut" =:= arr [idx 0 ==> address, idx 1 ==> value]
@@ -44,9 +44,9 @@ spec2 =
           _transaction <-
             "transaction"
               =:= mp
-                [ comment "Transaction inputs" $ idx 0 ==> set <-- txIn,
-                  comment "Transaction outputs" $ idx 1 ==> set <-- txOut,
-                  comment "Metadata" $ idx 2 ==> metadata
+                [ comment "Transaction inputs" $ idx 0 ==> set <-- txIn
+                , comment "Transaction outputs" $ idx 1 ==> set <-- txOut
+                , comment "Metadata" $ idx 2 ==> metadata
                 ]
           metadata <- "metadata" =:= VBytes
           _value <- "value" =:= mp ["token" ==> VText, "quantity" ==> VUInt]

src/Codec/CBOR/Cuddle/Huddle.hs

@@ -486,9 +486,9 @@ class IsCborable a
 
 instance IsCborable ByteString
 
-instance IsCborable CRef
+instance IsCborable CRefType
 
-instance IsCborable CGRef
+instance IsCborable CGRefType
 
 cbor :: (IsCborable b, IsConstrainable c b) => c -> Rule -> Constrained
 cbor v r@(Named n _ _) =
@@ -507,9 +507,9 @@ class IsComparable a
 
 instance IsComparable Int
 
-instance IsComparable CRef
+instance IsComparable CRefType
 
-instance IsComparable CGRef
+instance IsComparable CGRefType
 
 le :: (IsComparable a, IsConstrainable c a) => c -> Word64 -> Constrained
 le v bound =
@@ -633,10 +633,14 @@ instance IsType0 HuddleItem where
   toType0 (HIGroup g) = toType0 g
   toType0 (HIGRule g) =
     error $
-      "Attempt to reference generic rule from HuddleItem not supported: " <> show g
+      "Attempt to reference a raw generic rule: "
+        <> show g
+        <> ". Most likely this indicates you haven't provided generic parameters."
   toType0 (HIGRule' g) =
     error $
-      "Attempt to reference generic rule from HuddleItem not supported: " <> show g
+      "Attempt to reference a raw generic rule: "
+        <> show g
+        <> ". Most likely this indicates you haven't provided generic parameters."
 
 class CanQuantify a where
   -- | Apply a lower bound
@@ -960,12 +964,13 @@ binding2 fRule t0 t1 =
 type GRuleDef' = Named (FnWithArg GRef Type0)
 
 data GRuleCallAux = GRuleCallAux
-  { defFn :: FnWithArg GRef Type0,
-    callArg :: Type2
+  { defFn :: FnWithArg GRef Type0
+  , callArg :: Type2
   }
 
 type GRuleCall' = Named GRuleCallAux
 
+-- | Create a generic rule definition binding a single generic parameter.
 binding' :: (GRef -> Rule) -> GRuleDef'
 binding' fRule =
   Named
@@ -983,15 +988,18 @@ instance IsGRuleDef GRuleDef' where
 
 instance IsGRuleDef HuddleItem where
   toGRuleDef (HIGRule' gd) = gd
-  toGRuleDef _ = error "Attempt to use a non-generic rule as a GRuleDef"
+  toGRuleDef hi =
+    error $
+      "Attempt to apply generic parameters to a non-generic rule: " <> show hi
 
+-- | Call a generic definition, applying the given type parameter.
 (<--) :: (IsType0 t0, IsGRuleDef gd) => gd -> t0 -> GRuleCall'
 (toGRuleDef -> f) <-- t0 = fmap toCall f
   where
     toCall rd =
       GRuleCallAux
-        { defFn = rd,
-          callArg = t2
+        { defFn = rd
+        , callArg = t2
         }
     t2 = case toType0 t0 of
       NoChoice x -> x
@@ -1228,7 +1236,7 @@ toCDDL' mkPseudoRoot hdl =
     toGenericCall' (Named n gr _) =
       C.T2Name
         (C.Name n)
-        (Just . C.GenericArg $ (toCDDLType1 (callArg gr)) NE.:| [])
+        (Just . C.GenericArg $ toCDDLType1 (callArg gr) NE.:| [])
 
     toGenRuleDef :: GRuleDef -> C.WithComments C.Rule
     toGenRuleDef (Named n gr c) =

src/Codec/CBOR/Cuddle/Huddle/Generic.hs

@@ -2,8 +2,8 @@ module Codec.CBOR.Cuddle.Huddle.Generic where
 
 -- | Function carrying its argument
 data FnWithArg a result = FnWithArg
-  { fn :: a -> result,
-    arg :: a
+  { fn :: a -> result
+  , arg :: a
   }
   deriving (Functor)
 

src/Codec/CBOR/Cuddle/Huddle/HuddleM.hs

@@ -1,17 +1,17 @@
 -- | Monad for declaring Huddle constructs
-module Codec.CBOR.Cuddle.Huddle.HuddleM
-  ( module Huddle,
-    (=:=),
-    (=:~),
-    (=::=),
-    binding,
-    binding',
-    setRootRules,
-    huddleDef,
-    huddleDef',
-    include,
-    unsafeIncludeFromHuddle,
-  )
+module Codec.CBOR.Cuddle.Huddle.HuddleM (
+  module Huddle,
+  (=:=),
+  (=:~),
+  (=::=),
+  binding,
+  binding',
+  setRootRules,
+  huddleDef,
+  huddleDef',
+  include,
+  unsafeIncludeFromHuddle,
+)
 where
 
 import Codec.CBOR.Cuddle.Huddle hiding (binding, binding', (=:=), (=:~))