Restructure and document module

Restructure and add more documentation to the main module of the library.

src/Graphics/Avatars/Pixelated.hs

@@ -1,8 +1,48 @@
+-- |
+-- Module      : Graphics.Avatars.Pixelated
+-- Description : Contains types and functions for generating pixelated avatars.
+-- Copyright   : (c) Christopher Wells, 2016
+-- License     : MIT
+-- Maintainer  : cwellsny@nycap.rr.com
+--
+-- This module provides types and functions for creating and working with
+-- pixelated avatars.
+--
+-- Avatars can be generated by providing a `Seed`. Seeds can be created by
+-- passing a random String into `createSeed`. The given String is then turned
+-- into an MD5 checksum, which is used as the seed value.
+--
+-- Once a Seed has been created, an Avatar can be generated from it by passing
+-- it into `generateAvatar`. The generated Avatar can then be saved to a file
+-- by running `saveAvatar`.
+--
+-- = Example
+-- The following is an example showing how to construct a function which will
+-- generate an avatar from a given seed string, and save it at the given
+-- location.
+--
+-- @
+-- import Graphics.Avatars.Pixelated
+--
+-- createAndSaveAvatar :: String -> FilePath -> IO ()
+-- createAndSaveAvatar s path = saveAvatar avatar path
+--   where avatar = generateAvatar seed
+--         seed   = createSeed s
+-- @
 module Graphics.Avatars.Pixelated
 (
-  Seed(..), Avatar(..), Color(..), AvatarGrid(..), showGrid,
-
-  createSeed, generateAvatar, saveAvatar, colorFromSeed, generateAvatarGrid
+  -- * Types
+  -- ** Seed
+  Seed(..), createSeed,
+
+  -- ** Avatar
+  Avatar(..), generateAvatar, saveAvatar,
+
+  -- ** Color
+  Color(..), colorFromSeed,
+
+  -- ** AvatarGrid
+  AvatarGrid(..), showGrid, generateAvatarGrid
 )
 where
 
@@ -13,56 +53,15 @@ import Data.Digest.Pure.MD5 (md5)
 import Data.List.Split (chunksOf)
 
 -------------------------------------------------------------------------------
--- Types
+-- Seeds
 
 -- | A seed to use in generating an avatar. Can be created from a String by
 -- using the `createSeed` function.
+--
+-- Seeds are expected to be 32 character hexidecimal MD5 checksums.
 newtype Seed = Seed { unSeed :: String }
   deriving (Eq, Show)
 
--- | A generated avatar.
-newtype Avatar = Avatar { unAvatar :: DynamicImage }
-
--- | A color for an avatar.
-data Color = Black | Blue | Green | Grey | Orange | Purple | Red | Yellow
-  deriving (Eq, Show)
-
--- | A grid of boolean values representing an Avatar. True values indicate
--- colored pixels, and False values indicate blank pixels.
-newtype AvatarGrid = AvatarGrid { unAvatarGrid :: [[Bool]] }
-  deriving (Eq)
-
--- | Converts the grid into a String representation.
-instance Show AvatarGrid where
-  show x = (showGrid . unAvatarGrid) x
-
--- | The left half of an AvatarGrid.
-newtype AvatarGridSide = AvatarGridSide { unAvatarGridSide :: [[Bool]] }
-
--- | Converts the grid side into a String representation.
-instance Show AvatarGridSide where
-  show x = (showGrid . unAvatarGridSide) x
-
--- | Converts a grid of boolean values into a String representation.
---
--- >>> putStrLn $ showGrid [[True, False], [False, True]]
--- █ 
---  █
-showGrid :: [[Bool]] -> String
-showGrid g = (init . unlines) $ (map . map) showPixel g
-
--- | Converts a boolean value into a character representation for a pixel.
---
--- >>> showPixel True
--- '\9608'
--- >>> showPixel False
--- ' '
-showPixel :: Bool -> Char
-showPixel p = if p then '█' else ' '
-
--------------------------------------------------------------------------------
--- Seeds
-
 -- | Creates a seed from a given String.
 --
 -- >>> createSeed "Hello"
@@ -73,6 +72,9 @@ createSeed = Seed . show . md5 . packChars
 -------------------------------------------------------------------------------
 -- Avatars
 
+-- | A generated avatar.
+newtype Avatar = Avatar { unAvatar :: DynamicImage }
+
 -- | Generates an avatar from the given seed.
 generateAvatar :: Seed -> Avatar
 generateAvatar seed = undefined
@@ -94,7 +96,11 @@ saveAvatar avatar path = undefined
 -------------------------------------------------------------------------------
 -- Colors
 
--- | Pick an avatar color using the given seed.
+-- | A color for an avatar.
+data Color = Black | Blue | Green | Grey | Orange | Purple | Red | Yellow
+  deriving (Eq, Show)
+
+-- | Picks an avatar color using the given seed.
 --
 -- >>> colorFromSeed $ Seed {unSeed = "8b1a9953c4611296a827abf8c47804d7"}
 -- Orange
@@ -115,6 +121,39 @@ colorFromSeed seed = color avg
 -------------------------------------------------------------------------------
 -- AvatarGrids
 
+-- | A grid of boolean values representing an Avatar. True values indicate
+-- colored pixels, and False values indicate blank pixels.
+newtype AvatarGrid = AvatarGrid { unAvatarGrid :: [[Bool]] }
+  deriving (Eq)
+
+-- | Converts the grid into a String representation.
+instance Show AvatarGrid where
+  show x = (showGrid . unAvatarGrid) x
+
+-- | The left half of an AvatarGrid.
+newtype AvatarGridSide = AvatarGridSide { unAvatarGridSide :: [[Bool]] }
+
+-- | Converts the grid side into a String representation.
+instance Show AvatarGridSide where
+  show x = (showGrid . unAvatarGridSide) x
+
+-- | Converts a grid of boolean values into a String representation.
+--
+-- >>> putStrLn $ showGrid [[True, False], [False, True]]
+-- █ 
+--  █
+showGrid :: [[Bool]] -> String
+showGrid g = (init . unlines) $ (map . map) showPixel g
+
+-- | Converts a boolean value into a character representation for a pixel.
+--
+-- >>> showPixel True
+-- '\9608'
+-- >>> showPixel False
+-- ' '
+showPixel :: Bool -> Char
+showPixel p = if p then '█' else ' '
+
 -- | Generates an AvatarGrid using the given Seed.
 --
 -- It works by generating the left half of the grid using the contents of the