docs: add function comments

Former-commit-id: 7ea0bc72d29f2682c0c6acad661ebbcf972c0d21 [formerly 539842223abf9b35e9c10d2f90fe33594686e163] [formerly b1b9df91ffbc3ddb367cf50d6ae1ab047b4c4f93 [formerly 7b0b3a5201]]
Former-commit-id: 11953adc92ba1d1178ddac82436ae3bb32fdfd24 [formerly 21ab78130e9aecd675d78f66c424de592c18ed5a]
Former-commit-id: 71898152c9e1e4191bb9846bb689380ea8a68d27

packages/identity/src/identity.ts

@@ -4,11 +4,17 @@ import { poseidon } from "circomlibjs"
 import { genIdentityFromMessage, genRandomIdentity, Strategy } from "./strategies"
 import { Fq, parseSerializedIdentity } from "./utils"
 
+// The secret type is used for the identity commitment generation.
 export enum SecretType {
   GENERIC, // Generic secret, composed of identityNullifier and identityTrapdoor.
-  MULTIPART_SECRET // Multipart secret, composed from multiple parts dependent on the spam threshold.
+  MULTIPART // Multipart secret, composed from multiple parts dependent on the spam threshold.
 }
 
+/**
+ * ZkIdentity is a class which can be used by protocols supported by the
+ * @zk-key/protocols package and it simplifies the management of
+ * identity-related witness parameters.
+ */
 export default class ZkIdentity {
   private _identityTrapdoor: bigint
   private _identityNullifier: bigint
@@ -18,10 +24,9 @@ export default class ZkIdentity {
   private _defaultMultipartSecret: bigint[] = []
 
   /**
-   * Generates new ZkIdentity.
-   * @param strategy strategy for identity generation.
-   * @param metadata additional data needed to create identity for given strategy.
-   * @returns
+   * Initializes the class attributes based on the strategy passed as parameter.
+   * @param strategy The strategy for identity generation.
+   * @param metadata Additional data needed to create identity for given strategy.
    */
   constructor(strategy: Strategy = Strategy.RANDOM, metadata?: string | SerializedIdentity) {
     switch (strategy) {
@@ -31,7 +36,7 @@ export default class ZkIdentity {
         this._identityTrapdoor = identityTrapdoor
         this._identityNullifier = identityNullifier
         this._secret = [this._identityNullifier, this._identityTrapdoor]
-        this._genMultipartSecret()
+        this._setMultipartSecret()
 
         break
       }
@@ -41,7 +46,7 @@ export default class ZkIdentity {
         this._identityTrapdoor = identityTrapdoor
         this._identityNullifier = identityNullifier
         this._secret = [this._identityNullifier, this._identityTrapdoor]
-        this._genMultipartSecret()
+        this._setMultipartSecret()
 
         break
       }
@@ -60,7 +65,7 @@ export default class ZkIdentity {
         this._identityTrapdoor = hexToBigint(identityTrapdoor)
         this._secret = secret.map((item) => hexToBigint(item))
         this._multipartSecret = multipartSecret.map((item) => hexToBigint(item))
-        this._defaultMultipartSecret = this._multipartSecret.slice(0, 2);
+        this._defaultMultipartSecret = this._multipartSecret.slice(0, 2)
 
         break
       }
@@ -70,24 +75,23 @@ export default class ZkIdentity {
   }
 
   /**
-   * Generate multipart secret. To be used by RLN related apps.
+   *  Sets the multipart secret attribute.
    */
-  private _genMultipartSecret(): void {
-
+  private _setMultipartSecret(): void {
     const initialComponent = Fq.pow(this._identityTrapdoor, this._identityNullifier)
 
     this._multipartSecret = [initialComponent]
 
-    for (let i = 1; i < 16; i+=1) {
+    for (let i = 1; i < 16; i += 1) {
       this._multipartSecret.push(Fq.pow(initialComponent, BigInt(i + 1)))
     }
 
-    this._defaultMultipartSecret = this._multipartSecret.slice(0, 2);
+    this._defaultMultipartSecret = this._multipartSecret.slice(0, 2)
   }
 
   /**
-   * Return the raw user identity, composed of identityNullifier and identityTrapdoor.
-   * @returns Identity
+   * Returns the raw user identity, composed of identityNullifier and identityTrapdoor.
+   * @returns The trapdoor and nullifier values.
    */
   public getIdentity(): Identity {
     return {
@@ -96,37 +100,61 @@ export default class ZkIdentity {
     }
   }
 
+  /**
+   * Returns the identity nullifier.
+   * @returns The identity nullifier.
+   */
   public getNullifier(): bigint {
     return this._identityNullifier
   }
 
+  /**
+   * Returns the secret.
+   * @returns The secret.
+   */
   public getSecret(): bigint[] {
     return this._secret
   }
 
+  /**
+   * Returns the default multipart secret or a portion of the multipart secret.
+   * @param secretParts The number of the secret parts.
+   * @returns The multipart secret.
+   */
   public getMultipartSecret(secretParts: number = 2): bigint[] {
-    return secretParts === 2 ? this._defaultMultipartSecret : this._multipartSecret.slice(0, secretParts);
+    return secretParts === 2 ? this._defaultMultipartSecret : this._multipartSecret.slice(0, secretParts)
   }
 
+  /**
+   * Returns the Poseidon hash of the secret.
+   * @returns The hash of the secret.
+   */
   public getSecretHash(): bigint {
     return poseidon(this._secret)
   }
 
+  /**
+   * Returns the Poseidon hash of the multipart secret.
+   * @param secretParts The number of the secret parts.
+   * @returns The hash of the multipart secret.
+   */
   public getMultipartSecretHash(secretParts: number = 2): bigint {
-    const multipartSecret = this.getMultipartSecret(secretParts);
+    const multipartSecret = this.getMultipartSecret(secretParts)
+
     return poseidon(multipartSecret)
   }
 
   /**
-   * Generate commitment from secret
+   * Generates the identity commitment from the secret or the multipart secret.
    * @param secretType The secret type for which to generate identity commitment
+   * @param secretParts The number of the secret parts.
    * @returns identity commitment
    */
   public genIdentityCommitment(secretType: SecretType = SecretType.GENERIC, secretParts: number = 2): bigint {
     switch (secretType) {
       case SecretType.GENERIC:
         return poseidon([this.getSecretHash()])
-      case SecretType.MULTIPART_SECRET:
+      case SecretType.MULTIPART:
         return poseidon([this.getMultipartSecretHash(secretParts)])
       default:
         throw new Error("Provided secret type is not supported")
@@ -134,8 +162,8 @@ export default class ZkIdentity {
   }
 
   /**
-   * Serializes the `identityNullifier`, `identityTrapdoor` and `secret` from the identity
-   * @returns stringified serialized identity
+   * Serializes the class attributes and returns a stringified object.
+   * @returns The stringified serialized identity.
    */
   public serializeIdentity(): string {
     const data: SerializedIdentity = {