Skip to content

Improve documentation of wrapSite, runSnaplet and serveSnaplet #44

Merged
merged 2 commits into from Sep 20, 2012
View
39 src/Snap/Snaplet/Internal/Initializer.hs
@@ -367,15 +367,14 @@ addRoutes rs = do
------------------------------------------------------------------------------
--- | Wraps the snaplet's routing. When all is said and done, a snaplet's
--- routes end up getting combined into a single 'Handler' action. This
--- function allows you to modify that Handler before it actually gets served.
--- This allows you to do things that need to happen for every request handled
--- by your snaplet. Here are some examples of things you might do:
+-- | Wraps the /base/ snaplet's routing in another handler, allowing you to run
+-- code before and after all routes in an application.
+--
+-- Here are some examples of things you might do:
+--
+-- > wrapSite (\site -> logHandlerStart >> site >> logHandlerFinished)
+-- > wrapSite (\site -> ensureAdminUser >> site)
--
--- @wrapSite (\site -> removePathTrailingSlashes >> site)@
--- @wrapSite (\site -> logHandlerStart >> site >> logHandlerFinished)@
--- @wrapSite (\site -> ensureAdminUser >> site)@
wrapSite :: (Handler b v () -> Handler b v ())
-- ^ Handler modifier function
-> Initializer b v ()
@@ -510,12 +509,12 @@ runInitializer' mvar env b@(Initializer i) cwd = do
------------------------------------------------------------------------------
--- | Given an envirnoment and a Snaplet initializer, produce the set of
--- messages generated during initialization, a snap handler, and a cleanup
--- action. The environment is an arbitrary string such as "devel" or
--- "production". This string is used to determine the name of the config
--- files used each snaplet. If an environment of Nothing is used, then
--- runSnaplet defaults to "devel".
+-- | Given an environment and a Snaplet initializer, produce a concatenated log
+-- of all messages generated during initialization, a snap handler, and a
+-- cleanup action. The environment is an arbitrary string such as \"devel\" or
+-- \"production\". This string is used to determine the name of the
+-- configuration files used by each snaplet. If an environment of Nothing is
+-- used, then runSnaplet defaults to \"devel\".
runSnaplet :: Maybe String -> SnapletInit b b -> IO (Text, Snap (), IO ())
runSnaplet env (SnapletInit b) = do
snapletMVar <- newEmptyMVar
@@ -546,9 +545,15 @@ combineConfig config handler = do
------------------------------------------------------------------------------
--- | Serves a top-level snaplet as a web application. Reads command-line
--- arguments. FIXME: document this.
-serveSnaplet :: Config Snap AppConfig -> SnapletInit b b -> IO ()
+-- | Initialize and run a Snaplet. This function parses command-line arguments,
+-- runs the given Snaplet initializer, and starts an HTTP server running the
+-- Snaplet's toplevel 'Handler'.
+serveSnaplet :: Config Snap AppConfig
+ -- ^ The configuration of the server - you can usually pass a
+ -- default 'Config' via 'Snap.Http.Server.Config.defaultConfig'.
+ -> SnapletInit b b
+ -- ^ The snaplet initializer function.
+ -> IO ()
serveSnaplet startConfig initializer = do
config <- commandLineAppConfig startConfig
let env = appEnvironment =<< getOther config
Something went wrong with that request. Please try again.