Add Missing Documentation (#1)

* - Added import and documentation URLs. * - Removed outdated dependency reference. * - Updated main README with module documentation links. * - Updated dangling aside statements to use blockquoes for differentiation. * - [@eznastdlib/async] Added missing examples and docstrings. * - [enzastdlib/async] Ran examples through `deno fmt`. * - [enzastdlib/collections] Added missing docstrings and examples. * - Removed extra spacing. * - [@enzastdlib/errors] Added missing docstrings and examples. * - [@enzastdlib/events] Added missing docstrings and examples. * - [@enzastdlib/strings] Added missing docstrings and examples. * - [@enzastdlib/os] Added missing docstrings and examples. - **NOTE**: The MacOS paths were not tested as I do not have access to a MacOS device. - [@enzastdlib/os] Added credits for XDG documentation used. * - [@enzastdlib/path] Added missing docstrings and examples. * - [@enzastdlib/os] Fixed missing code fences. * - [@enzastdlib/json5] Added missing docstrings and examples. - [@enzastdlib/json5] Added TODO for creating tests. * - [@enzastdlib/testing] Added missing docstrings and examples. * - [@enzastdlib/json5] Fixed docstring typo. * - [@enzastdlib/schema] Added missing docstrings and examples. * - [@enzastdlib/json5] Fixed import typo. * - Added global TODOs for documentation. * - [@enzastdlib/schema] Added missing Markdown code block language specifiers.
novacbn · Jul 25, 2023 · d9015cc · d9015cc
1 parent 0f26527
commit d9015cc
Show file tree

Hide file tree

Showing 50 changed files with 1,257 additions and 84 deletions.
diff --git a/README.md b/README.md
@@ -6,33 +6,35 @@
 
 The following modules are considered public API ready for consumption:
 
-- [`@enzastdlib/async`](./async) — Utilities for working with asynchronous and `Promise`-based code.
-- [`@enzastdlib/collections`](./collections) — Utilities for working with collections like arrays and records.
-- [`@enzastdlib/commands`](./commands) — Create command line tools with validation powered by [JSON Schema 2019-09](https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8).
-- [`@enzastdlib/decorators`](./decorators) — Create function decorators that access metadata with a streamlined API.
-- [`@enzastdlib/environment`](./environment) — Parse and validate both environment variables and dotenv files powered by [JSON Schema 2019-09](https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8).
-- [`@enzastdlib/errors`](./errors) — General error objects that are used across `enzastdlib`.
-- [`@enzastdlib/path`](./events) — Create typed events with a typed version of `EventTarget`.
-- [`@enzastdlib/json5`](./json5) — Parse JSON5 documents and expressions.
-- [`@enzastdlib/os`](./os) — Utilities for abstracting away operating system specifics.
-- [`@enzastdlib/path`](./path) — Utilities for working with file system paths and URLs.
-- [`@enzastdlib/realm`](./realm) — Create custom JavaScript and TypeScript execution environments.
-- [`@enzastdlib/rpc`](./rpc) — Contains supplemental typing for creating fully typed and validated RPC clients and servers.
-- [`@enzastdlib/rpc-http`](./rpc-http) — Create fully typed and validated RPC clients and servers using HTTP as the transport.
-- [`@enzastdlib/rpc-messageport`](./rpc-messageport) — Create fully typed and validated RPC clients and servers using [`MessagePort`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort)-like API instances as the transport.
-- [`@enzastdlib/rpc-protocol`](./rpc-protocol) — Create fully typed and validated RPC clients and servers powered by [JSON Schema 2019-09](https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8).
-- [`@enzastdlib/rpc-streams`](./rpc-streams) — Create fully typed and validated RPC clients and servers using a pair of [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) / [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) instances as the transport.
-- [`@enzastdlib/schema`](./schema) — Create easy to use validators powered by [JSON Schema 2019-09](https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8).
-- [`@enzastdlib/strings`](./strings) — Utilities for working with strings.
-- [`@enzastdlib/testing`](./testing) — Utilities for working with Deno's testing API.
+- [`@enzastdlib/async`](https://deno.land/x/enzastdlib/async/mod.ts?doc) — Utilities for working with asynchronous and `Promise`-based code.
+- [`@enzastdlib/collections`](https://deno.land/x/enzastdlib/collections/mod.ts?doc) — Utilities for working with collections like arrays and records.
+- [`@enzastdlib/commands`](https://deno.land/x/enzastdlib/commands/mod.ts?doc) — Create command line tools with validation powered by [JSON Schema 2019-09](https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8).
+- [`@enzastdlib/decorators`](https://deno.land/x/enzastdlib/decorators/mod.ts?doc) — Create function decorators that access metadata with a streamlined API.
+- [`@enzastdlib/environment`](https://deno.land/x/enzastdlib/environment/mod.ts?doc) — Parse and validate both environment variables and dotenv files powered by [JSON Schema 2019-09](https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8).
+- [`@enzastdlib/errors`](https://deno.land/x/enzastdlib/errors/mod.ts?doc) — General error objects that are used across `enzastdlib`.
+- [`@enzastdlib/path`](https://deno.land/x/enzastdlib/events/mod.ts?doc) — Create typed events with a typed version of `EventTarget`.
+- [`@enzastdlib/json5`](https://deno.land/x/enzastdlib/json5/mod.ts?doc) — Parse JSON5 documents and expressions.
+- [`@enzastdlib/os`](https://deno.land/x/enzastdlib/os/mod.ts?doc) — Utilities for abstracting away operating system specifics.
+- [`@enzastdlib/path`](https://deno.land/x/enzastdlib/path/mod.ts?doc) — Utilities for working with file system paths and URLs.
+- [`@enzastdlib/realm`](https://deno.land/x/enzastdlib/realm/mod.ts?doc) — Create custom JavaScript and TypeScript execution environments.
+- [`@enzastdlib/rpc`](https://deno.land/x/enzastdlib/rpc/mod.ts?doc) — Contains supplemental typing for creating fully typed and validated RPC clients and servers.
+- [`@enzastdlib/rpc-http`](https://deno.land/x/enzastdlib/rpc-http/mod.ts?doc) — Create fully typed and validated RPC clients and servers using HTTP as the transport.
+- [`@enzastdlib/rpc-messageport`](https://deno.land/x/enzastdlib/rpc-messageport/mod.ts?doc) — Create fully typed and validated RPC clients and servers using [`MessagePort`](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort)-like API instances as the transport.
+- [`@enzastdlib/rpc-protocol`](https://deno.land/x/enzastdlib/rpc-protocol/mod.ts?doc) — Create fully typed and validated RPC clients and servers powered by [JSON Schema 2019-09](https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8).
+- [`@enzastdlib/rpc-streams`](https://deno.land/x/enzastdlib/rpc-streams/mod.ts?doc) — Create fully typed and validated RPC clients and servers using a pair of [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) / [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) instances as the transport.
+- [`@enzastdlib/schema`](https://deno.land/x/enzastdlib/schema/mod.ts?doc) — Create easy to use validators powered by [JSON Schema 2019-09](https://json-schema.org/specification-links.html#draft-2019-09-formerly-known-as-draft-8).
+- [`@enzastdlib/strings`](https://deno.land/x/enzastdlib/strings/mod.ts?doc) — Utilities for working with strings.
+- [`@enzastdlib/testing`](https://deno.land/x/enzastdlib/testing/mod.ts?doc) — Utilities for working with Deno's testing API.
 
 ## Importing
 
-...
+```typescript
+import * as mod from 'https://deno.land/x/enzastdlib/.../mod.ts';
+```
 
 ## Documentation
 
-...
+Visit the documentation at [Deno's module registry](https://deno.land/x/enzastdlib?doc).
 
 ## Need Help?
 

diff --git a/TODO.md b/TODO.md
@@ -2,4 +2,8 @@
 
 - Create API examples via the `@example` JSDoc annotation for all public API.
 
+- Add possible thrown exceptions to all public API docs.
+
+- Add Deno flags used to all public API docs.
+
 - Vendor external requirements.
diff --git a/async/README.md b/async/README.md
@@ -4,8 +4,10 @@ Utilities for working with asynchronous and `Promise`-based code.
 
 ## Importing
 
-...
+```typescript
+import * as mod from 'https://deno.land/x/enzastdlib/async/mod.ts';
+```
 
 ## Documentation
 
-...
+Visit the documentation at [Deno's module registry](https://deno.land/x/enzastdlib/async/mod.ts?doc).
diff --git a/async/iterable.ts b/async/iterable.ts
@@ -1,3 +1,30 @@
+/**
+ * Returns all values collected from the `iterable` in an array.
+ *
+ * > **NOTE**: This function is the equivilent of [`Array.fromAsync`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fromAsync)
+ * > if it available in your runtime use that instead.
+ *
+ * @param iterable
+ * @returns
+ *
+ * @example
+ * ```typescript
+ * import { assertEquals } from 'https://deno.land/std/testing/asserts.ts';
+ * import { arrayFromIterable } from 'https://deno.land/x/enzastdlib/async/mod.ts';
+ *
+ * async function* myGenerator(): AsyncGenerator<number> {
+ *     yield Promise.resolve(1);
+ *     yield Promise.resolve(2);
+ *     yield Promise.resolve(3);
+ * }
+ *
+ * const generator = myGenerator();
+ *
+ * const numbers = await arrayFromIterable(generator);
+ *
+ * assertEquals(numbers, [1, 2, 3]);
+ * ```
+ */
 export async function arrayFromIterable<Value>(
 	iterable: AsyncIterable<Value>,
 ): Promise<Value[]> {

diff --git a/async/promise.ts b/async/promise.ts
@@ -1,5 +1,18 @@
 /**
  * Returns type wrapped in a `Promise` if not already a `Promise`-wrapped value.
+ *
+ * @example
+ * ```typescript
+ * import type { Promisify } from 'https://deno.land/x/enzastdlib/async/mod.ts';
+ *
+ * function plainFunction(): number {
+ *     return 1;
+ * }
+ *
+ * type plainFunctionReturn = ReturnType<typeof plainFunction>; // `number`
+ *
+ * type plainFunctionReturnPromisified = Promisify<plainFunctionReturn>; // `Promise<number>`
+ * ```
  */
 export type Promisify<Value> = Value extends Promise<unknown> ? Value
 	: Promise<Value>;
@@ -8,6 +21,27 @@ export type Promisify<Value> = Value extends Promise<unknown> ? Value
  * Returns a `Promise` instance along with its resolve and reject functions.
  *
  * @returns
+ *
+ * @example
+ * ```typescript
+ * import {
+ *     assertEquals,
+ *     assertInstanceOf,
+ * } from 'https://deno.land/std/testing/asserts.ts';
+ * import { makePromise } from 'https://deno.land/x/enzastdlib/async/mod.ts';
+ * import { assertTypeOf } from 'https://deno.land/x/enzastdlib/testing/mod.ts';
+ *
+ * const { promise, resolve, reject } = makePromise<number>();
+ *
+ * assertInstanceOf(promise, Promise);
+ *
+ * assertTypeOf(resolve, 'function');
+ * assertTypeOf(reject, 'function');
+ *
+ * resolve(42);
+ *
+ * assertEquals(await promise, 42);
+ * ```
  */
 export function makePromise<Value = void>(): {
 	promise: Promise<Value>;

diff --git a/collections/README.md b/collections/README.md
@@ -4,8 +4,10 @@ Utilities for working with collections like arrays and records.
 
 ## Importing
 
-...
+```typescript
+import * as mod from 'https://deno.land/x/enzastdlib/collections/mod.ts';
+```
 
 ## Documentation
 
-...
+Visit the documentation at [Deno's module registry](https://deno.land/x/enzastdlib/collections/mod.ts?doc).
diff --git a/collections/class.ts b/collections/class.ts
@@ -2,6 +2,25 @@ import { OmitValues, PickValues } from './object.ts';
 
 /**
  * Returns an `Object` containing all the methods of a `Class`.
+ *
+ * @example
+ * ```typescript
+ * import type { MethodsOf } from 'https://deno.land/x/enzastdlib/collections/mod.ts';
+ *
+ * class MyClass {
+ *     myProperty = false;
+ *
+ *     methodOne(): number {
+ * 	       return 42;
+ *     }
+ *
+ *     methodTwo(): string {
+ *         return "Hello World";
+ *     }
+ * }
+ *
+ * type MyMethods = MethodsOf<MyClass>; // `{ methodOne: () => number; methodTwo: () => string; }`
+ * ```
  */
 export type MethodsOf<Cls> = PickValues<
 	Cls,
@@ -12,6 +31,25 @@ export type MethodsOf<Cls> = PickValues<
 
 /**
  * Returns an `Object` containing all the properties of a `Class`.
+ *
+ * @example
+ * ```typescript
+ * import type { PropertiesOf } from 'https://deno.land/x/enzastdlib/collections/mod.ts';
+ *
+ * class MyClass {
+ *     myProperty = false;
+ *
+ *     methodOne(): number {
+ * 	       return 42;
+ *     }
+ *
+ *     methodTwo(): string {
+ *         return "Hello World";
+ *     }
+ * }
+ *
+ * type MyProperties = PropertiesOf<MyClass>; // `{ myProperty: boolean; }`
+ * ```
  */
 export type PropertiesOf<Cls> = OmitValues<
 	Cls,

diff --git a/collections/object.ts b/collections/object.ts
@@ -1,28 +1,87 @@
 /**
- * Represents an `Object` that has no properties.
+ * Represents an `Object` type that has no properties.
+ *
+ * @example
+ * ```typescript
+ * import type { EmptyObject } from 'https://deno.land/x/enzastdlib/collections/mod.ts';
+ *
+ * type X = EmptyObject; // `{ [x: string]: never; [x: number]: never; [x: symbol]: never }`
+ * ```
  */
 export type EmptyObject = Record<PropertyKey, never>;
 
 /**
- * Returns an `Object` where properties with `Type` as the their typing are omitted.
+ * Returns an `Object` where members with the given type are picked into a new `Object` type.
+ *
+ * @example
+ * ```typescript
+ * import type { PickValues } from 'https://deno.land/x/enzastdlib/collections/mod.ts';
+ *
+ * const MY_CONSTANT_OBJECT = {
+ *     myBoolean: false,
+ *
+ *     myNumber: 42,
+ *
+ *     myString: 'Hello World',
+ *
+ *     otherNumber: 84,
+ * } as const;
+ *
+ * type FilteredValues = PickValues<typeof MY_CONSTANT_OBJECT, number>; // `{ readonly myNumber: 42; readonly otherNumber: 84; }`
  */
 export type PickValues<Obj, Value> = {
 	[Key in keyof Obj as Obj[Key] extends Value ? Key : never]: Obj[Key];
 };
 
 /**
- * Returns an `Object` where properties with `Type` as the their typing are omitted.
+ * Returns an `Object` where members with the given type are omitted from a new `Object` type.
+ *
+ * @example
+ * ```typescript
+ * import type { OmitValues } from 'https://deno.land/x/enzastdlib/collections/mod.ts';
+ *
+ * const MY_CONSTANT_OBJECT = {
+ *     myBoolean: false,
+ *
+ *     myNumber: 42,
+ *
+ *     myString: 'Hello World',
+ *
+ *     otherNumber: 84,
+ * } as const;
+ *
+ * type FilteredValues = OmitValues<typeof MY_CONSTANT_OBJECT, number>; // `{ readonly myBoolean: false; readonly myString: "Hello World"; }`
  */
 export type OmitValues<Obj, Value> = {
 	[Key in keyof Obj as Obj[Key] extends Value ? never : Key]: Obj[Key];
 };
 
 /**
- * Returns all the values of an `Object` as a type union.
+ * Returns all the values of an `Object` as a type union of its values.
+ *
+ * @example
+ * ```typescript
+ * import type { ValueOf } from 'https://deno.land/x/enzastdlib/collections/mod.ts';
+ *
+ * const MY_CONSTANT_OBJECT = {
+ *     x: 1,
+ * 	   y: 2,
+ *     z: 3
+ * } as const;
+ *
+ * type MyValues = ValueOf<typeof MY_CONSTANT_OBJECT>; // `1 | 2 | 3`
+ * ```
  */
 export type ValueOf<Obj> = Obj[keyof Obj];
 
 /**
- * Represents an `Object` that has unknown properties.
+ * Represents an `Object` type that has unknown properties.
+ *
+ * @example
+ * ```typescript
+ * import type { UnknownObject } from 'https://deno.land/x/enzastdlib/collections/mod.ts';
+ *
+ * type X = UnknownObject; // `{ [x: string]: unknown; [x: number]: unknown; [x: symbol]: unknown }`
+ * ```
  */
 export type UnknownObject = Record<PropertyKey, unknown>;
diff --git a/commands/README.md b/commands/README.md
@@ -4,11 +4,13 @@ Create command line tools with validation powered by [JSON Schema 2019-09](https
 
 ## Importing
 
-...
+```typescript
+import * as mod from 'https://deno.land/x/enzastdlib/commands/mod.ts';
+```
 
 ## Documentation
 
-...
+Visit the documentation at [Deno's module registry](https://deno.land/x/enzastdlib/commands/mod.ts?doc).
 
 ## Dependencies
 

diff --git a/commands/exit_codes.ts b/commands/exit_codes.ts
@@ -10,8 +10,8 @@ export const EXIT_CODES = {
 	/**
 	 * Represents when the command was called successfully.
 	 *
-	 * **NOTE**: By default this value is used if no number
-	 * is returned by the commands callback.
+	 * > **NOTE**: By default this value is used if no number
+	 * > is returned by the commands callback.
 	 */
 	resolved: 0,
 

diff --git a/decorators/README.md b/decorators/README.md
@@ -4,8 +4,10 @@ Create function decorators that access metadata with a streamlined API.
 
 ## Importing
 
-...
+```typescript
+import * as mod from 'https://deno.land/x/enzastdlib/decorators/mod.ts';
+```
 
 ## Documentation
 
-...
+Visit the documentation at [Deno's module registry](https://deno.land/x/enzastdlib/decorators/mod.ts?doc).
diff --git a/environment/README.md b/environment/README.md
@@ -4,11 +4,13 @@ Parse and validate both environment variables and dotenv files powered by [JSON
 
 ## Importing
 
-...
+```typescript
+import * as mod from 'https://deno.land/x/enzastdlib/environment/mod.ts';
+```
 
 ## Documentation
 
-...
+Visit the documentation at [Deno's module registry](https://deno.land/x/enzastdlib/environment/mod.ts?doc).
 
 ## Compatibility
 

diff --git a/errors/README.md b/errors/README.md
@@ -4,8 +4,10 @@ General error objects that are used across `enzastdlib`.
 
 ## Importing
 
-...
+```typescript
+import * as mod from 'https://deno.land/x/enzastdlib/errors/mod.ts';
+```
 
 ## Documentation
 
-...
+Visit the documentation at [Deno's module registry](https://deno.land/x/enzastdlib/errors/mod.ts?doc).