@@ -629,13 +629,18 @@ type family DropIfConstraintsInvolve column constraints where
629629 (DropIfConstraintsInvolve column constraints)
630630 (alias ::: constraint ': DropIfConstraintsInvolve column constraints)
631631
632+-- | A `SchemumType` is a user-defined type, either a `Table`,
633+-- `View` or `Typedef`.
632634data SchemumType
633635 = Table TableType
634636 | View RelationType
635637 | Typedef PGType
636638
639+-- | The schema of a database consists of a list of aliased,
640+-- user-defined `SchemumType`s.
637641type SchemaType = [(Symbol,SchemumType)]
638642
643+-- | Used in `Squeal.Postgresql.Manipulation.with`.
639644type family With
640645 (relations :: RelationsType)
641646 (schema :: SchemaType)
@@ -644,27 +649,38 @@ type family With
644649 With (alias ::: rel ': rels) schema =
645650 alias ::: 'View rel ': With rels schema
646651
652+-- | `IsPGlabel` looks very much like the `IsLabel` class. Whereas
653+-- the overloaded label, `fromLabel` is used for column references,
654+-- `label`s are used for enum terms. A `label` is called with
655+-- type application like `label @"beef"`.
647656class IsPGlabel (label :: Symbol) expr where label :: expr
648657instance label ~ label'
649658 => IsPGlabel label (PGlabel label') where label = PGlabel
659+-- | A `PGlabel` unit type with an `IsPGlabel` instance
650660data PGlabel (label :: Symbol) = PGlabel
651−
661+-- | Renders a label
652662renderLabel :: KnownSymbol label => proxy label -> ByteString
653663renderLabel (_ :: proxy label) =
654664 "\'" <> fromString (symbolVal (Proxy @label)) <> "\'"
655−
665+-- | Renders a list of labels
656666renderLabels
657667 :: All KnownSymbol labels => NP PGlabel labels -> [ByteString]
658668renderLabels = hcollapse
659669 . hcmap (Proxy @KnownSymbol) (K . renderLabel)
660−
670+-- | Gets the name of a type constructor
661671type family LabelOf (cons :: Type.ConstructorInfo) :: Symbol where
662672 LabelOf ('Type.Constructor name) = name
663−
673+-- | Gets the names of a list of type constructors
664674type family LabelsOf (conss :: [Type.ConstructorInfo]) :: [Symbol] where
665675 LabelsOf '[] = '[]
666676 LabelsOf (cons ': conss) = LabelOf cons ': LabelsOf conss
667677
678+-- | The `PG` type family embeds a subset of Haskell types
679+-- as basic Postgres types.
680+--
681+-- >>> :kind! PG LocalTime
682+-- PG LocalTime :: PGType
683+-- = 'PGtimestamp
668684type family PG (hask :: Type) :: PGType where
669685 PG Bool = 'PGbool
670686 PG Int16 = 'PGint2