From d5c3af89ab8076bcf4107859c1ba6b47a7815142 Mon Sep 17 00:00:00 2001
From: Akshay Nair <phenax5@gmail.com>
Date: Sun, 15 Jan 2023 00:13:04 +0530
Subject: chore: some more documentation

---
 stdlib/effect.ts | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)

(limited to 'stdlib/effect.ts')

diff --git a/stdlib/effect.ts b/stdlib/effect.ts
index 4a994c4..7eb557c 100644
--- a/stdlib/effect.ts
+++ b/stdlib/effect.ts
@@ -57,16 +57,105 @@ export type Func<Inp = unknown, Out = unknown> =
   | Kind1<Inp, Out>
   | (<_T extends Inp>() => Out)
 
+/**
+ * Monadic bind an effect to a function (Equivalent to haskell's >>= operator)
+ *
+ * @typeParam _Eff - Effect to evaluate first
+ * @typeParam _Fn - Function to call with the result of _Eff
+ *
+ * @example
+ * ```ts
+ * type main = Bind<
+ *   ReadFile<"./file.txt">,
+ *   <contents extends string>() => Print<contents>
+ * >
+ * ```
+ */
 export interface Bind<_Eff extends Effect, _Fn extends Func> extends Effect {}
 
+/**
+ * Bind result of evaluating an effect to a label (Equivalent to haskell's <- syntax)
+ *
+ * Note: labels are scoped to outermost Do, Bind, Try, etc scopes
+ *
+ * @typeParam _Name - The name of label
+ * @typeParam _Eff - Effect to evaluate
+ *
+ * @example
+ * ```ts
+ * type main = Do<[
+ *   // contents <- readFile "./file.txt"
+ *   BindTo<"contents", ReadFile<"./file.txt">>,
+ *   Bind<Label<"contents">, <c extends string>() => Print<c>>
+ * ]>
+ * ```
+ */
 export interface BindTo<_Name extends string, _Eff extends Effect>
   extends Effect {}
+
+/**
+ * Access a label defined with {@link BindTo}
+ *
+ * @typeParam _Name - The name of label
+ *
+ * @example
+ * ```ts
+ * type main = Do<[
+ *   BindTo<"contents", ReadFile<"./file.txt">>,
+ *   Bind<Label<"contents">, <c extends string>() => Print<c>>
+ * ]>
+ * ```
+ */
 export interface Label<_Name extends string> extends Effect {}
 
+/**
+ * Evaluate a sequence of effects in series and get the list of results
+ *
+ * @typeParam _Effs - List of effects
+ *
+ * @example
+ * ```ts
+ * type main = Bind<
+ *   Seq<[ Pure<1>, ReadFile<"./foobar.txt">  ]>,
+ *   <t extends [number, string]>() => Print<t>
+ * >
+ * ```
+ */
 export interface Seq<_Effs extends Effect[]> extends Effect {}
 
+/**
+ * Evaluate a sequence of effects in series and get the result of the last effect (Equivalent to haskell's do syntax)
+ *
+ * @typeParam _Effs - List of effects
+ *
+ * @example
+ * ```ts
+ * type main = Bind<
+ *   Do<[ Pure<1>, ReadFile<"./foobar.txt">  ]>,
+ *   <t extends string>() => Print<t>
+ * >
+ * ```
+ */
 export interface Do<_Effs extends Effect[]> extends Effect {}
 
+/**
+ * Wrap a value inside an effect (Equivalent to haskell's pure function)
+ *
+ * @typeParam V - Value
+ *
+ * @example
+ * ```ts
+ * type main = Bind<Pure<1>, <t extends number>() => Print<t>>
+ * ```
+ */
 export interface Pure<V> extends Effect<V> {}
 
+/**
+ * Noop effect that does nothing (returns undefined)
+ *
+ * @example
+ * ```ts
+ * type main = Bind<Noop, <t extends undefined>() => Print<t>>
+ * ```
+ */
 export interface Noop extends Effect {}
-- 
cgit v1.3.1