Add documentation comments

src/Halogen/Store/Connect.purs

@@ -15,6 +15,8 @@ import Halogen.Store.Select (Selector(..))
 import Type.Proxy (Proxy(..))
 import Unsafe.Reference (unsafeRefEq)
 
+-- | The input type for connected components, containing the selected context
+-- | from the store and the component's ordinary Halogen input.
 type Connected context input =
   { context :: context
   , input :: input
@@ -26,6 +28,9 @@ data Action context input output
   | Update context
   | Raise output
 
+-- | Connect a component to part of the store using a `Selector`. The selected
+-- | state will be provided as part of the component's input. Any time the
+-- | selected state changes the component will be notified with new input.
 connect
   :: forall action store context query input output m
    . MonadEffect m
@@ -85,6 +90,9 @@ connect (Selector selector) component =
     Raise output ->
       H.raise output
 
+-- | Subscribe to changes in the selected state by providing an action to run
+-- | any time the state updates. This can be used to connect components to the
+-- | store with more manual control than `connect` provides.
 subscribe
   :: forall storeAction store context state action slots output m
    . MonadStore storeAction store m

src/Halogen/Store/Monad.purs

@@ -18,6 +18,12 @@ import Halogen.Subscription (Emitter, Listener, makeEmitter)
 import Halogen.Subscription as HS
 import Unsafe.Coerce (unsafeCoerce)
 
+-- | The `MonadStore` class captures monads which implement a stored value,
+-- | along with methods to get, update (via an action type, `a`), or subscribe
+-- | to changes in the stored value.
+-- |
+-- | An instance is provided for `StoreT`, which is the standard way to use
+-- | the `MonadStore` class.
 class MonadEffect m <= MonadStore a s m | m -> s a where
   getStore :: m s
   updateStore :: a -> m Unit
@@ -30,6 +36,11 @@ type HalogenStore a s =
   , reducer :: s -> a -> s
   }
 
+-- | The `StoreT` monad transformer is the standard way to use the `MonadStore`
+-- | class. It extends the base monad with a global action `a` used to update
+-- | a global state `s`.
+-- |
+-- | The `MonadStore` type class describes the operations supported by this monad.
 newtype StoreT :: Type -> Type -> (Type -> Type) -> Type -> Type
 newtype StoreT a s m b = StoreT (ReaderT (HalogenStore a s) m b)
 
@@ -87,6 +98,21 @@ instance monadStoreHalogenM :: MonadStore a s m => MonadStore a s (HalogenM st a
   updateStore = lift <<< updateStore
   emitSelected = lift <<< emitSelected
 
+-- | Run a component in the `StoreT` monad.
+-- |
+-- | Requires an initial value for the store, `s`, and a reducer that updates
+-- | the store in response to an action, `a`.
+-- |
+-- | This can be used directly on the root component of your application to
+-- | produce a component that Halogen can run, so long as the base monad can
+-- | be fixed to `Aff`.
+-- |
+-- | ```purs
+-- | main = launchAff_ do
+-- |   body <- Halogen.Aff.awaitBody
+-- |   root <- runStoreT initialStore reducer rootComponent
+-- |   runUI root unit body
+-- | ```
 runStoreT
   :: forall a s q i o m
    . Monad m

src/Halogen/Store/Select.purs

@@ -2,13 +2,28 @@ module Halogen.Store.Select where
 
 import Prelude
 
+-- | A `Selector` represents a selection `a` from the store `store`. It is
+-- | commonly used with the `connect` and `subscribe` functions when connecting
+-- | a component to the store.
+-- |
+-- | A selector requires both a selection function from `store -> a` and an
+-- | equality function for `a`. The equality function is used to make sure
+-- | connected components are only notified when the selected state `a` has
+-- | changed.
 newtype Selector store a = Selector { eq :: a -> a -> Boolean, select :: store -> a }
 
+-- | Create a `Selector` from an equality function and a function to select a
+-- | sub-part of the store. The equality function will be used to determine if
+-- | the selected state has changed.
 select :: forall store a. (a -> a -> Boolean) -> (store -> a) -> Selector store a
 select eq = Selector <<< { eq, select: _ }
 
+-- | Create a `Selector` from a function to select a sub-part of the store. The
+-- | selector will use the `Eq` class to determine if the selected state has
+-- | changed.
 selectEq :: forall store a. Eq a => (store -> a) -> Selector store a
 selectEq = Selector <<< { eq, select: _ }
 
+-- | Create a `Selector` for the entire store.
 selectAll :: forall store. Selector store store
 selectAll = Selector { eq: \_ _ -> false, select: identity }