@@ -18,25 +18,36 @@ import Native.Lazy
1818
1919data Lazy a = L { force : () -> a }
2020
21−{-| Memoize a thunk so it is evaluated at most once. -}
21+{-| Delay a computation. This function memoizes results, so
22+it guarantees that the computation will be evaluated at most once.
23+-}
2224lazy : (() -> a) -> Lazy a
2325lazy t = L { force = (Native.Lazy.lazy t) }
2426
25−{-| Execute a lazy value. -}
27+{-| Evaluate a lazy value. It saves the result so the second time
28+you call `force` it does not run the computation again. -}
2629force : Lazy a -> a
2730force (L r) = r.force ()
2831
29−{-| Lazily apply a pure function to a lazy value. -}
32+{-| Lazily apply a function to a lazy value. The computation
33+will be delayed until you force the resulting value.
34+-}
3035map : (a -> b) -> Lazy a -> Lazy b
3136map f t = lazy <| \() ->
3237 f . force <| t
3338
34−{-| Lazily apply a Lazy function to a Lazy value. -}
39+{-| Lazily apply a lazy function to a lazy value. This can
40+be used to lazily apply a function to many arguments:
41+
42+```haskell
43+f `map` a `apply` b `apply` c
44+```
45+-}
3546apply : Lazy (a -> b) -> Lazy a -> Lazy b
3647apply f x = lazy <| \() ->
3748 (force f) (force x)
3849
39−{-| Lazily chain together Lazy computations. -}
50+{-| Lazily chain together lazy computations. -}
4051bind : Lazy a -> (a -> Lazy b) -> Lazy b
4152bind x k = lazy <| \() ->
4253 force . k . force <| x