add thunk documentation (fixes #35)

HOW_THUNKED_FUNCTION_WORKS.md

@@ -0,0 +1,68 @@
+Creates thunk with custom equality
+
+Also a unique reference is created, so that one application of rendering function (`f` argument) and equality (`eqFn` argument) is only ever equal to itself
+
+It's done because of a distinction of how compiler generalizes equality functions
+For example:
+1. something like `Eq String` would be OK, since it always returns the same dictionary, and thus the same eq function.
+
+```js
+var eqString = new Eq($foreign.eqStringImpl);
+```
+
+2. something like `Eq (Array String)` probably would not be OK, since it creates a new dictionary on the fly parameterized by String,
+
+```js
+var eqArray = function (dictEq) {
+  return new Eq($foreign.eqArrayImpl(eq(dictEq)));
+};
+```
+
+
+Unique reference forces you to provide equality function beforehand even when you use something like `Eq String`
+
+e.g.
+
+1. This is wrong, `is_eq` will return `false`
+
+```purs
+thunkCreator :: forall a . Eq a => a -> Thunk Array Int
+thunkCreator = thunked eq (\a -> [42])
+foo = thunkCreator "a"
+bar = thunkCreator "a"
+is_eq = Fn.runFn2 unsafeEqThunk foo bar
+```
+
+because it is compiled to
+
+```js
+var thunkCreator = function (dictEq) {
+    return thunked(Data_Eq.eq(dictEq))(function (a) {
+        return [ 42 ];
+    });
+};
+var foo = thunkCreator(Data_Eq.eqString)("a");
+var bar = thunkCreator(Data_Eq.eqString)("a");
+var is_eq = unsafeEqThunk(foo, bar);
+```
+
+2. This is right, `is_eq` will return `true`
+
+```purs
+thunkCreator :: String -> Thunk Array Int
+thunkCreator = thunked eq (\a -> [42])
+foo = thunkCreator "a"
+bar = thunkCreator "a"
+is_eq = Fn.runFn2 unsafeEqThunk foo bar
+```
+
+because it is compiled to
+
+```js
+var thunkCreator = thunked(Data_Eq.eq(Data_Eq.eqString))(function (a) {
+    return [ 42 ];
+});
+var foo = thunkCreator("a");
+var bar = thunkCreator("a");
+var is_eq = unsafeEqThunk(foo, bar);
+```

src/Halogen/VDom/Thunk.purs

@@ -45,6 +45,14 @@ thunk = Fn.mkFn4 \tid eqFn f a →
     (unsafeCoerce f ∷ ThunkArg → f i)
     (unsafeCoerce a ∷ ThunkArg)
 
+-- | Creates thunk with custom equality
+-- |
+-- | Also a unique reference is created, to stress the fact, that one
+-- | application of rendering function (`f` argument) and equality (`eqFn` argument) is only ever equal to itself
+-- |
+-- | It's done because of a distinction of how compiler generalizes equality functions
+-- | For more information check [HOW_THUNKED_FUNCTION_WORKS.md](https://github.com/purescript-halogen/purescript-halogen-vdom/blob/master/HOW_THUNKED_FUNCTION_WORKS.md) document
+
 thunked ∷ ∀ a f i. (a → a → Boolean) → (a → f i) → a → Thunk f i
 thunked eqFn f =
   let
@@ -53,6 +61,10 @@ thunked eqFn f =
   in
     \a → Fn.runFn4 thunk tid eqFn' f a
 
+-- | Creates thunk with equality that is fixed to referential equality (`===`)
+-- |
+-- | Works faster for types like `String` or `Integer`,
+-- | but will not work for arrays and objects
 thunk1 ∷ ∀ a f i. Fn.Fn2 (a → f i) a (Thunk f i)
 thunk1 = Fn.mkFn2 \f a → Fn.runFn4 thunk (unsafeThunkId f) Util.refEq f a