@@ -41,9 +41,21 @@ import Rel8.Schema.Spec ( SSpec( SSpec ), KnownSpec )
41import Rel8.Type ( DBType )
41import Rel8.Type ( DBType )
44+-- | @Table@s are one of the foundational elements of Rel8, and describe data
45+-- types that have a finite number of columns. Each of these columns contains
46+-- data under a shared context, and contexts describe how to interpret the
47+-- metadata about a column to a particular Haskell type. In Rel8, we have
48+-- contexts for expressions (the 'Expr' context), aggregations (the 'Aggregate'
49+-- context), insert values (the 'Insert' contex), among others.
51+-- In typical usage of Rel8 you don't need to derive instances of 'Table'
52+-- yourself, as anything that's an instance of 'Rel8able' is always a 'Table'.
44type Table :: K.Context -> Type -> Constraint
53type Table :: K.Context -> Type -> Constraint
45class (HTable (Columns a), context ~ Context a) => Table context a | a -> context where
54class (HTable (Columns a), context ~ Context a) => Table context a | a -> context where
55+ -- | The 'HTable' functor that describes the schema of this table.
46 type Columns a :: K.HTable
56 type Columns a :: K.HTable
58+ -- | The common context that all columns use as an interpretation.
47 type Context a :: K.Context
59 type Context a :: K.Context
49 toColumns :: a -> Columns a (Col (Context a))
61 toColumns :: a -> Columns a (Col (Context a))