From 89d6cb26bb946c4b186f05f24c819fb5568431e3 Mon Sep 17 00:00:00 2001
From: Jasper Van der Jeugt <jaspervdj@gmail.com>
Date: Sat, 6 Mar 2010 18:11:06 +0100
Subject: Documentation++, added copyValue function.

---
 data/templates/rss.xml          |  2 +-
 src/Text/Hakyll/Context.hs      | 11 +++++++++--
 src/Text/Hakyll/RenderAction.hs |  1 +
 src/Text/Hakyll/Rss.hs          | 31 +++++++++++++++++++++----------
 4 files changed, 32 insertions(+), 13 deletions(-)

diff --git a/data/templates/rss.xml b/data/templates/rss.xml
index 62fcc07..3a58d08 100644
--- a/data/templates/rss.xml
+++ b/data/templates/rss.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" ?>
+<?xml version="1.0" encoding="utf8"?>
 <rss version="2.0">
     <channel>
         <title>$title</title>
diff --git a/src/Text/Hakyll/Context.hs b/src/Text/Hakyll/Context.hs
index 892d5f7..3058946 100644
--- a/src/Text/Hakyll/Context.hs
+++ b/src/Text/Hakyll/Context.hs
@@ -4,6 +4,7 @@ module Text.Hakyll.Context
     , ContextManipulation
     , renderValue
     , changeValue
+    , copyValue
     , renderDate
     , changeExtension
     ) where
@@ -31,9 +32,9 @@ renderValue :: String             -- ^ Key of which the value should be copied.
             -> String             -- ^ Key the value should be copied to.
             -> (String -> String) -- ^ Function to apply on the value.
             -> ContextManipulation
-renderValue src dst f context = case M.lookup src context of
+renderValue source destination f context = case M.lookup source context of
     Nothing      -> context
-    (Just value) -> M.insert dst (f value) context
+    (Just value) -> M.insert destination (f value) context
 
 -- | Change a value in a @Context@.
 --
@@ -46,6 +47,12 @@ changeValue :: String             -- ^ Key to change.
             -> ContextManipulation
 changeValue key = renderValue key key
 
+-- | Copy a value from one key to another in a @Context@.
+copyValue :: String -- ^ Source key.
+          -> String -- ^ Destination key.
+          -> ContextManipulation
+copyValue source destination = renderValue source destination id
+
 -- | When the context has a key called @path@ in a @yyyy-mm-dd-title.extension@
 --   format (default for pages), this function can render the date.
 --
diff --git a/src/Text/Hakyll/RenderAction.hs b/src/Text/Hakyll/RenderAction.hs
index 62ac713..cec1a9f 100644
--- a/src/Text/Hakyll/RenderAction.hs
+++ b/src/Text/Hakyll/RenderAction.hs
@@ -1,3 +1,4 @@
+-- | This is the module which exports @RenderAction@.
 module Text.Hakyll.RenderAction
     ( RenderAction (..)
     , createRenderAction
diff --git a/src/Text/Hakyll/Rss.hs b/src/Text/Hakyll/Rss.hs
index d3e5be2..025851b 100644
--- a/src/Text/Hakyll/Rss.hs
+++ b/src/Text/Hakyll/Rss.hs
@@ -1,4 +1,6 @@
--- | A Module that allows easy rendering of RSS feeds.
+-- | A Module that allows easy rendering of RSS feeds. If you use this module,
+--   you must make sure you set the `absoluteUrl` field in the main Hakyll
+--   configuration.
 module Text.Hakyll.Rss
     ( RssConfiguration (..)
     , renderRss
@@ -16,6 +18,7 @@ import Text.Hakyll.RenderAction (Renderable)
 
 import Paths_hakyll
 
+-- | This is a data structure to keep the configuration of an RSS feed.
 data RssConfiguration = RssConfiguration
     { -- | Url of the RSS feed (relative to site root). For example, @rss.xml@.
       rssUrl         :: String
@@ -25,11 +28,13 @@ data RssConfiguration = RssConfiguration
       rssDescription :: String
     }
 
-createRssWith :: ContextManipulation
-              -> RssConfiguration
-              -> [Renderable]
-              -> FilePath
-              -> FilePath
+-- | This is an auxiliary function to create a listing that is, in fact, an RSS
+--   feed.
+createRssWith :: ContextManipulation -- ^ Manipulation to apply on the items.
+              -> RssConfiguration    -- ^ Feed configuration.
+              -> [Renderable]        -- ^ Items to include.
+              -> FilePath            -- ^ RSS feed template.
+              -> FilePath            -- ^ RSS item template.
               -> Renderable
 createRssWith manipulation configuration renderables template itemTemplate =
     listing >>> render template
@@ -42,12 +47,18 @@ createRssWith manipulation configuration renderables template itemTemplate =
         , ("description", rssDescription)
         ]
 
-renderRss :: RssConfiguration -> [Renderable] -> Hakyll ()
+-- | Render an RSS feed with a number of items.
+renderRss :: RssConfiguration -- ^ Feed configuration.
+          -> [Renderable]     -- ^ Items to include in the feed.
+          -> Hakyll ()
 renderRss = renderRssWith id
 
-renderRssWith :: ContextManipulation
-              -> RssConfiguration
-              -> [Renderable]
+-- | Render an RSS feed with a number of items. This function allows you to
+--   specify a @ContextManipulation@ which will be applied on every
+--   @Renderable@.
+renderRssWith :: ContextManipulation -- ^ Manipulation to apply on the items.
+              -> RssConfiguration    -- ^ Feed configuration.
+              -> [Renderable]        -- ^ Items to include in the feed.
               -> Hakyll ()
 renderRssWith manipulation configuration renderables = do
     template <- liftIO $ getDataFileName "templates/rss.xml"
-- 
cgit v1.2.3