@@ -6,9 +6,7 @@ Many Reflex functions operate in monadic context `m a`, where the monad 'm' supp
66
77The function signatures here have been simplified by removing many typeclass constraints and adding simple annotations to each function. Also the ubiquitous 't' type parameter has been removed.
88
9−Functions annotated with "[ ]" are *pure*: They operate on Events, Behaviors, or Dynamics uniformly without regard to the "current time".
10−
11−Other functions must operate in some monadic context, because they produce a result "as of now". The annotations are:
9+Some of these functions are *pure*: They operate on Events, Behaviors, or Dynamics uniformly without regard to the "current time". Other functions must operate in some monadic context, because they produce a result "as of now" (e.g., any function that takes an "initial" value, or returns a "current" value). Annotations are used to distinguish these cases:
1210
1311```haskell
1412[ ] -- Pure function
@@ -34,7 +32,7 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
3432[ ] ffor :: Event a -> (a -> b) -> Event b
3533[ ] fforMaybe :: Event a -> (a -> Maybe b) -> Event b
3634
37−-- Event to identical Event with debug trace.
35+-- Event to identical Event with debug trace. (Only prints if Event is ultimately used.)
3836[ ] traceEvent :: Show a => String -> Event a -> Event a
3937[ ] traceEventWith :: (a -> String) -> Event a -> Event a
4038
@@ -62,12 +60,12 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
6260[ ] fan :: GCompare k => Event (DMap k) -> EventSelector k
6361[ ] select :: EventSelector k -> k a -> Event a
6462
65−-- Event to Event via monadic function
63+-- Event to Event via function that can sample current values
6664[ ] push :: (a -> m (Maybe b)) -> Event a -> Event b
6765[ ] pushAlways :: (a -> m b ) -> Event a -> Event b
6866 -- Note supplied function operates in [H] context
6967
70−-- Event to monadic Event
68+-- Split Event into next occurrence and all other future occurrences, as of now.
7169[H] headE :: Event a -> m (Event a)
7270[H] tailE :: Event a -> m (Event a)
7371[H] headTailE :: Event a -> m (Event a, Event a)
@@ -82,7 +80,7 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
8280-- Extract Behavior from Dynamic
8381[ ] current :: Dynamic a -> Behavior a
8482
85−-- Event to monadic Behavior
83+-- Create Behavior with given initial value, updated when the Event fires.
8684[H] hold :: a -> Event a -> m (Behavior a)
8785
8886-- Transform Behavior to Behavior using function
@@ -93,7 +91,7 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
9391[ ] <> :: Monoid a => Behavior a -> Behavior a -> Behavior a
9492-- ... plus many more due to typeclass membership
9593
96−-- Behavior to Behavior via monadic value
94+-- Behavior to Behavior by sampling current values
9795[S] sample :: Behavior a -> m a
9896[ ] pull :: m a -> Behavior a
9997 -- Note supplied value is in [S] context
@@ -105,14 +103,17 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
105103-- Trivial Dynamic
106104[ ] constDyn :: a -> Dynamic a
107105
108−-- Construct Dynamic from Event
106+-- Create Dynamic with given initial value, updated (various ways) when the Event fires.
109107[H] holdDyn :: a -> Event a -> m (Dynamic a)
110108[H] foldDyn :: (a -> b -> b ) -> b -> Event a -> m (Dynamic b)
111109[H] foldDynMaybe :: (a -> b -> Maybe b ) -> b -> Event a -> m (Dynamic b)
112110[H] foldDynM :: (a -> b -> m' b ) -> b -> Event a -> m (Dynamic b)
113111[H] foldDynMaybeM :: (a -> b -> m' (Maybe b)) -> b -> Event a -> m (Dynamic b)
114112 -- Note m' supplies [H] context
113+
114+-- Initial value is 0; counts Event firings from now.
115115[H] count :: Num b => Event a -> m (Dynamic b)
116+-- Initial Bool value is supplied; toggles at each Event firing.
116117[H] toggle :: Bool -> Event a -> m (Dynamic Bool)
117118
118119-- Transform Dynamic to Dynamic using function
@@ -134,7 +135,7 @@ Since MonadHold depends on MonadSample, any [S] function also runs in [H] contex
134135-- Dynamic to Dynamic, removing updates w/o value change
135136[ ] nubDyn :: Eq a => Dynamic a -> Dynamic a
136137
137−-- Dynamic to identical Dynamic with debug trace.
138+-- Dynamic to identical Dynamic with debug trace. (Only prints if Dynamic is ultimately used.)
138139[ ] traceDyn :: Show a => String -> Dynamic a -> Dynamic a
139140[ ] traceDynWith :: (a -> String) -> Dynamic a -> Dynamic a
140141```
@@ -146,9 +147,6 @@ These functions flatten nested types such as Event-of-Event, Behavior-of-Event,
146147For Events, the returned Event fires whenever the latest Event supplied by the wrapper fires. There are differences in how the functions handle *coincidences* -- situations where the old or new Event fires at the same instant that we switch from old to new. In some cases, the output Event tracks the old Event at the instant of switchover, while in other cases it tracks the new Event.
147148
148149```haskell
149−-- Flatten Event-of-Event to monadic Event. New Event is used immediately.
150−[H] switchPromptly :: Event a -> Event (Event a) -> m (Event a)
151−
152150-- Flatten Behavior-of-Event to Event. Old Event is used during switchover.
153151[ ] switch :: Behavior (Event a) -> Event a
154152
@@ -163,6 +161,11 @@ For Events, the returned Event fires whenever the latest Event supplied by the w
163161[ ] joinDyn :: Dynamic (Dynamic a) -> Dynamic a
164162[ ] joinDynThroughMap :: Ord k => Dynamic (Map k (Dynamic a)) -> Dynamic (Map k a)
165163
166−-- Flatten Event-of-Behavior to monadic Behavior
164+-- Analogous to 'hold': Create a Behavior that is initially identical to the
165+-- supplied Behavior. Updated to track a new Behavior whenever the Event fires.
167166[H] switcher :: Behavior a -> Event (Behavior a) -> m (Behavior a)
167+
168+-- Similar to above, for Events. Created Event initially tracks the first argument.
169+-- At switchover, the output Event immediately tracks the new Event.
170+[H] switchPromptly :: Event a -> Event (Event a) -> m (Event a)
168171```