docs: improved and finalized jsdocs in exported functions (#74)

Author: onmax

src/crypto/sha256.ts

@@ -32,6 +32,9 @@ const W: number[] = [];
 export class SHA256 extends Hasher {
   _hash = new WordArray([...H]);
 
+  /**
+   * Resets the internal state of the hash object to initial values.
+   */
   reset() {
     super.reset();
     this._hash = new WordArray([...H]);
@@ -107,6 +110,12 @@ export class SHA256 extends Hasher {
     H[7] = (H[7] + h) | 0;
   }
 
+  /**
+   * Finishes the hash calculation and returns the hash as a WordArray.
+   *
+   * @param {string} messageUpdate - Additional message content to include in the hash.
+   * @returns {WordArray} The finalised hash as a WordArray.
+   */
   finalize(messageUpdate: string): WordArray {
     super.finalize(messageUpdate);
 
@@ -129,10 +138,22 @@ export class SHA256 extends Hasher {
   }
 }
 
+/**
+ * Calculates the SHA-256 hash of the message provided.
+ *
+ * @param {string} message - The message to hash.
+ * @returns {string} The message hash as a hexadecimal string.
+ */
 export function sha256(message: string) {
   return new SHA256().finalize(message).toString();
 }
 
+/**
+ * Calculates the SHA-256 hash of the given message and encodes it in Base64.
+ *
+ * @param {string} message - The message to hash.
+ * @returns {string} The base64 encoded hash of the message.
+ */
 export function sha256base64(message: string) {
   return new SHA256().finalize(message).toString(Base64);
 }

src/diff.ts

@@ -1,5 +1,13 @@
 import { objectHash, HashOptions } from "./object-hash";
 
+/**
+ * Calculates the difference between two objects and returns a list of differences.
+ *
+ * @param {any} obj1 - The first object to compare.
+ * @param {any} obj2 - The second object to compare.
+ * @param {HashOptions} [opts={}] - Configuration options for hashing the objects. See {@link HashOptions}.
+ * @returns {DiffEntry[]} An array with the differences between the two objects.
+ */
 export function diff(
   obj1: any,
   obj2: any,

src/hash.ts

@@ -4,7 +4,7 @@ import { sha256base64 } from "./crypto/sha256";
 /**
  * Hash any JS value into a string
  * @param {object} object value to hash
- * @param {HashOptions} options hashing options
+ * @param {HashOptions} options hashing options. See {@link HashOptions}.
  * @return {string} hash value
  * @api public
  */

src/object-hash.ts

@@ -2,43 +2,73 @@
 
 export interface HashOptions {
   /**
-   *
+   * Function to determine if a key should be excluded from hashing.
+   * @optional
+   * @param key - The key to check for exclusion.
+   * @returns {boolean} - Returns true to exclude the key from hashing.
    */
   excludeKeys?: ((key: string) => boolean) | undefined;
+
   /**
-   * hash object keys, values ignored
+   * Specifies whether to exclude values from hashing, so that only the object keys are hashed.
+   * @optional
    */
   excludeValues?: boolean | undefined;
+
   /**
-   * ignore unknown object types
+   * Specifies whether to ignore objects of unknown type (not directly serialisable) when hashing.
+   * @optional
+   * @default false
    */
   ignoreUnknown?: boolean | undefined;
+
   /**
-   * optional function that replaces values before hashing
+   * A function that replaces values before they are hashed, which can be used to customise the hashing process.
+   * @optional
+   * @param value - The current value to be hashed.
+   * @returns {any} - The value to use for hashing instead.
    */
   replacer?: ((value: any) => any) | undefined;
+
   /**
-   * consider 'name' property of functions for hashing
+   * Specifies whether the 'name' property of functions should be taken into account when hashing.
+   * @optional
+   * @default false
    */
   respectFunctionNames?: boolean | undefined;
+
   /**
-   * consider function properties when hashing
+   * Specifies whether properties of functions should be taken into account when hashing.
+   * @optional
+   * @default false
    */
   respectFunctionProperties?: boolean | undefined;
+
   /**
-   * Respect special properties (prototype, letructor) when hashing to distinguish between types
+   * Specifies whether to include type-specific properties such as prototype or constructor in the hash to distinguish between types.
+   * @optional
+   * @default false
    */
   respectType?: boolean | undefined;
+
   /**
-   * Sort all arrays before hashing
+   * Specifies whether arrays should be sorted before hashing to ensure consistent order.
+   * @optional
+   * @default false
    */
   unorderedArrays?: boolean | undefined;
+
   /**
-   * Sort `Set` and `Map` instances before hashing
+   * Specifies whether Set and Map instances should be sorted by key before hashing to ensure consistent order.
+   * @optional
+   * @default true
    */
   unorderedObjects?: boolean | undefined;
+
   /**
-   * Sort `Set` and `Map` instances before hashing
+   * Specifies whether the elements of `Set' and keys of `Map' should be sorted before hashing to ensure consistent order.
+   * @optional
+   * @default false
    */
   unorderedSets?: boolean | undefined;
 }
@@ -60,7 +90,7 @@ const defaults: HashOptions = Object.freeze({
 /**
  * Serialize any JS value into a stable, hashable string
  * @param {object} object value to hash
- * @param {HashOptions} options hashing options
+ * @param {HashOptions} options hashing options. See {@link HashOptions}.
  * @return {string} serialized value
  * @api public
  */

src/utils.ts

@@ -3,7 +3,7 @@ import { objectHash, HashOptions } from "./object-hash";
  * Compare two objects using reference equality and stable deep hashing.
  * @param {any} object1 First object
  * @param {any} object2 Second object
- * @param {HashOptions} hash options
+ * @param {HashOptions} hashOptions. Configuration options for hashing the objects. See {@link HashOptions}.
  * @return {boolean} true if equal and false if not
  * @api public
  */