docs: classes docstrings (#44)

* docs: add docstrings to classes

* Address @JoseLion feedback

* Add docstrings to TypeFactories.ts

* Add typeParam tags

Co-authored-by: Christian <[email protected]>

Author: ChristianSama

src/lib/ArrayAssertion.ts

@@ -6,6 +6,11 @@ import { UnsupportedOperationError } from "./errors/UnsupportedOperationError";
 import { expect } from "./expect";
 import { TypeFactory } from "./helpers/TypeFactories";
 
+/**
+ * Encapsulates assertion methods applicable to arrays.
+ *
+ * @param T the type of the array
+ */
 export class ArrayAssertion<T> extends Assertion<T[]> {
 
   public constructor(actual: T[]) {
@@ -270,6 +275,8 @@ export class ArrayAssertion<T> extends Assertion<T[]> {
    *   .toBePositive();
    * ```
    *
+   * @typeParam S the type of the factory's value
+   * @typeParam A the type of the assertion factory
    * @param index the index of the array to extract the value
    * @param typeFactory a factory to assert the extracted value type and create
    *                    an assertion for it

src/lib/Assertion.ts

@@ -22,6 +22,11 @@ export interface ExecuteOptions {
   invertedError: AssertionError;
 }
 
+/**
+ * Base class for all assertions.
+ *
+ * @param T the type of the `actual` value
+ */
 export class Assertion<T> {
 
   protected readonly actual: T;
@@ -329,6 +334,8 @@ export class Assertion<T> {
    *   .isValid();
    * ```
    *
+   * @typeParam S the type of the factory's value
+   * @typeParam A the type of the assertion factory
    * @param typeFactory a factory to assert the type and create an assertion
    * @returns a more specific assertion based on the factory type
    */

src/lib/BooleanAssertion.ts

@@ -2,6 +2,9 @@ import { AssertionError } from "assert";
 
 import { Assertion } from "./Assertion";
 
+/**
+ * Encapsulates assertion methods applicable to values of type boolean
+ */
 export class BooleanAssertion extends Assertion<boolean> {
 
   constructor(actual: boolean) {

src/lib/DateAssertion.ts

@@ -14,6 +14,9 @@ const DATE_METHOD_MAP: Record<keyof DateOptions, DateMethod> = {
   year: "getFullYear"
 };
 
+/**
+ * Encapsulates assertion methods applicable to values of type Date
+ */
 export class DateAssertion extends Assertion<Date> {
 
   constructor(actual: Date) {

src/lib/ErrorAssertion.ts

@@ -2,6 +2,11 @@ import { AssertionError } from "assert";
 
 import { Assertion } from "./Assertion";
 
+/**
+ * Encapsulates assertion methods applicable to Error instances.
+ *
+ * @param T the Error constructor type
+ */
 export class ErrorAssertion<T extends Error> extends Assertion<T> {
 
   public constructor(actual: T) {

src/lib/FunctionAssertion.ts

@@ -12,6 +12,11 @@ export interface Class<T> extends Function {
 
 const NoThrow = Symbol("NoThrow");
 
+/**
+ * Encapsulates assertion methods applicable to functions.
+ *
+ * @param T the type of the function's signature
+ */
 export class FunctionAssertion<T extends AnyFunction> extends Assertion<T> {
 
   constructor(actual: T) {
@@ -65,8 +70,9 @@ export class FunctionAssertion<T extends AnyFunction> extends Assertion<T> {
    *   .toHaveMessage("Something failed!");
    * ```
    *
-   * @param ErrorType optional error type constructor to check the thrown error
-   *                  against. If is not provided, it defaults to `Error`
+   * @typeParam E the type of the `Error`
+   * @param ExpectedType optional error type constructor to check the thrown error
+   *                  against. If is not provided, it defaults to {@link Error}
    * @returns a new {@link ErrorAssertion} to assert over the error
    */
   public toThrowError(): ErrorAssertion<Error>;
@@ -117,6 +123,8 @@ export class FunctionAssertion<T extends AnyFunction> extends Assertion<T> {
    *   .toBeNegative();
    * ```
    *
+   * @typeParam S the type of the factory's value
+   * @typeParam A the type of the assertion factory
    * @param expected the value the function is expected to throw
    * @param typeFactory optional type factory to perform more specific
    *                    assertions over the thrown value

src/lib/NumberAssertion.ts

@@ -30,6 +30,9 @@ export type BetweenOptions =
   | LowInclusiveBetweenOptions
   | HighInclusiveBetweenOptions;
 
+/**
+ * Encapsulates assertion methods applicable to values of type number
+ */
 export class NumberAssertion extends Assertion<number> {
 
   constructor(actual: number) {

src/lib/ObjectAssertion.ts

@@ -9,6 +9,11 @@ export type Entry<T, K = keyof T> = K extends keyof T
   ? [K, T[K]]
   : never;
 
+/**
+ * Encapsulates assertion methods applicable to objects.
+ *
+ * @param T the object's definition type
+ */
 export class ObjectAssertion<T extends JSObject> extends Assertion<T> {
 
   constructor(actual: T) {

src/lib/PromiseAssertion.ts

@@ -3,6 +3,12 @@ import { isDeepStrictEqual } from "util";
 
 import { Assertion } from "./Assertion";
 
+/**
+ * Encapsulates assertion methods applicable to Promises
+ *
+ * @param T the type of the value of the promise
+ * @param I type to track the current inverted state
+ */
 export class PromiseAssertion<T, I extends boolean = false> extends Assertion<Promise<T>> {
 
   // @ts-ignore:
@@ -139,6 +145,7 @@ export class PromiseAssertion<T, I extends boolean = false> extends Assertion<Pr
    * **Important:** Remember to return or `await` for this assertion to not leave
    * the promise asynchronous to the test
    *
+   * @typeParam E the type of the rejected value
    * @param expected the expected error to be rejected by the promise
    * @returns a promise with the caught error
    */

src/lib/StringAssertion.ts

@@ -2,6 +2,9 @@ import { AssertionError } from "assert";
 
 import { Assertion } from "./Assertion";
 
+/**
+ * Encapsulates assertion methods applicable to values of type string
+ */
 export class StringAssertion extends Assertion<string> {
 
   constructor(actual: string) {