parsonsmatt · May 7, 2025 · Apr 14, 2025 · May 7, 2025 · May 7, 2025 · May 7, 2025
diff --git a/persistent/ChangeLog.md b/persistent/ChangeLog.md
@@ -1,5 +1,10 @@
 # Changelog for persistent
 
+# 2.15.1.1 (unreleased)
+
+* [#1587](https://github.com/yesodweb/persistent/pull/1587)
+    * Improve documentation of `mpsFieldLabelModifier`.
+
 # 2.15.1.0
 
 * [#1519](https://github.com/yesodweb/persistent/pull/1519/files/9865a295f4545d30e55aacb6efc25f27f758e8ad#diff-5af2883367baae8f7f266df6a89fc2d1defb7572d94ed069e05c8135a883bc45)

diff --git a/persistent/Database/Persist/TH/Internal.hs b/persistent/Database/Persist/TH/Internal.hs
@@ -1053,7 +1053,9 @@ fixEntityDef ued =
             filter isHaskellUnboundField (unboundEntityFields ued)
         }
 
--- | Settings to be passed to the 'mkPersist' function.
+-- | Settings that can be passed to the 'mkPersist' (mps) function to control what code is generated.
+-- This is (just) the data type definition, so you will most likely want to use and adapt concrete values
+-- like 'sqlSettings'.
 data MkPersistSettings = MkPersistSettings
     { mpsBackend :: Type
     -- ^ Which database backend we\'re using. This type is used for the
@@ -1079,15 +1081,63 @@ data MkPersistSettings = MkPersistSettings
     , mpsPrefixFields :: Bool
     -- ^ Prefix field names with the model name. Default: True.
     --
-    -- Note: this field is deprecated. Use the mpsFieldLabelModifier  and
+    -- Note: this field is deprecated. Use the 'mpsFieldLabelModifier'  and
     -- 'mpsConstraintLabelModifier' instead.
     , mpsFieldLabelModifier :: Text -> Text -> Text
-    -- ^ Customise the field accessors and lens names using the entity and field
-    -- name.  Both arguments are upper cased.
+    -- ^ Customise the field names (and lens names) for generated entity data types.
     --
-    -- Default: appends entity and field.
+    -- Default: appends entity name and field name, equivalent to
     --
-    -- Note: this setting is ignored if mpsPrefixFields is set to False.
+    -- @
+    -- mpsFieldLabelModifier = \\entityName fieldName -> entityName <> fieldName
+    -- @
+    --
+    -- to avoid duplicate record field collisions.
+    --
+    -- For example, with default 'sqlSettings' and
+    --
+    -- @
+    -- 'mkPersistWith' 'sqlSettings' [] ['persistLowerCase'|
+    --     Person
+    --         name   Text
+    --         age    Int
+    -- |]
+    -- @
+    --
+    -- it will generate the entity data type
+    --
+    -- @
+    -- Person {
+    --     personName :: Text,  -- generated field name
+    --     personAge  :: Int    -- generated field name
+    -- }
+    -- @
+    --
+    -- Note: this setting is ignored if the deprecated 'mpsPrefixFields' is set to False.
+    --
+    -- === __Example without entity name__
+    --
+    -- You may not want the entity name prefix for all fields, so use
+    --
+    -- @
+    -- 'mkPersistWith' ('sqlSettings' { mpsFieldLabelModifier = \\\_entityName fieldName -> fieldName }) [] ['persistLowerCase'|
+    --     Person
+    --         name   Text
+    --         age    Int
+    -- |]
+    -- @
+    --
+    -- instead. This will generate the entity data type
+    --
+    -- @
+    -- Person {
+    --     name :: Text,
+    --     age  :: Int
+    -- }
+    -- @
+    --
+    -- When you have multiple entites with the same field name, you might need to
+    -- add @{-# LANGUAGE DuplicateRecordFields #-}@ for your code to compile.
     --
     -- @since 2.11.0.0
     , mpsAvoidHsKeyword :: Text -> Text
@@ -1102,7 +1152,7 @@ data MkPersistSettings = MkPersistSettings
     --
     -- Default: appends entity and field
     --
-    -- Note: this setting is ignored if mpsPrefixFields is set to False.
+    -- Note: this setting is ignored if the deprecated 'mpsPrefixFields' is set to False.
     --
     -- @since 2.11.0.0
     , mpsEntityHaddocks :: Bool