Some more documentation.

3 files changed, 14 insertions, 3 deletions

diff --git a/src/Text/Hakyll/Internal/Cache.hs b/src/Text/Hakyll/Internal/Cache.hs
index 9b9fab1..d28f849 100644
--- a/src/Text/Hakyll/Internal/Cache.hs
+++ b/src/Text/Hakyll/Internal/Cache.hs
@@ -8,12 +8,18 @@ import Text.Hakyll.Hakyll (Hakyll)
 import Text.Hakyll.File
 import Data.Binary
 
+-- | We can store all datatypes instantiating @Binary@ to the cache. The cache
+--   directory is specified by the @HakyllConfiguration@, usually @_cache@.
 storeInCache :: (Binary a) => a -> FilePath -> Hakyll ()
 storeInCache value path = do
     cachePath <- toCache path
     makeDirectories cachePath
     liftIO $ encodeFile cachePath value
 
+-- | Get a value from the cache. The filepath given should not be located in the
+--   cache. This function performs a timestamp check on the filepath and the
+--   filepath in the cache, and only returns the cached value when it is still
+--   up-to-date.
 getFromCache :: (Binary a) => FilePath -> Hakyll (Maybe a)
 getFromCache path = do
     cachePath <- toCache path
diff --git a/src/Text/Hakyll/Page.hs b/src/Text/Hakyll/Page.hs
index 7b40ada..6ead0ae 100644
--- a/src/Text/Hakyll/Page.hs
+++ b/src/Text/Hakyll/Page.hs
@@ -136,7 +136,8 @@ readPageFromFile path = do
   where
     url = toURL path
 
--- | Read a page. Might fetch it from the cache if available.
+-- | Read a page. Might fetch it from the cache if available. Otherwise, it will
+--   read it from the file given and store it in the cache.
 readPage :: FilePath -> Hakyll Page
 readPage path = do
     cacheResult <- getFromCache path
diff --git a/src/Text/Hakyll/Renderables.hs b/src/Text/Hakyll/Renderables.hs
index 9e62a91..c7183a8 100644
--- a/src/Text/Hakyll/Renderables.hs
+++ b/src/Text/Hakyll/Renderables.hs
@@ -64,10 +64,14 @@ data CombinedRenderable a b = CombinedRenderable a b
 -- | Combine two renderables. The url will always be taken from the first
 --   "Renderable". Also, if a `$key` is present in both renderables, the
 --   value from the first "Renderable" will be taken as well.
+--
+--   Since renderables are always more or less key-value maps, you can see
+--   this as a @union@ between two maps.
 combine :: (Renderable a, Renderable b) => a -> b -> CombinedRenderable a b
 combine = CombinedRenderable
 
--- | Combine two renderables and set a custom URL.
+-- | Combine two renderables and set a custom URL. This behaves like "combine",
+--   except that for the @url@ field, the given URL is always chosen.
 combineWithURL :: (Renderable a, Renderable b)
                => FilePath
                -> a
@@ -75,7 +79,7 @@ combineWithURL :: (Renderable a, Renderable b)
                -> CombinedRenderable a b
 combineWithURL = CombinedRenderableWithURL
 
--- | Render combinations.
+-- Render combinations.
 instance (Renderable a, Renderable b)
          => Renderable (CombinedRenderable a b) where