Write more API documentation.

examples/doc_githubWhiteIcon.hs

@@ -0,0 +1,12 @@
+#!/usr/bin/env stack
+-- stack runghc --package reanimate
+module Main (main) where
+
+import           Reanimate
+import           Reanimate.Builtin.Documentation
+import           Reanimate.Builtin.Images
+
+main :: IO ()
+main = reanimate $ staticFrame 1 $ mkGroup
+  [ mkBackground "grey"
+  , githubWhiteIcon ]

examples/doc_ternaryPlot.hs

@@ -2,13 +2,15 @@
 -- stack runghc --package reanimate
 module Main(main) where
 
-import Reanimate hiding (raster)
+import           Codec.Picture.Types
-import Reanimate.Builtin.Documentation
+import           Reanimate
-import Reanimate.Builtin.TernaryPlot
+import           Reanimate.Builtin.Documentation
-import Reanimate.ColorComponents
+import           Reanimate.Builtin.TernaryPlot
-import Data.Colour.CIE
-import Codec.Picture.Types
 
 main :: IO ()
-main = reanimate $ docEnv $ animate $ const $
+main = reanimate $ docEnv $ staticFrame 1 $
-  ternaryPlot 1024 (\a b c -> promotePixel $ toRGB8 $ cieXYZ a b c)
+  ternaryPlot 100 $ \aCoord bCoord cCoord -> promotePixel $
+    let red   = round $ aCoord*255
+        green = round $ bCoord*255
+        blue  = round $ cCoord*255
+    in PixelRGB8 red green blue

src/Reanimate/Builtin/Images.hs

@@ -1,3 +1,14 @@
+{-|
+Module      : Reanimate.Builtin.Images
+Copyright   : Written by David Himmelstrup
+License     : Unlicense
+Maintainer  : lemmih@gmail.com
+Stability   : experimental
+Portability : POSIX
+
+Collection of built-in images.
+
+-}
 module Reanimate.Builtin.Images
   ( svgLogo
   , haskellLogo
@@ -46,6 +57,7 @@ githubIcon :: SVG
 githubIcon = unsafePerformIO $ embedImage "data/github-icon.svg"
 
 {-# NOINLINE githubWhiteIcon #-}
+-- | <<docs/gifs/doc_githubWhiteIcon.gif>>
 githubWhiteIcon :: SVG
 githubWhiteIcon = unsafePerformIO $ embedImage "data/github-icon-white.svg"
 

src/Reanimate/Builtin/TernaryPlot.hs

@@ -1,19 +1,56 @@
-module Reanimate.Builtin.TernaryPlot where
+{-|
+Module      : Reanimate.Builtin.TernaryPlot
+Copyright   : Written by David Himmelstrup
+License     : Unlicense
+Maintainer  : lemmih@gmail.com
+Stability   : experimental
+Portability : POSIX
+
+Implementation of ternary plots: <https://en.wikipedia.org/wiki/Ternary_plot>
+
+-}
+module Reanimate.Builtin.TernaryPlot
+  ( ACoord
+  , BCoord
+  , CCoord
+  , ternaryPlot
+  -- , atCenter
+  -- , radius
+  , toCartesianCoords
+  , toOffsetCartesianCoords
+  , fromCartesianCoords
+  ) where
 
 import           Codec.Picture
 import           Graphics.SvgTree (Tree)
 import           Reanimate.Raster
 import           Reanimate.Svg
 
--- (top, left, right)
 -- a+b+c=1
+-- | Left-most coordinate.
 type ACoord = Double
+-- | Top-most coordinate.
 type BCoord = Double
+-- | Right-most coordinate.
 type CCoord = Double
 
--- Creates a centered ternary plot with a width of 5.
+-- | Creates a centered ternary plot with a width of 5.
-ternaryPlot :: Int -- ^ Pixels in the X-axis.
+--
-            -> (ACoord -> BCoord -> CCoord -> PixelRGBA8) -> Tree
+--   Example:
+--
+--   > ternaryPlot 100 $ \aCoord bCoord cCoord -> promotePixel $
+--   >   let red   = round $ aCoord*255
+--   >       green = round $ bCoord*255
+--   >       blue  = round $ cCoord*255
+--   >   in PixelRGB8 red green blue
+--
+--   <<docs/gifs/doc_ternaryPlot.gif>>
+ternaryPlot :: Int -- ^ Pixels in the X-axis. More pixels => higher quality.
+            -> (ACoord -> BCoord -> CCoord -> PixelRGBA8)
+            -- ^ a+b+c=1. A=1 is the left-most position,
+            --   B=1 is the top-most position, and
+            --   C=1 is the right-most position.
+            -> Tree
 ternaryPlot density fn =
     scaleToWidth stdWidth $
     translate (-cX) (-cY) $
@@ -36,22 +73,27 @@ ternaryPlot density fn =
         then PixelRGBA8 0 0 0 0
         else fn aCoord bCoord cCoord
 
-atCenter :: Double -> Tree -> Tree
+-- atCenter :: Double -> Tree -> Tree
-atCenter stdWidth = translate (-cX*stdWidth) (-cY*stdWidth)
+-- atCenter stdWidth = translate (-cX*stdWidth) (-cY*stdWidth)
-  where
+--   where
-    (cX, cY) = toCartesianCoords (1/3) (1/3)
+--     (cX, cY) = toCartesianCoords (1/3) (1/3)
 
-radius :: Double
+-- radius :: Double
-radius = sqrt (cX*cX + cY*cY)
+-- radius = sqrt (cX*cX + cY*cY)
-  where
+--   where
-    (cX, cY) = toCartesianCoords (1/3) (1/3)
+--     (cX, cY) = toCartesianCoords (1/3) (1/3)
 
+-- | Compute the XY coordinates from ternary coordinates.
+--   Note that @CCoord@ is given because @a+b+c=1@.
 toCartesianCoords :: ACoord -> BCoord -> (Double, Double)
 toCartesianCoords a b = (x, y)
   where
     x = (a+2*b)/2
     y = (sqrt 3 / 2) * a
 
+-- | Compute the XY coordinates relative from the center of the
+--   ternary plot.
+--   Note that @CCoord@ is given because @a+b+c=1@.
 toOffsetCartesianCoords :: ACoord -> BCoord -> (Double, Double)
 toOffsetCartesianCoords a b =
     (tx-zx, ty-zy)
@@ -59,6 +101,7 @@ toOffsetCartesianCoords a b =
     (zx,zy) = toCartesianCoords (1/3) (1/3)
     (tx,ty) = toCartesianCoords a b
 
+-- | Compute ternary coordinates from XY coordinates.
 fromCartesianCoords :: Double -> Double -> (ACoord, BCoord, CCoord)
 fromCartesianCoords x y = (a,b,1-a-b)
   where