Updated README and documentation

README.md

@@ -2,3 +2,9 @@
 [![Maintainer: coot](https://img.shields.io/badge/maintainer-coot-lightgrey.svg)](http://github.com/coot)
 [![Travis Build Status](https://travis-ci.org/coot/free-category.svg?branch=master)](https://travis-ci.org/coot/free-category)
 
+This package introduces variouos encodings of free categories in Haskell.
+
+Free categories are useful to model state machines in a simple yet type safe
+way.  Read more [here](https://coot.me/posts/finite-state-machines.html) on
+a simple example of a finite state machine encoded using a free category using
+a simple GADT.

src/Control/Category/Free.hs

@@ -45,6 +45,9 @@ import           Data.Semigroup.SSet (SSet (..))
 --
 -- prop> liftFree2    @Cat :: f a b -> Cat f ab
 -- prop> foldNatFree2 @Cat :: Category d => (forall x y. f x y -> d x y) -> Cat f a b -> d a b
+--
+-- The same performance concerns that apply to @'Control.Monad.Free.Free'@
+-- apply to this encoding of a free category.
 data Cat :: (* -> * -> *) -> * -> * -> * where
   Id :: Cat f a a
   (:.:) :: f b c -> Cat f a b -> Cat f a c
@@ -104,7 +107,8 @@ instance Category (C f) where
   C bc . C ab = C $ \k -> bc k . ab k
 
 -- |
--- Isomorphism between @'Cat'@ to @'C'@, which is a specialisation of @'hoistFreeH2'@.
+-- Isomorphism between @'Cat'@ to @'C'@, which is a specialisation of
+-- @'hoistFreeH2'@.
 toC :: Cat f a b -> C f a b
 toC = hoistFreeH2
 {-# INLINE toC #-}