@@ -51,17 +51,10 @@ module Squeal.PostgreSQL.Schema
5151 , GroupedBy
5252 -- * Constraints
5353 , (:=>)
54− , ColumnsToRelation
55− , RelationToColumns
56− , TableToColumns
57− , TablesToRelations
58− , RelationsToTables
5954 , ColumnConstraint (..)
6055 , TableConstraint (..)
6156 , TableConstraints
6257 , NilTableConstraints
63− , ConstraintInvolves
64− , DropIfConstraintsInvolve
6558 -- * Aliases
6659 , (:::)
6760 , Alias (Alias)
@@ -74,6 +67,11 @@ module Squeal.PostgreSQL.Schema
7467 , IsLabel (..)
7568 , IsQualified (..)
7669 -- * Type Families
70+ , Join
71+ , Create
72+ , Drop
73+ , Alter
74+ , Rename
7775 , Elem
7876 , In
7977 , PGNum
@@ -86,11 +84,13 @@ module Squeal.PostgreSQL.Schema
8684 , NullifyType
8785 , NullifyRelation
8886 , NullifyRelations
89− , Join
90− , Create
91− , Drop
92− , Alter
93− , Rename
87+ , ColumnsToRelation
88+ , RelationToColumns
89+ , TableToColumns
90+ , TablesToRelations
91+ , RelationsToTables
92+ , ConstraintInvolves
93+ , DropIfConstraintsInvolve
9494 -- * Generics
9595 , SameField
9696 , SameFields
@@ -181,9 +181,9 @@ data NullityType
181181 | NotNull PGType -- ^ @NULL@ is absent
182182
183183-- | The constraint operator, `:=>` is a type level pair
184−-- between an "constraint" and some type,
185−-- either a `ColumnConstraint` and a `NullityType` or a row of
186−-- `TableConstraint`s and a `TableType`.
184+-- between a "constraint" and some type, for use in pairing
185+-- a `ColumnConstraint` with a `NullityType` to produce a `ColumnType`
186+-- or a `TableConstraints` and a `ColumnsType` to produce a `TableType`.
187187type (:=>) constraint ty = '(constraint,ty)
188188infixr 7 :=>
189189
@@ -195,7 +195,11 @@ infixr 7 :=>
195195type (:::) (alias :: Symbol) ty = '(alias,ty)
196196infixr 6 :::
197197
198−-- | `ColumnConstraint` encodes the allowance of @DEFAULT@.
198+-- | `ColumnConstraint` encodes the availability of @DEFAULT@ for inserts and updates.
199+-- A column can be assigned a default value.
200+-- A data `Squeal.PostgreSQL.Manipulations.Manipulation` command can also
201+-- request explicitly that a column be set to its default value,
202+-- without having to know what that value is.
199203data ColumnConstraint
200204 = Def -- ^ @DEFAULT@ is available for inserts and updates
201205 | NoDef -- ^ @DEFAULT@ is unavailable for inserts and updates
@@ -222,13 +226,17 @@ type ColumnsType = [(Symbol,ColumnType)]
222226
223227-- | `TableConstraint` encodes various forms of data constraints
224228-- of columns in a table.
229+-- `TableConstraint`s give you as much control over the data in your tables
230+-- as you wish. If a user attempts to store data in a column that would
231+-- violate a constraint, an error is raised. This applies
232+-- even if the value came from the default value definition.
225233data TableConstraint
226234 = Check [Symbol]
227235 | Unique [Symbol]
228236 | PrimaryKey [Symbol]
229237 | ForeignKey [Symbol] Symbol [Symbol]
230238
231−-- | A `TableConstraints` is a set of aliased `TableConstraint`s.
239+-- | A `TableConstraints` is a row of `TableConstraint`s.
232240type TableConstraints = [(Symbol,TableConstraint)]
233241-- | A monokinded empty `TableConstraints`.
234242type family NilTableConstraints :: TableConstraints where
@@ -326,7 +334,7 @@ data Grouping
326334
327335{- | A `GroupedBy` constraint indicates that a table qualified column is
328336a member of the auxiliary namespace created by @GROUP BY@ clauses and thus,
329−may be called in an output `Expression` without aggregating.
337+may be called in an output `Squeal.PostgreSQL.Expression.Expression` without aggregating.
330338-}
331339class (KnownSymbol relation, KnownSymbol column)
332340 => GroupedBy relation column bys where
@@ -387,12 +395,12 @@ type family AliasesOf aliaseds where
387395 AliasesOf '[] = '[]
388396 AliasesOf (alias ::: ty ': tys) = alias ': AliasesOf tys
389397
390−-- | @HasUnique alias xs x@ is a constraint that proves that @xs@ is a singleton
391−-- of @alias ::: x@.
392−type HasUnique alias xs x = xs ~ '[alias ::: x]
398+-- | @HasUnique alias fields field@ is a constraint that proves that
399+-- @fields@ is a singleton of @alias ::: field@.
400+type HasUnique alias fields field = fields ~ '[alias ::: field]
393401
394−-- | @Has alias xs x@ is a constraint that proves that @xs@ has a field
395−-- of @alias ::: x@.
402+-- | @Has alias fields field@ is a constraint that proves that
403+-- @fields@ has a field of @alias ::: field@.
396404class KnownSymbol alias =>
397405 Has (alias :: Symbol) (fields :: [(Symbol,kind)]) (field :: kind)
398406 | alias fields -> field where