@@ -21,49 +21,50 @@ import Text.Hakyll.Context
2121import Text.Hakyll.File (toDestination, isFileMoreRecent)
2222import Text.Hakyll.Hakyll
2323
24+-- | Type used for rendering computations that carry along dependencies.
2425data RenderAction a b = RenderAction
25− { actionDependencies :: [FilePath]
26− , actionUrl :: Maybe (Hakyll FilePath)
27− , actionFunction :: a -> Hakyll b
26+ { -- | Dependencies of the @RenderAction@.
27+ actionDependencies :: [FilePath]
28+ , -- | URL pointing to the result of this @RenderAction@.
29+ actionUrl :: Maybe (Hakyll FilePath)
30+ , -- | The actual render function.
31+ actionFunction :: a -> Hakyll b
2832 }
2933
30−createRenderAction :: (a -> Hakyll b) -> RenderAction a b
34+-- | Create a @RenderAction@ from a function.
35+createRenderAction :: (a -> Hakyll b) -- ^ Function to execute.
36+ -> RenderAction a b
3137createRenderAction f = id { actionFunction = f }
3238
33−createSimpleRenderAction :: Hakyll b -> RenderAction () b
39+-- | Create a @RenderAction@ from a simple @Hakyll@ value.
40+createSimpleRenderAction :: Hakyll b -- ^ Hakyll value to pass on.
41+ -> RenderAction () b
3442createSimpleRenderAction = createRenderAction . const
3543
36−createFileRenderAction :: FilePath -> Hakyll b -> RenderAction () b
44+-- | Create a @RenderAction@ that operates on one file.
45+createFileRenderAction :: FilePath -- ^ File to operate on.
46+ -> Hakyll b -- ^ Value to pass on.
47+ -> RenderAction () b -- ^ The resulting action.
3748createFileRenderAction path action = RenderAction
3849 { actionDependencies = [path]
3950 , actionUrl = Just $ return path
4051 , actionFunction = const action
4152 }
4253
43−instance Category RenderAction where
44− id = RenderAction
45− { actionDependencies = []
46− , actionUrl = Nothing
47− , actionFunction = return
48− }
49−
50− x . y = RenderAction
51− { actionDependencies = actionDependencies x ++ actionDependencies y
52− , actionUrl = actionUrl y `mplus` actionUrl x
53− , actionFunction = actionFunction x <=< actionFunction y
54− }
55−
56−createManipulationAction :: ContextManipulation -> RenderAction Context Context
54+-- | Create a @RenderAction@ from a @ContextManipulation@.
55+createManipulationAction :: ContextManipulation -- ^ Manipulation to apply.
56+ -> RenderAction Context Context
5757createManipulationAction = createRenderAction . (return .)
5858
59−chain :: [RenderAction a a] -> RenderAction a a
60−chain [] = id
61−chain list@(_:_) = foldl1 (>>>) list
62−
63−runRenderAction :: RenderAction () a -> Hakyll a
59+-- | Run a @RenderAction@ now.
60+runRenderAction :: RenderAction () a -- ^ Render action to run.
61+ -> Hakyll a -- ^ Result of the action.
6462runRenderAction action = actionFunction action ()
6563
66−runRenderActionIfNeeded :: RenderAction () () -> Hakyll ()
64+-- | Run a @RenderAction@, but only when it is out-of-date. At this point, the
65+-- @actionUrl@ field must be set.
66+runRenderActionIfNeeded :: RenderAction () () -- ^ Action to run.
67+ -> Hakyll () -- ^ Empty result.
6768runRenderActionIfNeeded action = do
6869 url <- case actionUrl action of
6970 (Just u) -> u
@@ -73,4 +74,25 @@ runRenderActionIfNeeded action = do
7374 unless valid $ do liftIO $ hPutStrLn stderr $ "Rendering " ++ destination
7475 runRenderAction action
7576
77+-- | Chain a number of @RenderAction@ computations.
78+chain :: [RenderAction a a] -- ^ Actions to chain.
79+ -> RenderAction a a -- ^ Resulting action.
80+chain [] = id
81+chain list@(_:_) = foldl1 (>>>) list
82+
83+-- | This is a specialized version of @RenderAction@, a @Context@ that can be
84+-- rendered.
7685type Renderable = RenderAction () Context
86+
87+instance Category RenderAction where
88+ id = RenderAction
89+ { actionDependencies = []
90+ , actionUrl = Nothing
91+ , actionFunction = return
92+ }
93+
94+ x . y = RenderAction
95+ { actionDependencies = actionDependencies x ++ actionDependencies y
96+ , actionUrl = actionUrl y `mplus` actionUrl x
97+ , actionFunction = actionFunction x <=< actionFunction y
98+ }