From 2d0d70fd60c93f6aa29ddadd9e40d83670f3a660 Mon Sep 17 00:00:00 2001
From: patrick brisbin <pbrisbin@gmail.com>
Date: Tue, 13 Sep 2011 21:55:11 -0400
Subject: [PATCH] bring comments back in

---
 yesod/Yesod/Settings.hs | 41 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/yesod/Yesod/Settings.hs b/yesod/Yesod/Settings.hs
index 7b924472..148b081a 100644
--- a/yesod/Yesod/Settings.hs
+++ b/yesod/Yesod/Settings.hs
@@ -23,13 +23,41 @@ data AppEnvironment = Development
                     | Production
                     deriving (Eq, Show, Read, Enum, Bounded)
 
+-- | Dynamic per-environment configuration which can be loaded at
+--   run-time negating the need to recompile between environments.
 data AppConfig = AppConfig
-    { appEnv             :: AppEnvironment
-    , appPort            :: Int
+    { appEnv  :: AppEnvironment
+    , appPort :: Int
+
+    -- | Your application will keep a connection pool and take
+    --   connections from there as necessary instead of continually
+    --   creating new connections. This value gives the maximum number
+    --   of connections to be open at a given time. If your application
+    --   requests a connection when all connections are in use, that
+    --   request will fail. Try to choose a number that will work well
+    --   with the system resources available to you while providing
+    --   enough connections for your expected load.
+    --
+    --   Connections are returned to the pool as quickly as possible by
+    --   Yesod to avoid resource exhaustion. A connection is only
+    --   considered in use while within a call to runDB.
     , connectionPoolSize :: Int
-    , appRoot            :: Text
+
+    -- | The base URL for your application. This will usually be
+    --   different for development and production. Yesod automatically
+    --   constructs URLs for you, so this value must be accurate to
+    --   create valid links.
+    --
+    --   If your domain name was "yesod.com", you would probably want it
+    --   to be:
+    --
+    --   > "http://yesod.com"
+    --
+    , appRoot :: Text
     } deriving (Show)
 
+-- | Load an @'AppConfig'@ from a YAML-formatted file located at
+--   @config\/settings.yml@.
 loadConfig :: AppEnvironment -> IO AppConfig
 loadConfig env = do
     allSettings <- (join $ YAML.decodeFile ("config/settings.yml" :: String)) >>= fromMapping
@@ -51,6 +79,8 @@ loadConfig env = do
             Production -> ""
             _          -> ":" ++ show p
 
+-- | Load Postgresql settings from a YAML-formatted file located at
+--   @config\/postgresql.yml@.
 loadPostgresqlConnStr :: AppEnvironment -> IO Text
 loadPostgresqlConnStr env = do
     allSettings <- (join $ YAML.decodeFile ("config/postgresql.yml" :: String)) >>= fromMapping
@@ -62,13 +92,16 @@ loadPostgresqlConnStr env = do
       return $ [st| #{key}=#{value} |]
     return $ [st|#{connPart} dbname=#{database}|]
 
+-- | Load Sqlite settings from a YAML-formatted file located at
+--   @config\/sqlite.yml@.
 loadSqliteConnStr :: AppEnvironment -> IO Text
 loadSqliteConnStr env = do
     allSettings <- (join $ YAML.decodeFile ("config/sqlite.yml" :: String)) >>= fromMapping
     settings    <- lookupMapping (show env) allSettings
     lookupScalar "database" settings
 
--- note: no type signature to avoid Persistent.MongoDB dep
+-- note: no type signature to avoid an extra Persistent.MongoDB dep for
+-- those that don't need it
 --loadMongoConnParams :: AppEnvironment -> IO (Database, HostName)
 loadMongoConnParams env = do
     allSettings <- (join $ YAML.decodeFile ("config/mongoDB.yml" :: String)) >>= fromMapping