Fix some unescaped markup in haddocks (#316)

* Fix some unescaped markup in haddocks This addresses #315 * Expand documentation on unsafeDefault This copies the documentation in the cookbook to the haddocks, addressing #233. * Update docs/concepts/insert.rst Co-authored-by: Ollie Charles <[email protected]> --------- Co-authored-by: Ollie Charles <[email protected]>
circuithub · Mar 19, 2024 · f1caa45 · f1caa45
1 parent f7d3fa6
commit f1caa45
Show file tree

Hide file tree

Showing 3 changed files with 17 additions and 12 deletions.
diff --git a/docs/concepts/insert.rst b/docs/concepts/insert.rst
@@ -167,7 +167,7 @@ construct the ``DEFAULT`` expression::
 .. warning::
    Also note PostgreSQL's syntax rules mean that ``DEFAULT``` can only appear
    in ``INSERT``` expressions whose rows are specified using ``VALUES``. This
-   means that the ``rows`` field of your ``Insert`` record doesn't look like
+   means that if the ``rows`` field of your ``Insert`` record doesn't look like
    ``values [..]``, then ``unsafeDefault`` won't work.
 
 

diff --git a/src/Rel8.hs b/src/Rel8.hs
@@ -563,9 +563,9 @@ import Rel8.Window
 -- query = do
 --   thingExpr <- each thingSchema
 --   where_ $
---     deconstructADT @Thing
---       (\employer -> employerName employer ==. lit \"Mary\")
---       (\potato -> grower potato ==. lit \"Mary\")
+--     deconstructADT \@Thing
+--       (\\employer -> employerName employer ==. lit \"Mary\")
+--       (\\potato -> grower potato ==. lit \"Mary\")
 --       (lit False) -- Nullary case
 --       thingExpr
 --   pure thingExpr
@@ -609,10 +609,10 @@ import Rel8.Window
 -- instantiations of 'buildADT' for 'Task':
 --
 -- @
--- > :t buildADT @Task @\"Pending\"
--- buildADT @Task @\"Pending\" :: ADT Task Expr
--- > :t buildADT @Task @\"Complete\"
--- buildADT @Task @\"Complete\" :: CompletedTask Expr -> ADT Task Expr
+-- > :t buildADT \@Task \@\"Pending\"
+-- buildADT \@Task \@\"Pending\" :: ADT Task Expr
+-- > :t buildADT \@Task @\"Complete\"
+-- buildADT \@Task \@\"Complete\" :: CompletedTask Expr -> ADT Task Expr
 -- @
 --
 -- Note that as the "Pending" constructor has no fields, @buildADT
@@ -635,8 +635,8 @@ import Rel8.Window
 -- @
 -- > :{
 -- showQuery $ values
---   [ buildADT @Task @\"Pending\"
---   , buildADT @Task @\"Complete\" CompletedTask {date = Rel8.Expr.Time.now}
+--   [ buildADT \@Task \@\"Pending\"
+--   , buildADT \@Task \@\"Complete\" CompletedTask {date = Rel8.Expr.Time.now}
 --   ]
 -- :}
 -- @
@@ -685,10 +685,10 @@ import Rel8.Window
 -- @
 -- let
 --   pending :: ADT Task Expr
---   pending = constructADT @Task $ \pending _complete -> pending
+--   pending = constructADT \@Task $ \\pending _complete -> pending
 --
 --   complete :: ADT Task Expr
---   complete = constructADT @Task $ \_pending complete -> complete CompletedTask {date = Rel8.Expr.Time.now}
+--   complete = constructADT \@Task $ \\_pending complete -> complete CompletedTask {date = Rel8.Expr.Time.now}
 -- @
 --
 -- These values are otherwise identical to the ones we saw above with

diff --git a/src/Rel8/Expr/Default.hs b/src/Rel8/Expr/Default.hs
@@ -27,6 +27,11 @@ import Rel8.Expr.Opaleye ( fromPrimExpr )
 -- 3. @DEFAULT@ values can not be transformed. For example, the innocuous Rel8
 -- code @unsafeDefault + 1@ will crash, despite type checking.
 --
+-- Also note, PostgreSQL's syntax rules mean that @DEFAULT@ can only appear in
+-- @INSERT@ expressions whose rows are specified using @VALUES@. This means
+-- that if the @rows@ field of your 'Rel8.Insert' record doesn\'t look like
+-- @values [..]@, then @unsafeDefault@ won't work.
+--
 -- Given all these caveats, we suggest avoiding the use of default values where
 -- possible, instead being explicit. A common scenario where default values are
 -- used is with auto-incrementing identifier columns. In this case, we suggest