Documentation++.

1 files changed, 28 insertions, 7 deletions

diff --git a/src/Text/Hakyll/Tags.hs b/src/Text/Hakyll/Tags.hs
index 4059597..a2031f8 100644
--- a/src/Text/Hakyll/Tags.hs
+++ b/src/Text/Hakyll/Tags.hs
@@ -1,5 +1,19 @@
 -- | Module containing some specialized functions to deal with tags.
 --   This Module follows certain conventions. Stick with them.
+--
+--   More concrete: all functions in this module assume that the tags are
+--   located in the @tags@ field, and separated by commas. An example file
+--   @foo.markdown@ could look like:
+--
+--   > ---
+--   > author: Philip K. Dick
+--   > title: Do androids dream of electric sheep?
+--   > tags: future, science fiction, humanoid
+--   > ---
+--   > The novel is set in a post-apocalyptic near future, where the Earth and
+--   > its populations have been damaged greatly by Nuclear...
+--
+--   All the following functions would work with such a format.
 module Text.Hakyll.Tags
     ( readTagMap
     , renderTagCloud
@@ -12,15 +26,13 @@ import Control.Monad (foldM)
 import Control.Arrow (second)
 
 import Text.Hakyll.Hakyll (Hakyll)
-import Text.Hakyll.Context (ContextManipulation, renderValue)
+import Text.Hakyll.Context (ContextManipulation, changeValue)
 import Text.Hakyll.Render.Internal (finalSubstitute)
 import Text.Hakyll.Regex
 import Text.Hakyll.Util
 import Text.Hakyll.Page
 
--- | Read a tag map. This creates a map from tags to page paths. This function
---   assumes the tags are located in the @tags@ metadata field, separated by
---   commas.
+-- | Read a tag map. This creates a map from tags to page paths.
 readTagMap :: [FilePath] -> Hakyll (M.Map String [FilePath])
 readTagMap paths = foldM addPaths M.empty paths
   where
@@ -59,10 +71,19 @@ renderTagCloud tagMap urlFunction minSize maxSize =
     tagCount :: [(String, Float)]
     tagCount = map (second $ fromIntegral . length) $ M.toList tagMap
 
--- Render all tags to links.
-renderTagLinks :: (String -> String) -- ^ Function that produces an url for a tag.
+-- | Render all tags to links.
+--   
+--   On your side, it is nice if you can display the tags on a page, but
+--   naturally, most people would expect these are clickable.
+--
+--   So, this function takes a function to produce an url for a given tag, and
+--   applies it on all tags.
+--
+--   Note that it is your own responsibility to ensure a page which such an url
+--   exists.
+renderTagLinks :: (String -> String) -- ^ Function to produce an url for a tag.
                -> ContextManipulation
-renderTagLinks urlFunction = renderValue "tags" "tags" renderTagLinks'
+renderTagLinks urlFunction = changeValue "tags" renderTagLinks'
   where
     renderTagLinks' = intercalate ", "
                     . map ((\t -> link t $ urlFunction t) . trim)