Merge pull request #1 from satnam6502/satnam6502

Add documentation for fork and loop

src/Lava.hs

@@ -6,7 +6,7 @@
 -- Stability:   experimental
 -- Portability: portable
 --
--- A DSL for digital hardware design in Haskell.
+-- The Lava module provides a DSL for digital hardware design.
 --
 
 module Lava (module Lava.Combinators,

src/Lava/Combinators.hs

@@ -7,10 +7,15 @@ where
 import Control.Monad.Fix (MonadFix)
 import Control.Monad ((>=>)) 
 
--- | Fork captures sharing.
+-- | Fork captures sharing. The input wire `a` is split
+--   into two wires, each containing the value of `a`.
 fork :: Monad m => a -> m (a, a)
 fork a = return (a, a)
 
+-- | Loop is used to bend a wire `feedback` from the output of a circuit
+--   and feed it back as in input to a circuit. This requires
+--   the feedback path to contain at least one state (delay)
+--   element, otherwise the output will not terminate.
 loop :: MonadFix m => ((a, feedback) -> m (b, feedback)) ->
                       a -> m b
 loop circuit a