State machine constructors documentation

README.md

@@ -138,3 +138,11 @@ Contributions are extremely welcome. If you have any idea on how to improve the
 ## Logo
 
 The `crem` logo was kindly generated by [craiyon](https://www.craiyon.com/).
+
+## Resources
+
+If you want to know a bit more of `crem` and some ideas behind it, here are some additional resources you can check out:
+
+- [Domain modelling with state machines](http://marcosh.github.io/post/2021/10/27/ddd-state-machines.html), the first blog post where I started considering using composable state machines for DDD-like architectures.
+- [Composable Haskell state machines with `crem`](https://www.youtube.com/watch?v=cvbOG1I6wrU), if you prefer a video introducing `crem`.
+- [State machines with `crem`](https://hackmd.io/@CJO5VbycTsyzjGBytbwezQ/rkJliIjRj#/) the slide deck used for the above presentation.

src/Crem/Render/RenderableVertices.hs

@@ -18,9 +18,9 @@ import "base" Data.Void (Void)
 class RenderableVertices a where
   vertices :: [a]
 
--- | This is a newtype to be used with `deriving via`. If `a` has instances for
+-- | This is a newtype to be used with `deriving via`. If @a@ has instances for
 -- `Enum` and `Bounded`, then `AllVertices a` has an instance of
--- `RenderableVertices` which lists all the terms of type `a`.
+-- `RenderableVertices` which lists all the terms of type @a@.
 newtype AllVertices a = AllVertices a
 
 instance (Enum a, Bounded a) => RenderableVertices (AllVertices a) where

src/Crem/StateMachine.hs

@@ -26,7 +26,12 @@ import Prelude hiding ((.))
 --
 -- `StateMachineT` is a tree, where leaves are `BaseMachineT` and other nodes
 -- describe how to combine the subtrees to obtain more complex machines.
+--
+-- Please refer to https://github.com/tweag/crem/blob/main/docs/how-to-create-a-machine.md
+-- for a more complete discussion on the various constructors.
 data StateMachineT m input output where
+  -- | `Basic` allows to interpret a `BaseMachineT` as a `StateMachineT`,
+  -- making the @topology@ type variable existential
   Basic
     :: forall m vertex (topology :: Topology vertex) input output
      . ( Demote vertex ~ vertex
@@ -38,23 +43,31 @@ data StateMachineT m input output where
        )
     => BaseMachineT m topology input output
     -> StateMachineT m input output
+  -- | `Sequential` adds categorical composition for `StateMachineT`
   Sequential
     :: StateMachineT m a b
     -> StateMachineT m b c
     -> StateMachineT m a c
+  -- | `Parallel` allows to process two machine simultaneously
   Parallel
     :: StateMachineT m a b
     -> StateMachineT m c d
     -> StateMachineT m (a, c) (b, d)
+  -- | `Alternative` allows to process one out of two machines depending on the
+  -- input
   Alternative
     :: StateMachineT m a b
     -> StateMachineT m c d
     -> StateMachineT m (Either a c) (Either b d)
+  -- | `Feedback` allows to compose two machine going in oppositive directions
+  -- and run them in a loop
   Feedback
     :: (Foldable n, Monoid (n a), Monoid (n b))
     => StateMachineT m a (n b)
     -> StateMachineT m b (n a)
     -> StateMachineT m a (n b)
+  -- | `Kleisli` allows to compose sequentially machines which emit multiple
+  -- outputs
   Kleisli
     :: (Foldable n, Monoid (n c))
     => StateMachineT m a (n b)