Skip to content
Browse files

Documentation improvements.

  • Loading branch information...
1 parent 5165115 commit 0908e395acbe5bb83cedc3c44a011a60405cd4c1 @mightybyte mightybyte committed Oct 27, 2011
View
8 src/Snap.hs
@@ -1,3 +1,11 @@
+{-|
+
+This module provides convenience exports of the modules most commonly used
+when developing with the Snap Framework. For documentation about Snaplets,
+see "Snap.Snaplet". For the core web server API, see "Snap.Core".
+
+-}
+
module Snap
( module Control.Applicative
, module Control.Monad.State
View
20 src/Snap/Snaplet.hs
@@ -96,7 +96,6 @@ module Snap.Snaplet
, wrapHandlers
-- * Handlers
- -- $handler
, Handler
, reloadSite
@@ -198,7 +197,7 @@ import Snap.Snaplet.Internal.Types
-- state. This allows quux snaplet functions to access and modify the Quux
-- data structure without knowing anything about the App or Foo data
-- structures. It also lets other snaplets call functions from the quux
--- snaplet if they have the quux snaplet's lens (Lens App (Snaplet Quux)).
+-- snaplet if they have the quux snaplet's lens @Lens App (Snaplet Quux)@.
-- We can view our application as a tree of snaplets and other pieces of data.
-- The lenses are like pointers to nodes of the tree. If you have a pointer to
-- a node, you can access the node and all of its children without knowing
@@ -216,10 +215,10 @@ import Snap.Snaplet.Internal.Types
-- snaplet trees.
-- $snapletState
--- MonadSnaplet instances will typically have (MonadState (Snaplet v))
--- instances. We provide the following convenience functions which give the
--- equivalent to (MonadState v). These functions are what you use to access
--- and manipulate your user-defined snaplet state.
+-- MonadSnaplet instances will typically have @MonadState v@ instances. We
+-- provide the following convenience functions which give the equivalent to
+-- @MonadState (Snaplet v)@ for the less common cases where you need to work
+-- with the Snaplet wrapper.
-- $initializer
-- The Initializer monad is where your application's initialization happens.
@@ -250,15 +249,6 @@ import Snap.Snaplet.Internal.Types
-- 'wrapHandlers'.
--- $handler
--- Snaplet infrastructure is available during runtime request processing
--- through the Handler monad. There aren't very many standalone functions to
--- read about here, but this is deceptive. The key is in the type class
--- instances. Handler is an instance of 'MonadSnap', which means it is the
--- monad you will use to write all your application routes. It also has a
--- 'MonadSnaplet' instance, which gives you all the functionality described
--- above.
-
{-
View
2 src/Snap/Snaplet/Auth/Types.hs
@@ -69,7 +69,7 @@ newtype UserId = UserId { unUid :: Text }
deriving (Read,Show,Ord,Eq,FromJSON,ToJSON,Hashable)
--- | This will be replaced by Greg's role-based permission system.
+-- | This will be replaced by a role-based permission system.
data Role = Role ByteString
deriving (Read,Show,Ord,Eq)
View
3 src/Snap/Snaplet/Internal/Initializer.hs
@@ -2,7 +2,7 @@
{-# LANGUAGE BangPatterns #-}
module Snap.Snaplet.Internal.Initializer
-( addPostInitHook
+ ( addPostInitHook
, addPostInitHookBase
, toSnapletHook
, bracketInit
@@ -100,6 +100,7 @@ addPostInitHook' h = do
------------------------------------------------------------------------------
+-- | Variant of addPostInitHook for when you have things wrapped in a Snaplet.
addPostInitHookBase :: (Snaplet b -> IO (Snaplet b))
-> Initializer b v ()
addPostInitHookBase = Initializer . lift . tell . Hook
View
29 src/Snap/Snaplet/Internal/Types.hs
@@ -151,34 +151,52 @@ class MonadSnaplet m where
-- because Initializer has SnapletConfig, but doesn't have a full Snaplet.
+------------------------------------------------------------------------------
-- | Gets a list of the names of snaplets that are direct ancestors of the
-- current snaplet.
getSnapletAncestry :: (Monad (m b v), MonadSnaplet m) => m b v [Text]
getSnapletAncestry = return . _scAncestry =<< getOpaqueConfig
+
+------------------------------------------------------------------------------
-- | Gets the snaplet's path on the filesystem.
getSnapletFilePath :: (Monad (m b v), MonadSnaplet m) => m b v FilePath
getSnapletFilePath = return . _scFilePath =<< getOpaqueConfig
+
+------------------------------------------------------------------------------
-- | Gets the current snaple's name.
getSnapletName :: (Monad (m b v), MonadSnaplet m) => m b v (Maybe Text)
getSnapletName = return . _scId =<< getOpaqueConfig
+
+------------------------------------------------------------------------------
-- | Gets a human readable description of the snaplet.
getSnapletDescription :: (Monad (m b v), MonadSnaplet m) => m b v Text
getSnapletDescription = return . _scDescription =<< getOpaqueConfig
+
+------------------------------------------------------------------------------
-- | Gets the config data structure for the current snaplet.
getSnapletUserConfig :: (Monad (m b v), MonadSnaplet m) => m b v Config
getSnapletUserConfig = return . _scUserConfig =<< getOpaqueConfig
+
+------------------------------------------------------------------------------
-- | Gets the base URL for the current snaplet. Directories get added to
-- the current snaplet path by calls to 'nestSnaplet'.
getSnapletRootURL :: (Monad (m b v), MonadSnaplet m) => m b v ByteString
getSnapletRootURL = liftM getRootURL getOpaqueConfig
------------------------------------------------------------------------------
+-- | Snaplet infrastructure is available during runtime request processing
+-- through the Handler monad. There aren't very many standalone functions to
+-- read about here, but this is deceptive. The key is in the type class
+-- instances. Handler is an instance of 'MonadSnap', which means it is the
+-- monad you will use to write all your application routes. It also has a
+-- 'MonadSnaplet' instance, which gives you all the functionality described
+-- above.
newtype Handler b v a =
Handler (L.Lensed (Snaplet b) (Snaplet v) Snap a)
deriving ( Monad
@@ -191,26 +209,37 @@ newtype Handler b v a =
, MonadSnap)
+------------------------------------------------------------------------------
+-- | Gets the @Snaplet v@ from the current snaplet's state.
getSnapletState :: Handler b v (Snaplet v)
getSnapletState = Handler get
+------------------------------------------------------------------------------
+-- | Puts a new @Snaplet v@ in the current snaplet's state.
putSnapletState :: Snaplet v -> Handler b v ()
putSnapletState = Handler . put
+------------------------------------------------------------------------------
+-- | Modifies the @Snaplet v@ in the current snaplet's state.
modifySnapletState :: (Snaplet v -> Snaplet v) -> Handler b v ()
modifySnapletState f = do
s <- getSnapletState
putSnapletState (f s)
+------------------------------------------------------------------------------
+-- | Gets the @Snaplet v@ from the current snaplet's state and applies a
+-- function to it.
getsSnapletState :: (Snaplet v -> b) -> Handler b1 v b
getsSnapletState f = do
s <- getSnapletState
return (f s)
+------------------------------------------------------------------------------
+-- | The MonadState instance gives you access to the current snaplet's state.
instance MonadState v (Handler b v) where
get = getsSnapletState _snapletValue
put v = modifySnapletState (setL snapletValue v)

0 comments on commit 0908e39

Please sign in to comment.
Something went wrong with that request. Please try again.