Improved haddoc documentation

Let 'Queue' be exported as top implementation.  Add a note on 'Cat'
performance.

src/Control/Category/Free.hs

@@ -26,13 +26,8 @@
 #endif
 
 module Control.Category.Free
-    ( -- * Optimised version of free category
-      Cat (Id)
-    , arrCat
-    , foldCat
-
-      -- * Real time Queue
-    , Queue (ConsQ, NilQ)
+    ( -- * Real time Queue
+      Queue (ConsQ, NilQ)
     , consQ
     , snocQ
     , unconsQ
@@ -40,6 +35,11 @@ module Control.Category.Free
     , foldrQ
     , foldlQ
 
+      -- * Free Category based on Queue
+    , Cat (Id)
+    , arrCat
+    , foldCat
+
       -- * Free category (CPS style)
     , C (..)
     , toC
@@ -83,12 +83,9 @@ import           Control.Category.Free.Internal
 import           Unsafe.Coerce (unsafeCoerce)
 
 
---
--- Free categories based on real time queues; Ideas after E.Kmett's guanxi
--- project.
---
-
--- | Optimised version of a free category.
+-- | A version of a free category based on realtime queues.  This is an
+-- optimised version (for right associations) of E.Kemett's free category from
+-- 'guanxi' project.
 --
 -- @('.')@ has @O\(1\)@ complexity, folding is @O\(n\)@ where @n@ is the number
 -- of transitions.
@@ -121,6 +118,11 @@ import           Unsafe.Coerce (unsafeCoerce)
 -- Type aligned 'Queue's have efficient 'snocQ' and 'unconsQ' operations which
 -- allow to implement efficient composition and folding for 'Cat'.
 --
+-- /Performence/: it does not perform as reliably as 'Queue', which are not
+-- frigile to left right associations, and it is also more frigile to @-O@
+-- flags (behaves purly without any optimisations, e.g. @-O0@; and in some
+-- cases performence degrades with @-O2@ flag).
+--
 data Cat (f :: k -> k -> *) a b where
     Id  :: Cat f a a
     Cat :: Queue (Cat (Op f)) c b

src/Control/Category/Free/Internal.hs

@@ -179,8 +179,8 @@ instance ArrowChoice f => ArrowChoice (ListTr f) where
 --
 -- Upper bounds of `consQ`, `snocQ`, `unconsQ` are @O\(1\)@ (worst case).
 --
--- Invariant: sum of lengths of two last least is equal the length of the first
--- one.
+-- Internal invariant: sum of lengths of two last least is equal the length of
+-- the first one.
 --
 data Queue (f :: k -> k -> *) (a :: k) (b :: k) where
     Queue :: forall f a c b x.