From f33387d99d57991c4df4cf64f8bf56e28b34a385 Mon Sep 17 00:00:00 2001
From: LukeTemp <38944835+LukeTemp@users.noreply.github.com>
Date: Mon, 11 Dec 2023 18:18:11 +0000
Subject: [PATCH] Update haddocks

- Add example usage to optionsFromList'.
- Explain optionsEnum' using optionsFromList'.
---
 yesod-form/Yesod/Form/Option.hs | 66 +++++++++++++++++++++++++++++++--
 1 file changed, 62 insertions(+), 4 deletions(-)

diff --git a/yesod-form/Yesod/Form/Option.hs b/yesod-form/Yesod/Form/Option.hs
index 72ea58933..7185d863f 100644
--- a/yesod-form/Yesod/Form/Option.hs
+++ b/yesod-form/Yesod/Form/Option.hs
@@ -7,9 +7,61 @@ import Yesod.Form.Fields
 
 -- | Creates an 'OptionList' from a 'List', using the 'PathPiece' instance for
 -- the external value and a custom function for the user-facing value.
--- NB: We choose PathPiece as the most suitable class for generating External
--- Values. The motivation is to avoid Show/Read instances which could leak
--- an internal representation to forms, query params, javascript etc.
+-- 
+-- PathPiece instances should provide suitable external values, since path
+-- pieces serve to be exposed through URLs or HTML anyway. Show/Read instances
+-- are avoided here since they could leak internal representations to forms,
+-- query params, javascript etc.
+--
+-- === __Example usage__
+--
+-- @messages/en.msg
+-- > MsgSalesTeam: Sales Team
+-- > MsgSalesHead: Head of Sales Team
+-- > MsgTechTeam: Tech Team
+-- > MsgTechHead: Head of Tech Team
+--
+-- @example.hs
+-- > data UserRole = URSalesTeam | URSalesHead | URTechTeam | URTechHead
+--
+-- > instance PathPiece UserDepartment where
+-- >   toPathPiece = \case
+-- >     URSalesTeam -> "sales-team"
+-- >     URSalesHead -> "sales-head"
+-- >     URTechTeam -> "tech-team"
+-- >     URTechHead -> "tech-head"
+-- >   fromPathPiece = \case
+-- >     "sales-team" -> Just URSalesTeam
+-- >     "sales-head" -> Just URSalesHead
+-- >     "tech-team" -> Just URTechTeam
+-- >     "tech-head" -> Just URTechHead
+-- >     _ -> Nothing
+--
+-- > userRoleOptions ::
+-- >   (MonadHandler m, RenderMessage (HandlerSite m) msg) => m (OptionList UserRole)
+-- > userRoleOptions = optionsFromList' userRoles toMsg
+-- >   where
+-- >   userRoles = [URSalesTeam, URSalesHead, URTechTeam, URTechHead]
+-- >   toMsg = \case
+-- >     URSalesTeam -> MsgSalesTeam
+-- >     URSalesHead -> MsgSalesHead
+-- >     URTechTeam -> MsgTechTeam
+-- >     URTechHead -> MsgTechHead
+--
+-- userRoleOptions, will produce an OptionList with the following attributes:
+--
+-- > +----------------+----------------+--------------------+
+-- > | Internal Value | External Value | User-facing Value  |
+-- > +----------------+----------------+--------------------+
+-- > | URSalesTeam    | sales-team     | Sales Team         |
+-- > +----------------+----------------+--------------------+
+-- > | URSalesHead    | sales-head     | Head of Sales Team |
+-- > +----------------+----------------+--------------------+
+-- > | URTechTeam     | tech-team      | Tech Team          |
+-- > +----------------+----------------+--------------------+
+-- > | URTechHead     | tech-head      | Head of Tech Team  |
+-- > +----------------+----------------+--------------------+
+
 optionsFromList' ::
      MonadHandler m
   => RenderMessage (HandlerSite m) msg
@@ -25,7 +77,13 @@ optionsFromList' lst toDisplay = do
     , optionExternalValue = toPathPiece v
     }
 
--- | Creates an 'OptionList' from an 'Enum'
+-- | Creates an 'OptionList' from an 'Enum'.
+-- 
+-- optionsEnum' == optionsFromList' [minBound..maxBound]
+-- 
+-- Useful when the order in which the options appear is not important
+-- to the user (or if the order should match the explicit ordering of
+-- constructors in the type definition).
 optionsEnum' ::
      MonadHandler m
   => RenderMessage (HandlerSite m) msg