refactor: improve comment

Author: 0xClandestine

src/interfaces/IBLSSignatureChecker.sol

@@ -126,20 +126,28 @@ interface IBLSSignatureChecker is IBLSSignatureCheckerErrors, IBLSSignatureCheck
     /* VIEW */
 
     /*
-     * @notice Verifies aggregated BLS signatures and stake information for message hash `msgHash` across `quorumNumbers` at block `referenceBlockNumber`.
-     * @param msgHash The hash of the message that was signed.
+     * @notice This function is called by disperser when it has aggregated all the signatures of the operators
+     * that are part of the quorum for a particular taskNumber and is asserting them into onchain. The function
+     * checks that the claim for aggregated signatures are valid.
+     *
+     * The thesis of this procedure entails:
+     * 1. Getting the aggregated pubkey of all registered nodes at the time of pre-commit by the
+     * disperser (represented by apk in the parameters)
+     * 2. Subtracting the pubkeys of all non-signers (nonSignerPubkeys) and storing
+     * the output in apk to get aggregated pubkey of all operators that are part of quorum
+     * 3. Using this aggregated pubkey to verify the aggregated signature under BLS scheme
+     *
+     * @param msgHash The hash of the message that was signed. NOTE: Be careful to ensure msgHash is
+     * collision-resistant! This method does not hash msgHash in any way, so if an attacker is able
+     * to pass in an arbitrary value, they may be able to tamper with signature verification.
      * @param quorumNumbers The quorum numbers to verify signatures for, where each byte is an 8-bit integer.
-     * @param referenceBlockNumber The block number to use for stake information.
+     * @param referenceBlockNumber The block number at which the stake information is being verified
      * @param nonSignerStakesAndSignature Contains non-signer information and aggregated signature data.
-     * @return Stake totals for each quorum and a hash of the verification data.
-     * @dev The thesis of this procedure entails:
-     *      1. Getting the aggregated pubkey of all registered nodes at the time of pre-commit
-     *      2. Subtracting the pubkeys of all non-signers (nonSignerPubkeys)
-     *      3. Using the resulting aggregated pubkey to verify the aggregated signature under BLS scheme
-     * @dev Before signature verification, the function verifies:
-     *      1. The reference block number is valid and recent enough
-     *      2. Stake information is either most recent or latest before reference block
-     *      3. The aggregated signature is valid under the BLS scheme
+     * @return quorumStakeTotals The struct containing the total and signed stake for each quorum
+     * @return signatoryRecordHash The hash of the signatory record, which is used for fraud proofs
+     * @dev Before signature verification, the function verifies operator stake information. This includes
+     * ensuring that the provided referenceBlockNumber is valid and recent enough, and that the stake is
+     * either the most recent update for the total stake (of the operator) or latest before the referenceBlockNumber.
      */
     function checkSignatures(
         bytes32 msgHash,