docs: natspec updates (#521)

**Motivation:**

*Explain here the context, and why you're making that change. What is
the problem you're trying to solve.*

**Modifications:**

*Describe the modifications you've done.*

**Result:**

*After your change, what will change.*

Author: eigenmikem

src/interfaces/IBN254TableCalculator.sol

@@ -9,19 +9,21 @@ import {
 
 interface IBN254TableCalculator is IOperatorTableCalculator, IOperatorTableCalculatorTypes {
     /**
-     * @notice calculates the operatorInfos for a given operatorSet
-     * @param operatorSet the operatorSet to calculate the operator table for
-     * @return operatorSetInfo the operatorSetInfo for the given operatorSet
+     * @notice Calculates the BN254 operator table info for a given operatorSet
+     * @param operatorSet The operatorSet to calculate the operator table for
+     * @return operatorSetInfo The BN254OperatorSetInfo containing merkle root, aggregate pubkey, and total weights
      * @dev The output of this function is used by the multichain protocol to transport operator stake weights to destination chains
+     * @dev This function aggregates operator weights, creates a merkle tree of operator info, and calculates the aggregate BN254 public key
      */
     function calculateOperatorTable(
         OperatorSet calldata operatorSet
     ) external view returns (BN254OperatorSetInfo memory operatorSetInfo);
 
     /**
-     * @notice Get the operatorInfos for a given operatorSet
-     * @param operatorSet the operatorSet to get the operatorInfos for
-     * @return operatorInfos the operatorInfos for the given operatorSet
+     * @notice Get the individual operator infos for a given operatorSet
+     * @param operatorSet The operatorSet to get the operatorInfos for
+     * @return operatorInfos The array of BN254OperatorInfo structs containing pubkeys and weights for registered operators
+     * @dev Only returns operators that have registered their BN254 keys with the KeyRegistrar
      */
     function getOperatorInfos(
         OperatorSet calldata operatorSet

src/interfaces/IECDSATableCalculator.sol

@@ -9,10 +9,11 @@ import {
 
 interface IECDSATableCalculator is IOperatorTableCalculator, IOperatorTableCalculatorTypes {
     /**
-     * @notice calculates the operatorInfos for a given operatorSet
-     * @param operatorSet the operatorSet to calculate the operator table for
-     * @return operatorInfos the list of operatorInfos for the given operatorSet
+     * @notice Calculates the ECDSA operator infos for a given operatorSet
+     * @param operatorSet The operatorSet to calculate the operator table for
+     * @return operatorInfos The array of ECDSAOperatorInfo structs containing ECDSA addresses and weights for registered operators
      * @dev The output of this function is used by the multichain protocol to transport operator stake weights to destination chains
+     * @dev Only returns operators that have registered their ECDSA keys with the KeyRegistrar and have non-zero stake
      */
     function calculateOperatorTable(
         OperatorSet calldata operatorSet

src/middlewareV2/tableCalculator/BN254TableCalculator.sol

@@ -21,6 +21,13 @@ contract BN254TableCalculator is BN254TableCalculatorBase {
     /// @notice The default lookahead blocks for the slashable stake lookup
     uint256 public immutable LOOKAHEAD_BLOCKS;
 
+    /**
+     * @notice Constructor to initialize the BN254TableCalculator
+     * @param _keyRegistrar The KeyRegistrar contract for managing operator BN254 keys
+     * @param _allocationManager The AllocationManager contract for operator allocations and slashable stake
+     * @param _LOOKAHEAD_BLOCKS The number of blocks to look ahead when calculating minimum slashable stake
+     * @dev The lookahead blocks parameter helps ensure stake calculations account for future slashing events
+     */
     constructor(
         IKeyRegistrar _keyRegistrar,
         IAllocationManager _allocationManager,
@@ -31,11 +38,14 @@ contract BN254TableCalculator is BN254TableCalculatorBase {
     }
 
     /**
-     * @notice Get the operator weights for a given operatorSet based on the slashable stake.
+     * @notice Get the operator weights for a given operatorSet based on the minimum slashable stake.
      * @param operatorSet The operatorSet to get the weights for
-     * @return operators The addresses of the operators in the operatorSet
+     * @return operators The addresses of the operators in the operatorSet with non-zero slashable stake
      * @return weights The weights for each operator in the operatorSet, this is a 2D array where the first index is the operator
      * and the second index is the type of weight. In this case its of length 1 and returns the slashable stake for the operatorSet.
+     * @dev This implementation sums the minimum slashable stake across all strategies for each operator
+     * @dev Only includes operators with non-zero total slashable stake to optimize gas usage
+     * @dev The weights array contains only one element per operator representing their total slashable stake
      */
     function _getOperatorWeights(
         OperatorSet calldata operatorSet

src/middlewareV2/tableCalculator/BN254TableCalculatorBase.sol

@@ -23,6 +23,10 @@ abstract contract BN254TableCalculatorBase is IBN254TableCalculator {
     /// @notice KeyRegistrar contract for managing operator keys
     IKeyRegistrar public immutable keyRegistrar;
 
+    /**
+     * @notice Constructor to initialize the BN254TableCalculatorBase
+     * @param _keyRegistrar The KeyRegistrar contract for managing operator BN254 public keys
+     */
     constructor(
         IKeyRegistrar _keyRegistrar
     ) {
@@ -68,6 +72,9 @@ abstract contract BN254TableCalculatorBase is IBN254TableCalculator {
     }
 
     /// @inheritdoc IBN254TableCalculator
+    /**
+     * @dev Only returns operators that have registered their BN254 keys with the KeyRegistrar
+     */
     function getOperatorInfos(
         OperatorSet calldata operatorSet
     ) external view virtual returns (BN254OperatorInfo[] memory) {
@@ -109,13 +116,14 @@ abstract contract BN254TableCalculatorBase is IBN254TableCalculator {
     /**
      * @notice Calculates the operator table for a given operatorSet, also calculates the aggregate pubkey for the operatorSet
      * @param operatorSet The operatorSet to calculate the operator table for
-     * @return operatorSetInfo The operator table for the given operatorSet
+     * @return operatorSetInfo The BN254OperatorSetInfo containing merkle root, operator count, aggregate pubkey, and total weights
      * @dev This function:
      * 1. Gets operator weights from the weight calculator
      * 2. Collates weights into total weights
      * 3. Creates a merkle tree of operator info
      *    - assumes that the operator has a registered BN254 key
      * 4. Calculates the aggregate public key
+     * @dev Returns empty operator set info if no operators have registered keys or non-zero weights
      */
     function _calculateOperatorTable(
         OperatorSet calldata operatorSet

src/middlewareV2/tableCalculator/ECDSATableCalculator.sol

@@ -21,6 +21,13 @@ contract ECDSATableCalculator is ECDSATableCalculatorBase {
     /// @notice The default lookahead blocks for the slashable stake lookup
     uint256 public immutable LOOKAHEAD_BLOCKS;
 
+    /**
+     * @notice Constructor to initialize the ECDSATableCalculator
+     * @param _keyRegistrar The KeyRegistrar contract for managing operator ECDSA keys
+     * @param _allocationManager The AllocationManager contract for operator allocations and slashable stake
+     * @param _LOOKAHEAD_BLOCKS The number of blocks to look ahead when calculating minimum slashable stake
+     * @dev The lookahead blocks parameter helps ensure stake calculations account for future slashing events
+     */
     constructor(
         IKeyRegistrar _keyRegistrar,
         IAllocationManager _allocationManager,
@@ -31,11 +38,14 @@ contract ECDSATableCalculator is ECDSATableCalculatorBase {
     }
 
     /**
-     * @notice Get the operator weights for a given operatorSet based on the slashable stake.
+     * @notice Get the operator weights for a given operatorSet based on the minimum slashable stake.
      * @param operatorSet The operatorSet to get the weights for
-     * @return operators The addresses of the operators in the operatorSet
+     * @return operators The addresses of the operators in the operatorSet with non-zero slashable stake
      * @return weights The weights for each operator in the operatorSet, this is a 2D array where the first index is the operator
      * and the second index is the type of weight. In this case it's of length 1 and returns the slashable stake for the operatorSet.
+     * @dev This implementation sums the minimum slashable stake across all strategies for each operator
+     * @dev Only includes operators with non-zero total slashable stake to optimize gas usage
+     * @dev The weights array contains only one element per operator representing their total slashable stake
      */
     function _getOperatorWeights(
         OperatorSet calldata operatorSet

src/middlewareV2/tableCalculator/ECDSATableCalculatorBase.sol

@@ -21,13 +21,20 @@ abstract contract ECDSATableCalculatorBase is IECDSATableCalculator {
     /// @notice KeyRegistrar contract for managing operator keys
     IKeyRegistrar public immutable keyRegistrar;
 
+    /**
+     * @notice Constructor to initialize the ECDSATableCalculatorBase
+     * @param _keyRegistrar The KeyRegistrar contract for managing operator ECDSA public keys
+     */
     constructor(
         IKeyRegistrar _keyRegistrar
     ) {
         keyRegistrar = _keyRegistrar;
     }
 
     /// @inheritdoc IECDSATableCalculator
+    /**
+     * @dev Only returns operators that have registered their ECDSA keys with the KeyRegistrar and have non-zero stake
+     */
     function calculateOperatorTable(
         OperatorSet calldata operatorSet
     ) external view virtual returns (ECDSAOperatorInfo[] memory operatorInfos) {
@@ -84,10 +91,11 @@ abstract contract ECDSATableCalculatorBase is IECDSATableCalculator {
     /**
      * @notice Calculates the operator table for a given operatorSet
      * @param operatorSet The operatorSet to calculate the operator table for
-     * @return operatorInfos The operator table for the given operatorSet
+     * @return operatorInfos The array of ECDSAOperatorInfo structs for operators with registered ECDSA keys
      * @dev This function:
      * 1. Gets operator weights from the weight calculator
      * 2. Creates ECDSAOperatorInfo structs for each operator with registered ECDSA keys
+     * @dev Returns empty array if no operators have registered keys or non-zero weights
      */
     function _calculateOperatorTable(
         OperatorSet calldata operatorSet