@@ -41,9 +41,21 @@ import Rel8.Schema.Spec ( SSpec( SSpec ), KnownSpec )
4141import Rel8.Type ( DBType )
4242
4343
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.
50+--
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'.
4453type Table :: K.Context -> Type -> Constraint
4554class (HTable (Columns a), context ~ Context a) => Table context a | a -> context where
55+ -- | The 'HTable' functor that describes the schema of this table.
4656 type Columns a :: K.HTable
57+
58+ -- | The common context that all columns use as an interpretation.
4759 type Context a :: K.Context
4860
4961 toColumns :: a -> Columns a (Col (Context a))