docs: add inline doc comments to all public contract functions

contracts/commitment-pool/src/lib.rs

@@ -25,7 +25,22 @@ pub struct CommitmentPool;
 
 #[contractimpl]
 impl CommitmentPool {
-    /// Initialize the commitment pool with admin, token, and verifier contract addresses.
+    /// Initializes the commitment pool with admin, token, and verifier contract addresses.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `admin` - The address of the contract administrator.
+    /// * `token_id` - The address of the underlying token contract.
+    /// * `verifier_id` - The address of the Groth16 verifier contract.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` on successful initialization.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Error::Unauthorized` if the contract is already initialized.
     pub fn initialize(
         env: Env,
         admin: Address,
@@ -43,10 +58,25 @@ impl CommitmentPool {
         Ok(())
     }
 
-    /// Deposit a commitment into the shielded pool.
+    /// Deposits a commitment into the shielded pool.
     ///
     /// The commitment is a hash of (secret, nullifier, amount, token).
-    /// The encrypted_note allows the recipient to decrypt the note details.
+    /// The encrypted_note allows the recipient to decrypt the note details off-chain.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `commitment` - A 32-byte hash representing the user's deposit commitment.
+    /// * `encrypted_note` - The encrypted details of the deposit for the recipient.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` on a successful deposit.
+    ///
+    /// # Errors
+    ///
+    /// * Returns `Error::ContractPaused` if the contract is currently paused.
+    /// * Returns `Error::DuplicateCommitment` if the commitment already exists in the tree.
     pub fn deposit(
         env: Env,
         commitment: BytesN<32>,
@@ -71,10 +101,28 @@ impl CommitmentPool {
         Ok(())
     }
 
-    /// Withdraw from the pool by providing a valid ZK proof.
+    /// Withdraws tokens from the pool by providing a valid ZK proof.
     ///
     /// The proof demonstrates knowledge of a valid commitment in the Merkle tree
     /// without revealing which commitment is being spent.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `nullifier` - A unique 32-byte hash derived from the secret to prevent double-spending.
+    /// * `proof` - The serialized ZK proof proving ownership of a commitment.
+    /// * `recipient` - The address that will receive the withdrawn tokens.
+    /// * `amount` - The amount of tokens to withdraw.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` on a successful withdrawal.
+    ///
+    /// # Errors
+    ///
+    /// * Returns `Error::ContractPaused` if the contract is currently paused.
+    /// * Returns `Error::NullifierAlreadySpent` if the nullifier has been seen before.
+    /// * Returns `Error::InvalidProof` if the proof verification fails.
     pub fn withdraw(
         env: Env,
         nullifier: BytesN<32>,
@@ -131,16 +179,47 @@ impl CommitmentPool {
     }
 
     /// Returns the current Merkle root of the commitment tree.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    ///
+    /// # Returns
+    ///
+    /// Returns a 32-byte array representing the current Merkle root.
     pub fn get_root(env: Env) -> BytesN<32> {
         MerkleTree::root(&env)
     }
 
     /// Checks whether a nullifier has already been spent.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `nullifier` - The 32-byte nullifier hash to check.
+    ///
+    /// # Returns
+    ///
+    /// Returns `true` if the nullifier has been spent, otherwise `false`.
     pub fn is_nullifier_spent(env: Env, nullifier: BytesN<32>) -> bool {
         NullifierSet::is_spent(&env, &nullifier)
     }
 
-    /// Pause the contract. Only the admin can call this.
+    /// Pauses the contract, suspending deposits and withdrawals.
+    ///
+    /// Only the contract administrator can call this function.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` upon successfully pausing the contract.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Error::Unauthorized` if the caller is not the admin.
     pub fn pause(env: Env) -> Result<(), Error> {
         let admin: Address = env.storage().instance()
             .get(&DataKey::Admin).ok_or(Error::Unauthorized)?;
@@ -150,7 +229,21 @@ impl CommitmentPool {
         Ok(())
     }
 
-    /// Unpause the contract. Only the admin can call this.
+    /// Unpauses the contract, resuming deposits and withdrawals.
+    ///
+    /// Only the contract administrator can call this function.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` upon successfully unpausing the contract.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Error::Unauthorized` if the caller is not the admin.
     pub fn unpause(env: Env) -> Result<(), Error> {
         let admin: Address = env.storage().instance()
             .get(&DataKey::Admin).ok_or(Error::Unauthorized)?;

contracts/compliance-registry/src/lib.rs

@@ -22,7 +22,20 @@ pub struct ComplianceRegistry;
 
 #[contractimpl]
 impl ComplianceRegistry {
-    /// Initialize the registry with an admin address.
+    /// Initializes the registry with an admin address.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `admin` - The address of the contract administrator.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` on successful initialization.
+    ///
+    /// # Errors
+    ///
+    /// Returns `ComplianceError::Unauthorized` if the contract is already initialized.
     pub fn initialize(env: Env, admin: Address) -> Result<(), ComplianceError> {
         if env.storage().instance().has(&RegistryKey::Admin) {
             return Err(ComplianceError::Unauthorized);
@@ -32,7 +45,20 @@ impl ComplianceRegistry {
         Ok(())
     }
 
-    /// Set the auditor address. Only admin can call this.
+    /// Sets the auditor address. Only the admin can call this function.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `auditor` - The address of the designated auditor.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` upon successful update of the auditor address.
+    ///
+    /// # Errors
+    ///
+    /// Returns `ComplianceError::Unauthorized` if the caller is not the admin.
     pub fn set_auditor(env: Env, auditor: Address) -> Result<(), ComplianceError> {
         let admin: Address = env.storage().instance()
             .get(&RegistryKey::Admin).ok_or(ComplianceError::Unauthorized)?;
@@ -41,10 +67,24 @@ impl ComplianceRegistry {
         Ok(())
     }
 
-    /// Register an encrypted viewing key for a commitment.
+    /// Registers an encrypted viewing key for a commitment.
     ///
     /// The viewing key is encrypted with the auditor's public key,
     /// allowing only the auditor to decrypt transaction details.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `commitment` - The 32-byte hash of the commitment.
+    /// * `encrypted_key` - The encrypted viewing key.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` upon successful registration.
+    ///
+    /// # Errors
+    ///
+    /// Returns `ComplianceError::AlreadyRegistered` if a key is already registered for this commitment.
     pub fn register_viewing_key(
         env: Env,
         commitment: BytesN<32>,
@@ -58,8 +98,23 @@ impl ComplianceRegistry {
         Ok(())
     }
 
-    /// Get the encrypted viewing key for a commitment.
+    /// Gets the encrypted viewing key for a commitment.
+    /// 
     /// Only the auditor can retrieve viewing keys.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `commitment` - The 32-byte hash of the commitment.
+    ///
+    /// # Returns
+    ///
+    /// Returns the encrypted viewing key as `Bytes`.
+    ///
+    /// # Errors
+    ///
+    /// * Returns `ComplianceError::NotAuditor` if the caller is not the registered auditor.
+    /// * Returns `ComplianceError::NotFound` if no viewing key exists for the given commitment.
     pub fn get_viewing_key(
         env: Env,
         commitment: BytesN<32>,

contracts/groth16-verifier/src/lib.rs

@@ -50,7 +50,20 @@ pub struct Groth16Verifier;
 
 #[contractimpl]
 impl Groth16Verifier {
-    /// Initialize the verifier with an admin address.
+    /// Initializes the verifier with an admin address.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `admin` - The address of the contract administrator.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` on successful initialization.
+    ///
+    /// # Errors
+    ///
+    /// Returns `VerifierError::Unauthorized` if the contract is already initialized.
     pub fn initialize(env: Env, admin: Address) -> Result<(), VerifierError> {
         if env.storage().instance().has(&VkKey::Admin) {
             return Err(VerifierError::Unauthorized);
@@ -60,9 +73,23 @@ impl Groth16Verifier {
         Ok(())
     }
 
-    /// Register a verification key by storing its serialized form.
+    /// Registers a verification key by storing its serialized form.
     ///
     /// Only the admin can register verification keys.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `vk_hash` - The 32-byte hash of the verification key.
+    /// * `vk_data` - The serialized verification key data.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` upon successful registration.
+    ///
+    /// # Errors
+    ///
+    /// Returns `VerifierError::Unauthorized` if the caller is not the admin.
     pub fn register_vk(
         env: Env,
         vk_hash: BytesN<32>,
@@ -81,22 +108,40 @@ impl Groth16Verifier {
         Ok(())
     }
 
-    /// Check if a verification key is registered.
+    /// Checks if a verification key is registered.
+    ///
+    /// # Arguments
+    ///
+    /// * `env` - The execution environment.
+    /// * `vk_hash` - The 32-byte hash of the verification key to check.
+    ///
+    /// # Returns
+    ///
+    /// Returns `true` if the verification key is registered, otherwise `false`.
     pub fn is_vk_registered(env: Env, vk_hash: BytesN<32>) -> bool {
         env.storage()
             .persistent()
             .has(&VkKey::Vk(vk_hash))
     }
 
-    /// Verify a Groth16 proof against registered verification key.
+    /// Verifies a Groth16 proof against a registered verification key.
     ///
     /// # Arguments
-    /// * `proof` - Serialized proof bytes (A, B, C points)
-    /// * `public_inputs` - Vector of 32-byte public input scalars
-    /// * `vk_hash` - Hash of the verification key to use
+    ///
+    /// * `env` - The execution environment.
+    /// * `proof` - Serialized proof bytes (A, B, C points).
+    /// * `public_inputs` - Vector of 32-byte public input scalars.
+    /// * `vk_hash` - Hash of the verification key to use.
     ///
     /// # Returns
-    /// `true` if the proof is valid, `false` otherwise
+    ///
+    /// Returns `Ok(true)` if the proof is valid, `Ok(false)` if invalid.
+    ///
+    /// # Errors
+    ///
+    /// * Returns `VerifierError::VkNotRegistered` if the given `vk_hash` is not found.
+    /// * Returns `VerifierError::InvalidProofFormat` if the proof length is incorrect.
+    /// * Returns `VerifierError::InvalidPublicInputs` if the public inputs vector is empty.
     pub fn verify(
         env: Env,
         proof: Bytes,