Type-safe identifiers in haddocks

3 files changed, 15 insertions, 8 deletions

diff --git a/src/Hakyll/Core/Compiler.hs b/src/Hakyll/Core/Compiler.hs
index 2eb219c..909f945 100644
--- a/src/Hakyll/Core/Compiler.hs
+++ b/src/Hakyll/Core/Compiler.hs
@@ -53,7 +53,7 @@
 -- This illustration can help us understand the type signature of 'require'.
 --
 -- > require :: (Binary a, Typeable a, Writable a)
--- >         => Identifier
+-- >         => Identifier a
 -- >         -> (b -> a -> c)
 -- >         -> Compiler b c
 --
@@ -64,7 +64,7 @@
 -- These are constraints for the @a@ type. @a@ (the template) needs to have
 -- certain properties for it to be required.
 --
--- > Identifier
+-- > Identifier a
 --
 -- This is simply @templates/fancy.html@: the 'Identifier' of the item we want
 -- to 'require', in other words, the name of the item we want to add to the
diff --git a/src/Hakyll/Core/Identifier.hs b/src/Hakyll/Core/Identifier.hs
index b413b32..3b67381 100644
--- a/src/Hakyll/Core/Identifier.hs
+++ b/src/Hakyll/Core/Identifier.hs
@@ -20,6 +20,15 @@
 -- @posts/foo.html@. In this case, the identifier is the name of the source
 -- file of the page.
 --
+-- An `Identifier` carries the type of the value it identifies. This basically
+-- means that an @Identifier (Page String)@ refers to a page.
+--
+-- It is a phantom type parameter, meaning you can safely change this if you
+-- know what you are doing. You can change the type using the 'castIdentifier'
+-- function.
+--
+-- If the @a@ type is not known, Hakyll traditionally uses @Identifier ()@.
+--
 {-# LANGUAGE GeneralizedNewtypeDeriving, DeriveDataTypeable #-}
 module Hakyll.Core.Identifier
     ( Identifier (..)
@@ -41,12 +50,6 @@ import Data.Typeable (Typeable)
 
 -- | An identifier used to uniquely identify a value
 --
--- The @a@ is used to denote the type that the identifier points to. It is a
--- phantom type parameter, meaning you can safely change this if you know what
--- you are doing.
---
--- If the @a@ type is not known, Hakyll traditionally uses @Identifier ()@.
---
 data Identifier a = Identifier
     { identifierGroup :: Maybe String
     , identifierPath  :: String
diff --git a/src/Hakyll/Core/Identifier/Pattern.hs b/src/Hakyll/Core/Identifier/Pattern.hs
index 6bbfad8..8263f29 100644
--- a/src/Hakyll/Core/Identifier/Pattern.hs
+++ b/src/Hakyll/Core/Identifier/Pattern.hs
@@ -31,6 +31,10 @@
 -- The 'capture' function allows the user to get access to the elements captured
 -- by the capture elements in the pattern.
 --
+-- Like an 'Identifier', a 'Pattern' also has a type parameter. This is simply
+-- an extra layer of safety, and can be discarded using the 'castPattern'
+-- function.
+--
 module Hakyll.Core.Identifier.Pattern
     ( Pattern
     , castPattern