From 5a38daeff2f836784888ad15e24f6c63367f7c3a Mon Sep 17 00:00:00 2001 From: Jade Lovelace Date: Tue, 27 Sep 2022 10:11:10 -0700 Subject: [PATCH] Fix docs for discoverEntities being jacked (#1428) * Fix docs for discoverEntities being jacked I have literally no idea why haddock was unhappy about them before, but I just changed it to a block comment and it worked. * Update changelog --- persistent/ChangeLog.md | 5 ++ persistent/Database/Persist/TH.hs | 110 +++++++++++++++--------------- persistent/persistent.cabal | 2 +- 3 files changed, 62 insertions(+), 55 deletions(-) diff --git a/persistent/ChangeLog.md b/persistent/ChangeLog.md index a1e80a5c6..5dba2c2c9 100644 --- a/persistent/ChangeLog.md +++ b/persistent/ChangeLog.md @@ -1,5 +1,10 @@ # Changelog for persistent +## 2.14.3.1 + +* [#1428](https://github.com/yesodweb/persistent/pull/1428) + * Fix that the documentation for `discoverEntities` was not being generated. + ## 2.14.3.0 * [#1425](https://github.com/yesodweb/persistent/pull/1425) diff --git a/persistent/Database/Persist/TH.hs b/persistent/Database/Persist/TH.hs index e54ab099f..7c7958abc 100644 --- a/persistent/Database/Persist/TH.hs +++ b/persistent/Database/Persist/TH.hs @@ -3147,60 +3147,62 @@ filterConName' mps entity field = mkName $ T.unpack name entityName = unEntityNameHS entity fieldName = upperFirst $ unFieldNameHS field --- | Splice in a list of all 'EntityDef' in scope. This is useful when running --- 'mkPersist' to ensure that all entity definitions are available for setting --- foreign keys, and for performing migrations with all entities available. --- --- 'mkPersist' has the type @MkPersistSettings -> [EntityDef] -> DecsQ@. So, to --- account for entities defined elsewhere, you'll @mappend $(discoverEntities)@. --- --- For example, --- --- @ --- share --- [ mkPersistWith sqlSettings $(discoverEntities) --- ] --- [persistLowerCase| ... |] --- @ --- --- Likewise, to run migrations with all entity instances in scope, you'd write: --- --- @ --- migrateAll = migrateModels $(discoverEntities) --- @ --- --- Note that there is some odd behavior with Template Haskell and splicing --- groups. If you call 'discoverEntities' in the same module that defines --- 'PersistEntity' instances, you need to ensure they are in different top-level --- binding groups. You can write @$(pure [])@ at the top level to do this. --- --- @ --- -- Foo and Bar both export an instance of PersistEntity --- import Foo --- import Bar --- --- -- Since Foo and Bar are both imported, discoverEntities can find them here. --- mkPersistWith sqlSettings $(discoverEntities) [persistLowerCase| --- User --- name Text --- age Int --- |] --- --- -- onlyFooBar is defined in the same 'top level group' as the above generated --- -- instance for User, so it isn't present in this list. --- onlyFooBar :: [EntityDef] --- onlyFooBar = $(discoverEntities) --- --- -- We can manually create a new binding group with this, which splices an --- -- empty list of declarations in. --- $(pure []) --- --- -- fooBarUser is able to see the 'User' instance. --- fooBarUser :: [EntityDef] --- fooBarUser = $(discoverEntities) --- @ --- --- @since 2.13.0.0 +{-| +Splice in a list of all 'EntityDef' in scope. This is useful when running +'mkPersist' to ensure that all entity definitions are available for setting +foreign keys, and for performing migrations with all entities available. + +'mkPersist' has the type @MkPersistSettings -> [EntityDef] -> DecsQ@. So, to +account for entities defined elsewhere, you'll @mappend $(discoverEntities)@. + +For example, + +@ +share + [ mkPersistWith sqlSettings $(discoverEntities) + ] + [persistLowerCase| ... |] +@ + +Likewise, to run migrations with all entity instances in scope, you'd write: + +@ +migrateAll = migrateModels $(discoverEntities) +@ + +Note that there is some odd behavior with Template Haskell and splicing +groups. If you call 'discoverEntities' in the same module that defines +'PersistEntity' instances, you need to ensure they are in different top-level +binding groups. You can write @$(pure [])@ at the top level to do this. + +@ +-- Foo and Bar both export an instance of PersistEntity +import Foo +import Bar + +-- Since Foo and Bar are both imported, discoverEntities can find them here. +mkPersistWith sqlSettings $(discoverEntities) [persistLowerCase| + User + name Text + age Int + |] + +-- onlyFooBar is defined in the same 'top level group' as the above generated +-- instance for User, so it isn't present in this list. +onlyFooBar :: [EntityDef] +onlyFooBar = $(discoverEntities) + +-- We can manually create a new binding group with this, which splices an +-- empty list of declarations in. +$(pure []) + +-- fooBarUser is able to see the 'User' instance. +fooBarUser :: [EntityDef] +fooBarUser = $(discoverEntities) +@ + +@since 2.13.0.0 +-} discoverEntities :: Q Exp discoverEntities = do instances <- reifyInstances ''PersistEntity [VarT (mkName "a")] diff --git a/persistent/persistent.cabal b/persistent/persistent.cabal index 71a394384..ad0b7f9f6 100644 --- a/persistent/persistent.cabal +++ b/persistent/persistent.cabal @@ -1,5 +1,5 @@ name: persistent -version: 2.14.3.0 +version: 2.14.3.1 license: MIT license-file: LICENSE author: Michael Snoyman