From e75a5a15912b8f297fe9c9747f574486d6c4e334 Mon Sep 17 00:00:00 2001
From: Akshay Nair <phenax5@gmail.com>
Date: Sat, 14 Jan 2023 18:16:41 +0530
Subject: chore: adds some docs

---
 stdlib/effect.ts | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 stdlib/test.ts   | 20 +++++++++++++++-----
 2 files changed, 61 insertions(+), 5 deletions(-)

(limited to 'stdlib')

diff --git a/stdlib/effect.ts b/stdlib/effect.ts
index 9b19197..4a994c4 100644
--- a/stdlib/effect.ts
+++ b/stdlib/effect.ts
@@ -1,12 +1,58 @@
+/**
+ * Generic interface for declaring effects
+ * @typeParam T - The output generated by the effect (defaults to `unknown`)
+ *
+ * @example
+ * ```ts
+ * interface MyEffect extends Effect<string[]> {}
+ * ```
+ */
 export interface Effect<T = unknown> {
+  /** @hidden */
   output: T
 }
 
+/**
+ * An implementation of `* -> *` higher-kinded type
+ *
+ * @typeParam Inp - The input type
+ * @typeParam Out - The output type
+ *
+ * @example
+ * You can define a return property for the function body
+ *   and use `this['input']` to access the argument
+ *   Uses - {@link util.ApplyK}
+ *
+ * ```ts
+ * interface SomeFunc extends Kind1<number, string> {
+ *   return: `Your number is ${this['input']}`,
+ * }
+ *
+ * type result = ApplyK<SomeFunc, 200>
+ * ```
+ */
 export interface Kind1<Inp = unknown, Out = unknown> {
   input: Inp
   return: Out
 }
 
+/**
+ * Generic function definition as a union of a kind and anonymous function
+ *
+ * @typeParam Inp - The input type
+ * @typeParam Out - The output type
+ *
+ * @example
+ * In addition to defining a kind (see - {@link Kind1}),
+ *  you can also in some places, use inline lambda functions
+ *
+ * ```ts
+ * type main = Bind<
+ *   ReadFile<"./file.txt">,
+ *   <contents extends string>() => Print<contents>
+ * >
+ * ```
+ */
 export type Func<Inp = unknown, Out = unknown> =
   | Kind1<Inp, Out>
   | (<_T extends Inp>() => Out)
diff --git a/stdlib/test.ts b/stdlib/test.ts
index fd1045b..a3b1d80 100644
--- a/stdlib/test.ts
+++ b/stdlib/test.ts
@@ -2,11 +2,21 @@ import { Do, Effect, Kind1 } from './effect'
 import { Throw, Try } from './exception'
 import { Equals } from './util'
 
-export interface Config {
-  // compileTimeTestFailures: false
-  // stopAtFailure: true // TODO: stopAtFailure
-}
-
+/**
+ * Assert a boolean expression is true
+ *
+ * @typeParam _B - The boolean value to assert
+ *
+ * @throws {"assertion error"} if false
+ *
+ * @example
+ * Here's an example checking if `SomeValue` is not equal to [1,2,3]
+ * Uses - {@link util.Not}, {@link util.Equals}
+ *
+ * ```ts
+ * Assert<Not<Equals<SomeValue, [1, 2, 3]>>>
+ * ```
+ */
 export interface Assert<_B extends boolean> extends Effect {}
 
 export interface Test<_m extends string, _effs extends Effect[]>
-- 
cgit v1.3.1