From 5726e0d9c39922a8aacc00f96cbaf9926b689a89 Mon Sep 17 00:00:00 2001
From: rowan <rowan@kitsu.cafe>
Date: Mon, 31 Mar 2025 20:45:26 -0500
Subject: [PATCH] add documentation for each method

---
 README.md    | 138 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 src/curry.js |   1 +
 2 files changed, 138 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5238d0d..93626a5 100644
--- a/README.md
+++ b/README.md
@@ -46,28 +46,77 @@ const twelve = curriedAdd(4, 4, 4) // 12
 ```
 
 ### Option
+> Option<T> = Some<T> | None
 
 Represents a value which may not exist.
 
+
 #### Methods
 ##### of :: Option f => a -> f a
 > Option.of\<a\>(value: a) -> Option\<a\>
 
+Creates a new `Some\<T\>` from `T`
+
+```js
+const some = Option.of(1) // Some<number>(1)
+```
+
 ##### zero :: Option f => () -> f a
-> Option.zero\<a\>(value: a) -> Option\<a\>
+> Option.zero() -> Option\<()\>
+
+Creates a new `Err<()>`
+
+```js
+const none = Option.zero() // None
+```
 
 ##### chain :: Option m => m a ~> (a -> m b) -> m b
 > Option\<T\>.chain\<U\>(fn: (value: T) -> Option\<U\>) -> Option\<U\>
 
+Transform a `Option\<T\>` into `Option\<U\>` by applying `fn(T) -> Option\<U\>`.
+
+```js
+const some = Option.of(1)
+const next = some.chain(x => Some(`value ${x}`)) // Some<string>('value 1')
+None.chain(x => Some(`value ${x}`)) // None
+const none = some.chain(None) // None
+none.chain(() => Some(1)) // None
+```
+
 ##### map :: Option f => f a ~> (a -> b) -> f b
 > Option\<T\>.map\<U\>(fn: (value: T) -> U) -> Option\<U\>
 
 ##### alt :: Option f => f a ~> f a -> f a
 > Option\<T\>.alt(other: Option\<T\>) -> Option\<T\>
 
+Choose between either the first or second `Option` based on existence.
+
+```js
+const some = Option.of(1)
+const none = Option.zero()
+
+some.alt(none) // Some<number>(1)
+none.alt(some) // Some<number>(1)
+some.alt(Some(2)) // Some<number>(1)
+Some(2).alt(some) // Some<number>(2)
+none.alt(None) // None
+None.alt(none) // None
+```
+
 ##### fold :: Option f => f a ~> ((b, a) -> b, b) -> b
 > Option\<T\>.fold\<U\>(fn: ((acc: U, value: T) -> U, initial: U) -> U) -> U
 
+Fold over a `Option`, accumulating the value. This is `unwrap_or_default` in Rust.
+
+```js
+const some = Some(1)
+some.fold((acc, x) => x), 2) // 1
+some.fold((acc, x) => acc), 2) // 2
+
+const none = Option.zero()
+none.fold((acc, x) => x, 2) // 2
+```
+
 ##### isSome :: Option f => () -> boolean
 > Option\<T\>.isSome() -> boolean
 
@@ -75,6 +124,7 @@ Represents a value which may not exist.
 > Option\<T\>.isNone() -> boolean
 
 ### Result
+> Result<T, E> = Ok<T> | Err<E>
 
 Represents a value which may fail.
 
@@ -82,27 +132,113 @@ Represents a value which may fail.
 ##### of :: Result f => a -> f a
 > Result.of\<a\>(value: a) -> Result\<a, ()\>
 
+Creates a new `Ok\<T\>` from `T`
+
+```js
+const ok = Result.of(1) // Ok<number>(1)
+```
+
 ##### zero :: Result f => () -> f a
 > Result.zero() -> Result\<(), ()\>
 
+Creates a new `Err<()>`
+
+```js
+const err = Result.zero() // Err<()>()
+```
+
 ##### chain :: Result m => m a ~> (a -> m b) -> m b
 > Result\<T, E\>.chain\<U\>(fn: (value: T) -> Result<U, E>) -> Result\<U, E\>
 
+Transform a `Result\<T, E\>` into `Result\<U, E\>` by applying `fn(T) -> Result\<U, E\>`.
+
+```js
+const ok = Result.of(1)
+const next = ok.chain(x => Ok(`value ${x}`)) // Ok<string>('value 1')
+Err(0).chain(x => Ok(1)) // Err(0)
+const err = next.chain(() => Err(0)) // Err(0)
+err.chain(() => Ok(1)) // Err(0)
+```
+
 ##### map :: Result f => f a ~> (a -> b) -> f b
 > Result\<T, E\>.map\<U\>(fn: (value: T) -> U) -> Result\<U, E\>
 
+Transform a `Result\<T, E\>` into a `Result\<U, E\>` by applying `fn(T) -> U`
+
+```js
+const ok = Result.of(1)
+const next = ok.map(x => `value ${x}`) // Ok<string>('value 1')
+Err(0).map(x => Ok(1)) // Err(0)
+
+```
+
 ##### alt :: Result f => f a ~> f a -> f a
 > Result\<T, E\>.alt(other: Result\<T, E\>) -> Result\<T, E\>
 
+Choose between either the first or second `Result` based on success.
+
+```js
+const ok = Result.of(1)
+const err = Result.zero()
+
+ok.alt(err) // Ok<number>(1)
+err.alt(ok) // Ok<number>(1)
+ok.alt(Ok(2)) // Ok<number>(1)
+Ok(2).alt(ok) // Ok<number>(2)
+err.alt(Err(new Error('wont see this'))) // Err<()>()
+Err(new Error('hi! :3')).alt(err) // Err<Error>(new Error('hi! :3'))
+```
+
 ##### fold :: Result f => f a ~> ((b, a) -> b, b) -> b
 > Result\<T, E\>.fold\<U\>(fn: ((acc: U, value: T) -> U, initial: U) -> U) -> U
 
+Fold over a `Result`, accumulating the value. This is `unwrap_or_default` in Rust.
+
+```js
+const ok = Ok(1)
+ok.fold((acc, x) => x), 2) // 1
+ok.fold((acc, x) => acc), 2) // 2
+
+const err = Result.zero()
+err.fold((acc, x) => x, 2) // 2
+```
+
 ##### bimap :: Result f => f a c ~> (a -> b, c -> d) -> f b d
 > Result\<T1, E1\>.bimap\<T2, E2\>(x: (value: T1) -> T2, y: (error: E1) -> E2) -> Result\<T2, E2\>
 
+```js
+const ok = Ok(1)
+
+ok.bimap(
+    x => x + 1,
+    y => y * 2
+) // Ok(2)
+
+const err = Err(4)
+
+err.bimap(
+    x => x + 1,
+    y => y * 2
+) // Err(8)
+```
+
 ##### isOk :: Result f => () -> boolean
 > Result\<T, E\>.isOk() -> boolean
 
+Returns a boolean based on whether the Result is `Some<T>`
+
+```js
+Ok(1).isSome() // true
+Err(1).isSome() // false
+```
+
 ##### isErr :: Result f => () -> boolean
 > Result\<T, E\>.isErr() -> boolean
 
+Returns a boolean based on whether the Result is `Err<E>`
+
+```js
+Ok(1).isErr() // false
+Err(1).isErr() // true
+```
+
diff --git a/src/curry.js b/src/curry.js
index a193971..a6ac077 100644
--- a/src/curry.js
+++ b/src/curry.js
@@ -69,3 +69,4 @@ export function curry(func) {
   }
 }
 
+