@@ -10,9 +10,33 @@ where
1010import Prelude
1111
1212
13+-- | The schema for a table. This is used to specify the name and schema that a
14+-- table belongs to (the @FROM@ part of a SQL query), along with the schema of
15+-- the columns within this table.
16+--
17+-- For each selectable table in your database, you should provide a
18+-- @TableSchema@ in order to interact with the table via Rel8. For a table
19+-- storing a list of projects (as defined in the introduction):
20+--
21+-- >>> :{
22+-- projectSchema :: TableSchema (Project ColumnSchema)
23+-- projectSchema = TableSchema
24+-- { tableName = "project"
25+-- , tableSchema = Nothing -- Assumes that the 'project' table is reachable from your connection's search_path
26+-- , tableColumns = Project
27+-- { projectAuthorId = "author_id"
28+-- , projectName = "name"
29+-- }
30+-- }
31+-- :}
1332data TableSchema names = TableSchema
1433 { name :: String
34+ -- ^ The name of the table.
1535 , schema :: Maybe String
36+ -- ^ The schema that this table belongs to. If 'Nothing', whatever is on
37+ -- the connection's @search_path@ will be used.
1638 , columns :: names
39+ -- ^ The columns of the table. Typically you would use a a higher-kinded
40+ -- data type here, parameterized by the 'Rel8.ColumnSchema.ColumnSchema' functor.
1741 }
1842 deriving stock Functor