:memo: Begin documenting effect module.

1 files changed, 27 insertions, 7 deletions

diff --git a/src/lustre/effect.gleam b/src/lustre/effect.gleam
index fff3da6..54d2d65 100644
--- a/src/lustre/effect.gleam
+++ b/src/lustre/effect.gleam
@@ -1,5 +1,25 @@
-//// To read the full documentation for this module, please visit
-//// [https://lustre.build/api/lustre/effect](https://lustre.build/api/lustre/effect)
+//// In other frameworks it's common for components to perform side effects
+//// whenever the need them. An event handler might make an HTTP request, or a
+//// component might reach into the DOM to focus an input.
+////
+//// In Lustre we try to keep side effects separate from our main program loop.
+//// This comes with a whole bunch of benefits like making it easier to test and
+//// reason about our code, making it possible to implement time-travel debugging,
+//// or even to run our app on the server using Lustre's server components. This
+//// is great but we still need to perform side effects at some point, so how do
+//// we do that?
+////
+//// The answer is through the `Effect` type. An application's `init` and `update`
+//// functions typically return a tuple of `#(model, Effect(msg))`. The `Effect`
+//// type is a way of describing to the runtime some side effects that should be
+//// performed.
+////
+//// By going through this abstraction we discourage side effects from being
+//// performed in the middle of our program. Furthermore they provide a mechanism
+//// for effects to send messages *back* to the main program loop so you can, for
+//// example, fire off an HTTP request and turn the response into a message that
+//// can be handled by your `update` function.
+////
 
 // IMPORTS ---------------------------------------------------------------------
 
@@ -26,11 +46,11 @@ pub fn from(effect: fn(fn(msg) -> Nil) -> Nil) -> Effect(msg) {
 
 /// Emit a custom event from a component as an effect. Parents can listen to these
 /// events in their `view` function like any other HTML event.
-/// 
+///
 /// You *probably* don't need to use this type of effect if you're not making use
 /// of Lustre's components, but in rare cases it may be useful to emit custom
 /// events from the DOM node that your Lustre application is mounted to.
-/// 
+///
 pub fn event(name: String, data: Json) -> Effect(msg) {
   Effect([fn(_, emit) { emit(name, data) }])
 }
@@ -46,7 +66,7 @@ pub fn none() -> Effect(msg) {
 // MANIPULATIONS ---------------------------------------------------------------
 
 ///
-/// 
+///
 pub fn batch(effects: List(Effect(msg))) -> Effect(msg) {
   Effect({
     use b, Effect(a) <- list.fold(effects, [])
@@ -55,7 +75,7 @@ pub fn batch(effects: List(Effect(msg))) -> Effect(msg) {
 }
 
 ///
-/// 
+///
 pub fn map(effect: Effect(a), f: fn(a) -> b) -> Effect(b) {
   Effect({
     list.map(effect.all, fn(effect) {
@@ -71,7 +91,7 @@ pub fn map(effect: Effect(a), f: fn(a) -> b) -> Effect(b) {
 /// Perform a side effect by supplying your own `dispatch` function. This is
 /// primarily used internally by the server runtime, but it is also useful for
 /// testing.
-/// 
+///
 pub fn perform(
   effect: Effect(a),
   dispatch: fn(a) -> Nil,