Add some comments. Update README. (#8)

Author: natefaubion

README.md

@@ -4,8 +4,8 @@ An extensible virtual-dom library for PureScript.
 
 ## Overview
 
-`Halogen.VDom` is a "batteries not included" virtual-dom library for PureScript
-with inspiration drawn from:
+`Halogen.VDom` is a bare-bones virtual-dom library for PureScript with
+inspiration drawn from:
 
 * https://github.com/Matt-Esch/virtual-dom
 * https://github.com/paldepind/snabbdom
@@ -17,9 +17,10 @@ It's goals being:
 2. To be as fast as possible given (1).
 3. To be extensible.
 
-Notably, `Halogen.VDom` is largely useless out of the box. It does not support
-attributes, properties, or event listeners. It is intended to be extended
-(and likely `newtype`d) by other frameworks to suit their needs.
+Notably, `Halogen.VDom` is largely useless out of the box. You'll need to bring
+your own attributes, properties, and event listeners (though there is a working
+implementation included). It is intended to be extended (and likely
+`newtype`d) by other frameworks to suit their needs.
 
 ---
 

src/Halogen/VDom/DOM.purs

@@ -30,6 +30,8 @@ type VDomMachine eff a b = Machine (Eff eff) a b
 
 type VDomStep eff a b = Eff eff (Step (Eff eff) a b)
 
+-- | Widget machines recursively reference the configured spec to potentially
+-- | enable recursive trees of Widgets.
 newtype VDomSpec eff a w = VDomSpec
   { buildWidget ∷ VDomSpec eff a w → VDomMachine eff w DOM.Node
   , buildAttributes ∷ DOM.Element → VDomMachine eff a Unit
@@ -38,6 +40,15 @@ newtype VDomSpec eff a w = VDomSpec
 
 type VDomEffects eff = (dom ∷ DOM | eff)
 
+-- | Starts an initial `VDom` machine by providing a `VDomSpec`.
+-- |
+-- | ```purescript
+-- | main = do
+-- |   machine1 ← buildVDom spec vdomTree1
+-- |   machine2 ← Machine.step machine1 vdomTree2
+-- |   machine3 ← Machine.step machine2 vdomTree3
+-- |   ...
+-- | ````
 buildVDom
   ∷ ∀ eff a w
   . VDomSpec (VDomEffects eff) a w

src/Halogen/VDom/DOM/Prop.purs

@@ -27,6 +27,8 @@ import Halogen.VDom.Types (Namespace(..))
 import Halogen.VDom.Util as Util
 import Unsafe.Coerce (unsafeCoerce)
 
+-- | Attributes, properties, event handlers, and element lifecycles.
+-- | Parameterized by the type of handlers outputs.
 data Prop a
   = Attribute (Maybe Namespace) String String
   | Property String PropValue
@@ -60,6 +62,9 @@ propFromInt = unsafeCoerce
 propFromNumber ∷ Number → PropValue
 propFromNumber = unsafeCoerce
 
+-- | A `Machine`` for applying attributes, properties, and event handlers.
+-- | An emitter effect must be provided to respond to events. For example,
+-- | to allow arbitrary effects in event handlers, one could use `id`.
 buildProp
   ∷ ∀ eff a
   . (a → Eff (ref ∷ REF, dom ∷ DOM | eff) Unit)

src/Halogen/VDom/Machine.purs

@@ -21,12 +21,15 @@ data Step m a b = Step b (Machine m a b) (m Unit)
 instance functorStep ∷ Functor m ⇒ Functor (Step m a) where
   map f (Step x m d) = Step (f x) (m >>> map (map f)) d
 
+-- | Returns the output value of a `Step`.
 extract ∷ ∀ m a b. Step m a b → b
 extract (Step x _ _) = x
 
+-- | Runs the next step.
 step ∷ ∀ m a b. Step m a b → a → m (Step m a b)
 step (Step _ m _) = m
 
+-- | Runs the finalizer associated with a `Step`
 halt ∷ ∀ m a b. Step m a b → m Unit
 halt (Step _ _ h) = h
 

src/Halogen/VDom/Types.purs

@@ -18,6 +18,12 @@ import Data.Newtype (class Newtype)
 import Data.Tuple (Tuple)
 import Unsafe.Coerce (unsafeCoerce)
 
+-- | The core virtual-dom tree type, where `a` is the type of attributes,
+-- | and `w` is the type of "widgets". Widgets are machines that have complete
+-- | control over the lifecycle of some `DOM.Node`.
+-- |
+-- | The `Grafted` constructor and associated machinery enables `bimap`
+-- | fusion using a Coyoneda-like encoding.
 data VDom a w
   = Text String
   | Elem (ElemSpec a) (Array (VDom a w))