docs: document the public API as TSDoc (generated from type declarations)

README.md

@@ -19,67 +19,7 @@ assert.notEqual(1, 2)
 
 ## API
 
-#### `assert(value[, message])`
-
-Throws an `AssertionError` unless `value` is truthy. If `message` is an `Error` instance, it is thrown directly instead of being wrapped in an `AssertionError`.
-
-#### `assert.AssertionError`
-
-An `Error` subclass thrown by all assertions on failure. Instances have the following properties:
-
-#### `error.actual`
-
-The `actual` value passed to the assertion, if any.
-
-#### `error.expected`
-
-The `expected` value passed to the assertion, if any.
-
-#### `error.operator`
-
-The name of the operator used by the assertion that failed, such as `'=='` or `'strictEqual'`.
-
-If no `message` is provided to `AssertionError`, one is generated from `actual`, `expected`, and `operator`.
-
-#### `assert.fail([message])`
-
-Throws an `AssertionError` unconditionally. Defaults `message` to `'Failed'` if not provided.
-
-#### `assert.ok(value[, message])`
-
-Throws an `AssertionError` unless `value` is truthy. Equivalent to `assert()`.
-
-#### `assert.notOk(value[, message])`
-
-Throws an `AssertionError` if `value` is truthy.
-
-#### `assert.equal(actual, expected[, message])`
-
-Throws an `AssertionError` unless `actual == expected`, using the `==` operator. `NaN` is treated as equal to `NaN`.
-
-#### `assert.notEqual(actual, expected[, message])`
-
-Throws an `AssertionError` unless `actual != expected`, using the `!=` operator. `NaN` is treated as equal to `NaN`.
-
-#### `assert.strictEqual(actual, expected[, message])`
-
-Throws an `AssertionError` unless `actual` and `expected` are the same value, as determined by `Object.is()`.
-
-#### `assert.notStrictEqual(actual, expected[, message])`
-
-Throws an `AssertionError` unless `actual` and `expected` are not the same value, as determined by `Object.is()`.
-
-#### `assert.match(actual, regexp[, message])`
-
-Throws an `AssertionError` unless `actual` is a string that matches `regexp`.
-
-#### `assert.doesNotMatch(actual, regexp[, message])`
-
-Throws an `AssertionError` unless `actual` is a string that does not match `regexp`.
-
-#### `assert.ifError(actual)`
-
-Throws an `AssertionError` unless `actual` is `undefined` or `null`.
+See the [`bare-assert` reference](https://docs.pears.com/reference/bare/modules/bare-assert).
 
 ## License
 

index.d.ts

@@ -1,28 +1,120 @@
+/**
+ * Throw an `AssertionError` if `value` is falsy.
+ * @param value - The value to assert is truthy.
+ * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown
+ * directly instead of an `AssertionError`.
+ * @throws {AssertionError} thrown if `value` is falsy (unless `message` is an `Error` instance,
+ * which is thrown instead).
+ */
 declare function assert(value: any, message?: string | Error): void
 
 declare namespace assert {
+  /**
+   * Error thrown when an assertion fails, carrying the `actual`, `expected`, and `operator`
+   * involved.
+   */
   export class AssertionError extends Error {
     constructor(opts?: { message?: string; actual?: any; expected?: any; operator?: string })
 
+    /** The actual value that failed the assertion. */
     actual?: any
+    /** The expected value the assertion was checked against. */
     expected?: any
+    /**
+     * The comparison operator used by the assertion that failed, for example `'=='` or
+     * `'strictEqual'`.
+     */
     operator?: string
   }
 
+  /**
+   * Throw an `AssertionError` if `value` is falsy.
+   * @param value - The value to assert is truthy.
+   * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown
+   * directly instead of an `AssertionError`.
+   * @throws {AssertionError} thrown if `value` is falsy (unless `message` is an `Error` instance,
+   * which is thrown instead).
+   */
   export function ok(value: any, message?: string | Error): void
 
+  /**
+   * Throw an `AssertionError` unless `actual` and `expected` are loosely equal (`==`), with `NaN`
+   * treated as equal to `NaN`.
+   * @param actual - The value produced.
+   * @param expected - The value to compare `actual` against.
+   * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown
+   * directly instead of an `AssertionError`.
+   * @throws {AssertionError} thrown if the values are not loosely equal (unless `message` is an
+   * `Error` instance, which is thrown instead).
+   */
   export function equal(actual: any, expected: any, message?: string | Error): void
 
+  /**
+   * Throw an `AssertionError` unless `actual` and `expected` are loosely unequal (`!=`), with
+   * `NaN` treated as equal to `NaN`.
+   * @param actual - The value produced.
+   * @param expected - The value to compare `actual` against.
+   * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown
+   * directly instead of an `AssertionError`.
+   * @throws {AssertionError} thrown if the values are loosely equal (unless `message` is an
+   * `Error` instance, which is thrown instead).
+   */
   export function notEqual(actual: any, expected: any, message?: string | Error): void
 
+  /**
+   * Throw an `AssertionError` unless `actual` and `expected` are the same value according to
+   * `Object.is()`, which treats `NaN` as equal to `NaN` and `0` as distinct from `-0`.
+   * @param actual - The value produced.
+   * @param expected - The value to compare `actual` against.
+   * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown
+   * directly instead of an `AssertionError`.
+   * @throws {AssertionError} thrown if the values are not the same value (unless `message` is an
+   * `Error` instance, which is thrown instead).
+   */
   export function strictEqual(actual: any, expected: any, message?: string | Error): void
 
+  /**
+   * Throw an `AssertionError` unless `actual` and `expected` are different values according to
+   * `Object.is()`, which treats `NaN` as equal to `NaN` and `0` as distinct from `-0`.
+   * @param actual - The value produced.
+   * @param expected - The value to compare `actual` against.
+   * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown
+   * directly instead of an `AssertionError`.
+   * @throws {AssertionError} thrown if the values are the same value (unless `message` is an
+   * `Error` instance, which is thrown instead).
+   */
   export function notStrictEqual(actual: any, expected: any, message?: string | Error): void
 
+  /**
+   * Throw an `AssertionError` unless `actual` is a string that matches the `expected` regular
+   * expression.
+   * @param actual - The string to test.
+   * @param expected - The regular expression that `actual` must match.
+   * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown
+   * directly instead of an `AssertionError`.
+   * @throws {AssertionError} thrown if `actual` is not a string or does not match `expected`
+   * (unless `message` is an `Error` instance, which is thrown instead).
+   */
   export function match(actual: string, expected: RegExp, message?: string | Error): void
 
+  /**
+   * Throw an `AssertionError` unless `actual` is a string that does not match the `expected`
+   * regular expression.
+   * @param actual - The string to test.
+   * @param expected - The regular expression that `actual` must not match.
+   * @param message - Custom message for the thrown error; if an `Error` instance, it is thrown
+   * directly instead of an `AssertionError`.
+   * @throws {AssertionError} thrown if `actual` is not a string or matches `expected` (unless
+   * `message` is an `Error` instance, which is thrown instead).
+   */
   export function doesNotMatch(actual: string, expected: RegExp, message?: string | Error): void
 
+  /**
+   * Throw an `AssertionError` unless `actual` is `null` or `undefined`.
+   * @param actual - The value to assert is `null` or `undefined`.
+   * @throws {AssertionError} thrown if `actual` is neither `null` nor `undefined`, with the
+   * message `ifError got <actual>`.
+   */
   export function ifError(actual: any): void
 }