@@ -249,6 +249,7 @@ type family Manipulation_ (schemas :: SchemasType) (params :: Type) (row :: Type
249249-- | Convert a `Query` into a `Manipulation`.
250250queryStatement
251251 :: Query '[] commons schemas params columns
252+ -- ^ `Query` to embed as a `Manipulation`
252253 -> Manipulation commons schemas params columns
253254queryStatement q = UnsafeManipulation $ renderSQL q
254255
@@ -271,9 +272,13 @@ insertInto
271272 , SOP.SListI columns
272273 , SOP.SListI row1 )
273274 => QualifiedAlias sch tab
275+ -- ^ table
274276 -> QueryClause commons schemas params columns
277+ -- ^ what to insert
275278 -> ConflictClause tab commons schemas params table
279+ -- ^ what to do in case of conflict
276280 -> ReturningClause commons schemas params '[tab ::: row0] row1
281+ -- ^ what to return
277282 -> Manipulation commons schemas params row1
278283insertInto tab qry conflict ret = UnsafeManipulation $
279284 "INSERT" <+> "INTO" <+> renderSQL tab
@@ -281,7 +286,7 @@ insertInto tab qry conflict ret = UnsafeManipulation $
281286 <> renderSQL conflict
282287 <> renderSQL ret
283288
284−-- | Like `insertInto` but with `OnConflictDoRaise` and no `ReturningClause`.
289+-- | Like `insertInto` but with `OnConflictDoRaise` and `no` `ReturningClause`.
285290insertInto_
286291 :: ( Has sch schemas schema
287292 , Has tab schema ('Table table)
@@ -289,30 +294,33 @@ insertInto_
289294 , row ~ TableToRow table
290295 , SOP.SListI columns )
291296 => QualifiedAlias sch tab
297+ -- ^ table
292298 -> QueryClause commons schemas params columns
299+ -- ^ what to insert
293300 -> Manipulation commons schemas params '[]
294301insertInto_ tab qry =
295302 insertInto tab qry OnConflictDoRaise (Returning_ Nil)
296303
297304-- | A `QueryClause` describes what to `insertInto` a table.
298305data QueryClause commons schemas params columns where
299− -- | `Values` describes `NP` lists of `Aliased` `Optional` `Expression`s
300− -- whose `ColumnsType` must match the tables'.
301306 Values
302307 :: SOP.SListI columns
303308 => NP (Aliased (Optional (Expression '[] commons 'Ungrouped schemas params '[]))) columns
309+ -- ^ row of values
304310 -> [NP (Aliased (Optional (Expression '[] commons 'Ungrouped schemas params '[]))) columns]
311+ -- ^ additional rows of values
305312 -> QueryClause commons schemas params columns
306− -- | `Select` describes a subquery that permits use of `Optional` `Expression`s.
307313 Select
308314 :: SOP.SListI columns
309315 => NP (Aliased (Optional (Expression '[] commons grp schemas params from))) columns
316+ -- ^ row of values
310317 -> TableExpression '[] commons grp schemas params from
318+ -- ^ from a table expression
311319 -> QueryClause commons schemas params columns
312− -- | `Subquery` describes a subquery whose `RowType` must match the tables'.
313320 Subquery
314321 :: ColumnsToRow columns ~ row
315322 => Query '[] commons schemas params row
323+ -- ^ subquery to insert
316324 -> QueryClause commons schemas params columns
317325
318326instance RenderSQL (QueryClause commons schemas params columns) where
@@ -350,6 +358,7 @@ instance RenderSQL (QueryClause commons schemas params columns) where
350358pattern Values_
351359 :: SOP.SListI columns
352360 => NP (Aliased (Optional (Expression '[] commons 'Ungrouped schemas params '[]))) columns
361+ -- ^ row of values
353362 -> QueryClause commons schemas params columns
354363pattern Values_ vals = Values vals []
355364
@@ -374,7 +383,7 @@ instance (forall x. RenderSQL (expr x)) => RenderSQL (Optional expr ty) where
374383-- deleted will be returned. For example, if a row was locked
375384-- but not updated because an `OnConflict` `DoUpdate` condition was not satisfied,
376385-- the row will not be returned. `Returning` `Star` will return all columns
377−-- in the row. Use @Returning Nil@ in the common case where no return
386+-- in the row. Use `Returning` `Nil` in the common case where no return
378387-- values are desired.
379388newtype ReturningClause commons schemas params from row =
380389 Returning (Selection '[] commons 'Ungrouped schemas params from row)
@@ -388,6 +397,7 @@ instance RenderSQL (ReturningClause commons schemas params from row) where
388397pattern Returning_
389398 :: SOP.SListI row
390399 => NP (Aliased (Expression '[] commons 'Ungrouped schemas params from)) row
400+ -- ^ row of values
391401 -> ReturningClause commons schemas params from row
392402pattern Returning_ list = Returning (List list)
393403
@@ -400,7 +410,9 @@ data ConflictClause tab commons schemas params table where
400410 OnConflictDoRaise :: ConflictClause tab commons schemas params table
401411 OnConflict
402412 :: ConflictTarget constraints
413+ -- ^ conflict target
403414 -> ConflictAction tab commons schemas params columns
415+ -- ^ conflict action
404416 -> ConflictClause tab commons schemas params (constraints :=> columns)
405417
406418-- | Render a `ConflictClause`.
@@ -418,12 +430,12 @@ the exact details of the `update` action to be performed in case of a conflict.
418430The `Set` and WHERE `Condition`s in `OnConflict` `DoUpdate` have access to the
419431existing row using the table's name (or an alias), and to rows proposed
420432for insertion using the special @#excluded@ table.
433+`OnConflict` `DoNothing` simply avoids inserting a row as its alternative action.
434+`OnConflict` `DoUpdate` updates the existing row that conflicts
435+with the row proposed for insertion as its alternative action.
421436-}
422437data ConflictAction tab commons schemas params columns where
423− -- | `OnConflict` `DoNothing` simply avoids inserting a row as its alternative action.
424438 DoNothing :: ConflictAction tab commons schemas params columns
425− -- | `OnConflict` `DoUpdate` updates the existing row that conflicts
426− -- with the row proposed for insertion as its alternative action.
427439 DoUpdate
428440 :: ( row ~ ColumnsToRow columns
429441 , SOP.SListI columns
@@ -473,7 +485,6 @@ UPDATE statements
473485update
474486 :: ( SOP.SListI columns
475487 , SOP.SListI row1
476− , db ~ (commons :=> schemas)
477488 , Has sch schemas schema
478489 , Has tab schema ('Table table)
479490 , row0 ~ TableToRow table
@@ -498,7 +509,6 @@ update tab columns wh returning = UnsafeManipulation $
498509-- | Update a row returning `Nil`.
499510update_
500511 :: ( SOP.SListI columns
501− , db ~ (commons :=> schemas)
502512 , Has sch schemas schema
503513 , Has tab schema ('Table table)
504514 , row ~ TableToRow table
@@ -517,25 +527,25 @@ update_ tab columns wh = update tab columns wh (Returning_ Nil)
517527DELETE statements
518528-----------------------------------------}
519529
520−-- | Specify additional tables.
530+-- | Specify additional tables with `Using`
531+-- an `also` list of table expressions, allowing columns
532+-- from other tables to appear in the WHERE condition.
533+-- This is similar to the list of tables that can be specified
534+-- in the FROM Clause of a SELECT statement;
535+-- for example, an alias for the table name can be specified.
536+-- Do not repeat the target table in the `Using` list,
537+-- unless you wish to set up a self-join.
538+-- `NoUsing` if no additional tables are to be used.
521539data UsingClause commons schemas params from where
522− -- | No `UsingClause`
523540 NoUsing :: UsingClause commons schemas params '[]
524− -- | An `also` list of table expressions, allowing columns
525− -- from other tables to appear in the WHERE condition.
526− -- This is similar to the list of tables that can be specified
527− -- in the FROM Clause of a SELECT statement;
528− -- for example, an alias for the table name can be specified.
529− -- Do not repeat the target table in the `Using` list,
530− -- unless you wish to set up a self-join.
531541 Using
532542 :: FromClause '[] commons schemas params from
543+ -- ^ what to use
533544 -> UsingClause commons schemas params from
534545
535546-- | Delete rows from a table.
536547deleteFrom
537548 :: ( SOP.SListI row1
538− , db ~ (commons :=> schemas)
539549 , Has sch schemas schema
540550 , Has tab schema ('Table table)
541551 , row0 ~ TableToRow table
@@ -557,8 +567,7 @@ deleteFrom tab using wh returning = UnsafeManipulation $
557567
558568-- | Delete rows returning `Nil`.
559569deleteFrom_
560− :: ( db ~ (commons :=> schemas)
561− , Has sch schemas schema
570+ :: ( Has sch schemas schema
562571 , Has tab schema ('Table table)
563572 , row ~ TableToRow table
564573 , columns ~ TableToColumns table )