Update haddocks

Author: tathougies

beam-core/Database/Beam.hs

@@ -2,7 +2,7 @@
 -- | Top-level Beam module. This module re-exports all the symbols
 --   necessary for most common user operations.
 --
---   The most interesting modules are 'Database.Beam.Schema' and 'Database.Beam.Query'.
+--   The most interesting modules are "Database.Beam.Schema" and "Database.Beam.Query".
 --
 --   This is mainly reference documentation. Most users will want to consult the
 --   [manual](https://tathougies.github.io/beam).

beam-core/Database/Beam/Backend/SQL.hs

@@ -22,7 +22,7 @@ import Control.Monad.IO.Class
 --
 --   Provided here is a low-level interface. Most often, you'll only need the
 --   'withDatabase' and 'withDatabaseDebug' function. The 'run*' functions are
---   wrapped by the appropriate functions in 'Database.Beam.Query'.
+--   wrapped by the appropriate functions in "Database.Beam.Query".
 --
 --   This interface is very high-level and isn't meant to expose the full power
 --   of the underlying database. Namely, it only supports simple data retrieval

beam-core/Database/Beam/Backend/SQL/AST.hs

@@ -1,7 +1,7 @@
 {-# LANGUAGE CPP #-}
 {-# LANGUAGE UndecidableInstances #-}
 -- | This module implements an AST type for SQL92. It allows us to realize
---   the call structure of the builders defined in 'Database.Beam.Backend.SQL92'
+--   the call structure of the builders defined in "Database.Beam.Backend.SQL.SQL92"
 module Database.Beam.Backend.SQL.AST where
 
 import Prelude hiding (Ordering)

beam-migrate/Database/Beam/Migrate.hs

@@ -34,13 +34,13 @@
 --
 -- As one final point, @beam-migrate@ can generate schemas in any beam-supported
 -- SQL DDL syntax. The @beam-migrate@ module provides a DDL syntax for Haskell
--- in 'Database.Beam.Haskell.Syntax'. This allows @beam-migrate@ to translate
+-- in "Database.Beam.Haskell.Syntax". This allows @beam-migrate@ to translate
 -- predicate sets into the corresponding Haskell schema and the corresponding
 -- Haskell migration script. This reflection allows tool based off of
 -- @beam-migrate@ to support schema generation from an existing database.
 --
 -- For more information on checked databases, see the
--- 'Database.Beam.Migrate.Checks' module.
+-- "Database.Beam.Migrate.Checks" module.
 --
 -- == Migrations
 --
@@ -58,12 +58,12 @@
 -- script in a given backend syntax, or generate an appropriate
 -- 'DatabaseSettings' object for use with the rest of the beam ecosystem.
 --
--- For more information in migrations see 'Database.Beam.Migrate.Types'
+-- For more information in migrations see "Database.Beam.Migrate.Types"
 --
 -- == Syntax
 --
 -- For low-level access to the underlying SQL syntax builders, see
--- 'Database.Beam.Migrate.Syntax'
+-- "Database.Beam.Migrate.SQL.SQL92"
 --
 -- == Advanced features
 --

beam-migrate/Database/Beam/Migrate/Backend.hs

@@ -19,14 +19,14 @@
 -- deserialize them from JSON. Finally, if your backend has custom
 -- 'DatabasePredicate's you will have to provide appropriate 'ActionProvider's
 -- to discover potential actions for your backend. See the documentation for
--- 'Database.Beam.Migrate.Actions' for more information.
+-- "Database.Beam.Migrate.Actions" for more information.
 --
 -- Tools may be interested in the 'SomeBeamMigrationBackend' data type which
 -- provides a monomorphic type to wrap the polymorphic 'BeamMigrationBackend'
 -- type. Currently, @beam-migrate-cli@ uses this type to get the underlying
 -- 'BeamMigrationBackend' via the @hint@ package.
 --
--- For an example migrate backend, see 'Database.Beam.Sqlite.Migrates'
+-- For an example migrate backend, see "Database.Beam.Sqlite.Migrate"
 module Database.Beam.Migrate.Backend
   ( BeamMigrationBackend(..)
   , DdlError

beam-migrate/Database/Beam/Migrate/Simple.hs

@@ -39,9 +39,15 @@ import qualified Data.Text as T
 data BringUpToDateHooks m
   = BringUpToDateHooks
   { runIrreversibleHook :: m Bool
+    -- ^ Called before we're about to run an irreversible migration step. Return
+    -- 'True' to run the step, or 'False' to abort immediately.
   , startStepHook       :: Int -> T.Text -> m ()
+    -- ^ Called at the beginning of each step with the step index and description
   , endStepHook         :: Int -> T.Text -> m ()
+    -- ^ Called at the end of each step with the step index and description
   , runCommandHook      :: Int -> String -> m ()
+    -- ^ Called before a command is about to run. The first argument is the step
+    -- index and the second is a string representing the command about to be run.
 
   , queryFailedHook     :: m ()
     -- ^ Called when a query fails
@@ -56,6 +62,8 @@ data BringUpToDateHooks m
     -- the number of entries passed the given migrations the database has.
   }
 
+-- | Default set of 'BringUpToDateHooks'. Refuses to run irreversible
+-- migrations, and fails in case of error, using 'fail'.
 defaultUpToDateHooks :: Monad m => BringUpToDateHooks m
 defaultUpToDateHooks =
   BringUpToDateHooks
@@ -76,16 +84,24 @@ defaultUpToDateHooks =
         fail ("The database is ahead of the known schema by " ++ show aheadBy ++ " migration(s)")
   }
 
--- | Check for the beam-migrate log. If it exists, use it and the supplied
--- migrations to bring the database up-to-date. Otherwise, create the log and
--- run all migrations.
+-- | Equivalent to calling 'bringUpToDateWithHooks' with 'defaultUpToDateHooks'.
+--
+-- Tries to bring the database up to date, using the database log and the given
+-- 'MigrationSteps'. Fails if the migration is irreversible, or an error occurs.
 bringUpToDate :: Database be db
               => BeamMigrationBackend cmd be hdl m
               -> MigrationSteps cmd () (CheckedDatabaseSettings be db)
               -> m (Maybe (CheckedDatabaseSettings be db))
 bringUpToDate be@BeamMigrationBackend {} =
   bringUpToDateWithHooks defaultUpToDateHooks be
 
+-- | Check for the beam-migrate log. If it exists, use it and the supplied
+-- migrations to bring the database up-to-date. Otherwise, create the log and
+-- run all migrations.
+--
+-- Accepts a set of hooks that can be used to customize behavior. See the
+-- documentation for 'BringUpToDateHooks' for more information. Calling this
+-- with 'defaultUpToDateHooks' is the same as using 'bringUpToDate'.
 bringUpToDateWithHooks :: forall db cmd be hdl m
                         . Database be db
                        => BringUpToDateHooks m
@@ -178,6 +194,10 @@ createSchema BeamMigrationBackend { backendActionProvider = actions } db =
     Just cmds ->
         mapM_ runNoReturn cmds
 
+-- | Given a 'BeamMigrationBackend', attempt to automatically bring the current
+-- database up-to-date with the given 'CheckedDatabaseSettings'. Fails (via
+-- 'fail') if this involves an irreversible migration (one that may result in
+-- data loss).
 autoMigrate :: Database be db
             => BeamMigrationBackend cmd be hdl m
             -> CheckedDatabaseSettings be db

beam-migrate/Database/Beam/Migrate/Types.hs

@@ -40,15 +40,11 @@ module Database.Beam.Migrate.Types
   , MigrationCommand(..), MigrationDataLoss(..)
 
   , runMigrationSteps, runMigrationSilenced
-  , runMigrationVerbose, executeMigration
-  , eraseMigrationType, migrationStep, upDown
-  , migrationDataLoss
+  , executeMigration, eraseMigrationType, migrationStep
+  , upDown, migrationDataLoss
 
   , migrateScript, evaluateDatabase, stepNames ) where
 
-import Database.Beam
-import Database.Beam.Backend
-
 import Database.Beam.Migrate.Types.CheckedEntities
 import Database.Beam.Migrate.Types.Predicates
 
@@ -61,19 +57,27 @@ import Data.Text (Text)
 
 -- * Migration types
 
+-- | Represents a particular step in a migration
 data MigrationStep syntax next where
     MigrationStep :: Text -> Migration syntax a -> (a -> next) -> MigrationStep syntax next
 deriving instance Functor (MigrationStep syntax)
+
+-- | A series of 'MigrationStep's that take a database from the schema in @from@
+-- to the one in @to@. Use the 'migrationStep' function and the arrow interface
+-- to sequence 'MigrationSteps'.
 newtype MigrationSteps syntax from to = MigrationSteps (Kleisli (F (MigrationStep syntax)) from to)
   deriving (Category, Arrow)
 
+-- | Free monadic function for 'Migration's
 data MigrationF syntax next where
   MigrationRunCommand
     :: { _migrationUpCommand   :: syntax {-^ What to execute when applying the migration -}
        , _migrationDownCommand :: Maybe syntax {-^ What to execute when unapplying the migration -}
        , _migrationNext :: next }
     -> MigrationF syntax next
 deriving instance Functor (MigrationF syntax)
+
+-- | A sequence of potentially reversible schema update commands
 type Migration syntax = F (MigrationF syntax)
 
 -- | Information on whether a 'MigrationCommand' loses data. You can
@@ -101,10 +105,14 @@ data MigrationCommand cmd
     -- ^ Information on whether the migration loses data
   } deriving Show
 
+-- | Run the migration steps between the given indices, using a custom execution function.
 runMigrationSteps :: Monad m
-                  => Int -> Maybe Int
-                  -> MigrationSteps syntax () a
+                  => Int -- ^ Zero-based index of the first step to run
+                  -> Maybe Int -- ^ Index of the last step to run, or 'Nothing' to run every step
+                  -> MigrationSteps syntax () a -- ^ The set of steps to run
                   -> (forall a'. Int -> Text -> Migration syntax a' -> m a')
+                  -- ^ Callback for each step. Called with the step index, the
+                  -- step description and the migration.
                   -> m a
 runMigrationSteps firstIdx lastIdx (MigrationSteps steps) runMigration =
   runF (runKleisli steps ()) finish step 0
@@ -114,33 +122,37 @@ runMigrationSteps firstIdx lastIdx (MigrationSteps steps) runMigration =
           then runMigration i nm doStep >>= \x -> next x (i + 1)
           else next (runMigrationSilenced doStep) (i + 1)
 
+-- | Get the result of a migration, without running any steps
 runMigrationSilenced :: Migration syntax a -> a
 runMigrationSilenced m = runF m id step
   where
     step (MigrationRunCommand _ _ next) = next
 
-runMigrationVerbose :: MonadBeam syntax be hdl m => (syntax -> String)
-                    -> Migration syntax a -> m a
-runMigrationVerbose renderMigrationSyntax steps =
-  runF steps finish step
-  where finish = pure
-        step (MigrationRunCommand up _ next) =
-          do liftIO (putStrLn (renderMigrationSyntax up))
-             runNoReturn up
-             next
-
+-- | Remove the explicit source and destination schemas from a 'MigrationSteps' object
 eraseMigrationType :: a -> MigrationSteps syntax a a' -> MigrationSteps syntax () ()
 eraseMigrationType a (MigrationSteps steps) = MigrationSteps (arr (const a) >>> steps >>> arr (const ()))
 
+-- | Create a 'MigrationSteps' from the given description and migration function.
 migrationStep :: Text -> (a -> Migration syntax a') -> MigrationSteps syntax a a'
 migrationStep stepName migration =
     MigrationSteps (Kleisli (\a -> liftF (MigrationStep stepName (migration a) id)))
 
+-- | Given a command in the forward direction, and an optional one in the
+-- reverse direction, construct a 'Migration' that performs the given
+-- command. Multiple commands can be sequenced monadically.
 upDown :: syntax -> Maybe syntax -> Migration syntax ()
 upDown up down = liftF (MigrationRunCommand up down ())
 
-migrateScript :: forall syntax m a.
-                 Monoid m => (Text -> m) -> (syntax -> m) -> MigrationSteps syntax () a -> m
+-- | Given functions to render a migration step description and the underlying
+-- syntax, create a script for the given 'MigrationSteps'.
+migrateScript :: forall syntax m a. Monoid m
+              => (Text -> m)
+              -- ^ Called at the beginning of each 'MigrationStep' with the step description
+              -> (syntax -> m)
+              -- ^ Called for each command in the migration step
+              -> MigrationSteps syntax () a
+              -- ^ The set of steps to run
+              -> m
 migrateScript renderMigrationHeader renderMigrationSyntax (MigrationSteps steps) =
   runF (runKleisli steps ()) (\_ x -> x)
     (\(MigrationStep header migration next) x ->
@@ -168,16 +180,18 @@ migrationDataLoss go = runF go (\_ -> MigrationKeepsData)
                               Nothing -> MigrationLosesData
                               _ -> next)
 
+-- | Run a 'MigrationSteps' without executing any of the commands against a
+-- database.
 evaluateDatabase :: forall syntax a. MigrationSteps syntax () a -> a
 evaluateDatabase (MigrationSteps f) = runF (runKleisli f ()) id (\(MigrationStep _ migration next) -> next (runMigration migration))
   where
     runMigration :: forall a'. Migration syntax a' -> a'
     runMigration migration = runF migration id (\(MigrationRunCommand _ _ next) -> next)
 
+-- | Collect the names of all steps in hte given 'MigrationSteps'
 stepNames :: forall syntax a. MigrationSteps syntax () a -> [Text]
 stepNames (MigrationSteps f) = runF (runKleisli f ()) (\_ x -> x) (\(MigrationStep nm migration next) x -> next (runMigration migration) (x ++ [nm])) []
   where
     runMigration :: forall a'. Migration syntax a' -> a'
     runMigration migration = runF migration id (\(MigrationRunCommand _ _ next) -> next)
 
--- * Checked database entities

beam-postgres/Database/Beam/Postgres/Full.hs

@@ -64,6 +64,8 @@ instance Monoid (PgLockedTables s) where
   mempty = PgLockedTables []
   mappend (PgLockedTables a) (PgLockedTables b) = PgLockedTables (a <> b)
 
+-- | Combines the result of a query along with a set of locked tables. Used as a
+-- return value for the 'lockingFor_' function.
 data PgWithLocking s a = PgWithLocking (PgLockedTables s) a
 instance ProjectibleWithPredicate c syntax a => ProjectibleWithPredicate c syntax (PgWithLocking s a) where
   project' p mutateM (PgWithLocking tbls a) =
@@ -73,7 +75,7 @@ instance ProjectibleWithPredicate c syntax a => ProjectibleWithPredicate c synta
 lockAll_ :: a -> PgWithLocking s a
 lockAll_ = PgWithLocking mempty
 
--- | Return and lock the given tables. Typically used as an infix operator. See
+-- | Return and lock the given tables. Typically used as an infix operator. See the
 -- <http://tathougies.github.io/beam/user-guide/backends/beam-postgres/ the user guide> for usage
 -- examples
 withLocks_ :: a -> PgLockedTables s -> PgWithLocking s a
@@ -89,8 +91,8 @@ locked_ (DatabaseEntity (DatabaseTable tblNm tblSettings)) = do
   pure (PgLockedTables [nm], joined)
 
 -- | Lock some tables during the execution of a query. This is rather complicated, and there are
--- several usage examples in <http://tathougies.github.io/beam/user-guide/backends/beam-postgres/
--- the user guide>
+-- several usage examples in
+-- <http://tathougies.github.io/beam/user-guide/backends/beam-postgres/ the user guide>
 --
 -- The Postgres locking clause is rather complex, and beam currently does not check several
 -- pre-conditions. It is assumed you kinda know what you're doing.

beam-postgres/Database/Beam/Postgres/PgSpecific.hs

@@ -49,6 +49,7 @@ module Database.Beam.Postgres.PgSpecific
   , pgSumMoney_, pgAvgMoney_
 
     -- ** Set-valued functions
+    -- $set-valued-funs
   , PgSetOf, pgUnnest
   , pgUnnestArray, pgUnnestArrayWithOrdinality
 
@@ -431,15 +432,20 @@ instance ToJSON a => HasSqlValueSyntax PgValueSyntax (PgJSONB a) where
     PgValueSyntax $
     emit "'" <> escapeString (BL.toStrict (encode a)) <> emit "'::jsonb"
 
+-- | Key-value pair, used as output of 'pgJsonEachText' and 'pgJsonEach'
 data PgJSONEach valType f
-  = PgJSONEach { pgJsonEachKey :: C f T.Text, pgJsonEachValue :: C f valType }
-  deriving Generic
+  = PgJSONEach
+  { pgJsonEachKey :: C f T.Text
+  , pgJsonEachValue :: C f valType
+  } deriving Generic
 instance Beamable (PgJSONEach valType)
 
+-- | Output row of 'pgJsonKeys'
 data PgJSONKey f = PgJSONKey { pgJsonKey :: C f T.Text }
   deriving Generic
 instance Beamable PgJSONKey
 
+-- | Output row of 'pgJsonArrayElements' and 'pgJsonArrayElementsText'
 data PgJSONElement a f = PgJSONElement { pgJsonElement :: C f a }
   deriving Generic
 instance Beamable (PgJSONElement a)
@@ -451,8 +457,6 @@ instance Beamable (PgJSONElement a)
 -- section on
 -- <https://www.postgresql.org/docs/current/static/functions-json.html JSON>.
 --
--- Note that @beam-postgres@ does not yet support @setof@ so some functions are
--- missing. PRs to implement this functionality are welcome!
 class IsPgJSON (json :: * -> *) where
   -- | The @json_each@ or @jsonb_each@ function. Values returned as @json@ or
   -- @jsonb@ respectively. Use 'pgUnnest' to join against the result
@@ -985,3 +989,29 @@ instance HasDefaultSqlDataTypeConstraints PgColumnSchemaSyntax (V.Vector a)
 -- For more information on Psotgres json support see the postgres
 -- <https://www.postgresql.org/docs/current/static/functions-json.html manual>.
 
+
+-- $set-valued-funs
+--
+-- Postgres supports functions that returns /sets/. We can join directly against
+-- these sets or arrays. @beam-postgres@ supports this feature via the
+-- 'pgUnnest' and 'pgUnnestArray' functions.
+--
+-- Any function that returns a set can be typed as an expression returning
+-- 'PgSetOf'. This polymorphic type takes one argument, which is a 'Beamable'
+-- type that represents the shape of the data in the rows. For example, the
+-- @json_each@ function returns a key and a value, so the corresponding
+-- @beam-postgres@ function ('pgJsonEach') returns a value of type 'PgSetOf
+-- (PgJSONEach Value)', which represents a set containing 'PgJSONEach'
+-- rows. 'PgJSONEach' is a table with a column for keys ('pgJsonEachKey') and
+-- one for values ('pgJsonEachValue').
+--
+-- Any 'PgSetOf' value can be introduced into the 'Q' monad using the 'pgUnnest'
+-- function.
+--
+-- Postgres arrays (represented by the 'V.Vector' type) can also be joined
+-- against using the 'pgUnnestArray' function. This directly corresponds to the
+-- SQL @UNNEST@ keyword. Unlike sets, arrays have a sense of order. The
+-- 'pgUnnestArrayWithOrdinality' function allows you to join against the
+-- elements of an array along with its index. This corresponds to the
+-- @UNNEST .. WITH ORDINALITY@ clause.
+