feat: add code comments to lp registry contracts

src/interfaces/ILPRegistry.sol

@@ -3,21 +3,30 @@
 
 pragma solidity ^0.8.20;
 
+/**
+ * @title ILPRegistry
+ * @dev Interface for the Liquidity Provider (LP) Registry contract.
+ *      This interface defines the events, errors, and function signatures
+ *      for managing LPs, pools, and their associated liquidity.
+ */
 interface ILPRegistry {
+    // Events
     event LPRegistered(address indexed pool, address indexed lp, uint256 liquidityAmount);
     event LPRemoved(address indexed pool, address indexed lp);
     event PoolAdded(address indexed pool);
     event PoolRemoved(address indexed pool);
     event LiquidityIncreased(address indexed pool, address indexed lp, uint256 amount);
     event LiquidityDecreased(address indexed pool, address indexed lp, uint256 amount);
 
-    error NotAuthorized();
-    error PoolNotFound();
-    error AlreadyRegistered();
-    error NotRegistered();
-    error InsufficientLiquidity();
-    error InvalidAmount();
+    // Errors
+    error NotAuthorized(); // Thrown when an unauthorized action is attempted.
+    error PoolNotFound();  // Thrown when a pool is not found in the registry.
+    error AlreadyRegistered(); // Thrown when an LP or pool is already registered.
+    error NotRegistered(); // Thrown when an LP is not registered for a specific pool.
+    error InsufficientLiquidity(); // Thrown when liquidity is insufficient for an operation.
+    error InvalidAmount(); // Thrown when an invalid liquidity amount is provided.
 
+    // Function signatures
     function registerLP(address pool, address lp, uint256 liquidityAmount) external;
     function removeLP(address pool, address lp) external;
     function addPool(address pool) external;

src/protocol/LPRegistry.sol

@@ -6,42 +6,87 @@ pragma solidity ^0.8.20;
 import "../interfaces/ILPRegistry.sol";
 import "openzeppelin-contracts/contracts/access/Ownable.sol";
 
+/**
+ * @title LPRegistry
+ * @dev Implementation of the ILPRegistry interface.
+ *      Manages the registration of liquidity providers (LPs), pools, and their associated liquidity.
+ *      Restricted to owner-controlled operations for pool and LP management.
+ */
 contract LPRegistry is ILPRegistry, Ownable {
+    // Mapping to track valid pools
     mapping(address => bool) public validPools;
+
+    // Nested mapping to track registered LPs for each pool
     mapping(address => mapping(address => bool)) public poolLPs;
-    mapping(address => uint256) public poolLPCount;
 
-    // State variables for liquidity amounts
+    // Tracks the number of LPs registered for each pool
+    mapping(address => uint256) public poolLPCount;
+
+    // Mapping to store liquidity amounts per LP for each pool
     mapping(address => mapping(address => uint256)) public lpLiquidityAmount;
+
+    // Tracks total liquidity for each pool
     mapping(address => uint256) public totalLPLiquidity;
 
+    /**
+     * @dev Initializes the contract, setting the deployer as the initial owner.
+     */
     constructor() Ownable(msg.sender) {}
 
+    /**
+     * @dev Modifier to ensure a pool is valid.
+     * @param pool The address of the pool to check.
+     */
     modifier onlyValidPool(address pool) {
         if (!validPools[pool]) revert PoolNotFound();
         _;
     }
 
+    /**
+     * @dev Modifier to ensure an LP is registered for a given pool.
+     * @param pool The address of the pool.
+     * @param lp The address of the LP.
+     */
     modifier onlyRegisteredLP(address pool, address lp) {
         if (!poolLPs[pool][lp]) revert NotRegistered();
         _;
     }
 
+    /**
+     * @notice Adds a new pool to the registry.
+     * @param pool The address of the pool to add.
+     * @dev Only callable by the contract owner.
+     */
     function addPool(address pool) external onlyOwner {
         if (validPools[pool]) revert AlreadyRegistered();
         validPools[pool] = true;
         emit PoolAdded(pool);
     }
 
+    /**
+     * @notice Removes a pool from the registry.
+     * @param pool The address of the pool to remove.
+     * @dev Only callable by the contract owner. Pool must have no active liquidity.
+     */
     function removePool(address pool) external onlyOwner {
         if (!validPools[pool]) revert PoolNotFound();
-        // Only allow removal if no liquidity remains
         if (totalLPLiquidity[pool] > 0) revert("Pool has active liquidity");
         validPools[pool] = false;
         emit PoolRemoved(pool);
     }
 
-    function registerLP(address pool, address lp, uint256 liquidityAmount) external onlyOwner onlyValidPool(pool) {
+    /**
+     * @notice Registers an LP for a pool with an initial liquidity amount.
+     * @param pool The address of the pool.
+     * @param lp The address of the LP.
+     * @param liquidityAmount The initial liquidity amount.
+     * @dev Only callable by the contract owner. Pool must be valid.
+     */
+    function registerLP(address pool, address lp, uint256 liquidityAmount) 
+        external 
+        onlyOwner 
+        onlyValidPool(pool) 
+    {
         if (poolLPs[pool][lp]) revert AlreadyRegistered();
         if (liquidityAmount == 0) revert InvalidAmount();
 
@@ -53,25 +98,55 @@ contract LPRegistry is ILPRegistry, Ownable {
         emit LPRegistered(pool, lp, liquidityAmount);
     }
 
-    function removeLP(address pool, address lp) external onlyOwner onlyValidPool(pool) onlyRegisteredLP(pool, lp) {
-        // Only allow removal if no liquidity remains
+    /**
+     * @notice Removes an LP from a pool.
+     * @param pool The address of the pool.
+     * @param lp The address of the LP.
+     * @dev Only callable by the contract owner. LP must have no active liquidity.
+     */
+    function removeLP(address pool, address lp) 
+        external 
+        onlyOwner 
+        onlyValidPool(pool) 
+        onlyRegisteredLP(pool, lp) 
+    {
         if (lpLiquidityAmount[pool][lp] > 0) revert("LP has active liquidity");
 
         poolLPs[pool][lp] = false;
         poolLPCount[pool]--;
         emit LPRemoved(pool, lp);
     }
 
-    function increaseLiquidity(address pool, uint256 amount) external onlyValidPool(pool) onlyRegisteredLP(pool, msg.sender) {
+    /**
+     * @notice Increases the liquidity for an LP in a pool.
+     * @param pool The address of the pool.
+     * @param amount The amount of liquidity to add.
+     * @dev Only callable by the LP itself.
+     */
+    function increaseLiquidity(address pool, uint256 amount) 
+        external 
+        onlyValidPool(pool) 
+        onlyRegisteredLP(pool, msg.sender) 
+    {
         if (amount == 0) revert InvalidAmount();
 
         lpLiquidityAmount[pool][msg.sender] += amount;
         totalLPLiquidity[pool] += amount;
 
-        emit LiquidityIncreased(pool, msg.sender, lpLiquidityAmount[pool][msg.sender]);
+        emit LiquidityIncreased(pool, msg.sender, amount);
     }
 
-    function decreaseLiquidity(address pool, uint256 amount) external onlyValidPool(pool) onlyRegisteredLP(pool, msg.sender) {
+    /**
+     * @notice Decreases the liquidity for an LP in a pool.
+     * @param pool The address of the pool.
+     * @param amount The amount of liquidity to remove.
+     * @dev Only callable by the LP itself. Cannot remove more liquidity than available.
+     */
+    function decreaseLiquidity(address pool, uint256 amount) 
+        external 
+        onlyValidPool(pool) 
+        onlyRegisteredLP(pool, msg.sender) 
+    {
         if (amount == 0) revert InvalidAmount();
         if (amount > lpLiquidityAmount[pool][msg.sender]) revert InsufficientLiquidity();
 
@@ -81,22 +156,49 @@ contract LPRegistry is ILPRegistry, Ownable {
         emit LiquidityDecreased(pool, msg.sender, amount);
     }
 
+    /**
+     * @notice Checks if an address is a registered LP for a pool.
+     * @param pool The address of the pool.
+     * @param lp The address of the LP.
+     * @return True if the address is a registered LP for the pool, false otherwise.
+     */
     function isLP(address pool, address lp) external view returns (bool) {
         return poolLPs[pool][lp];
     }
 
+    /**
+     * @notice Gets the number of LPs registered for a pool.
+     * @param pool The address of the pool.
+     * @return The number of registered LPs.
+     */
     function getLPCount(address pool) external view returns (uint256) {
         return poolLPCount[pool];
     }
 
+    /**
+     * @notice Checks if a pool is valid.
+     * @param pool The address of the pool.
+     * @return True if the pool is valid, false otherwise.
+     */
     function isValidPool(address pool) external view returns (bool) {
         return validPools[pool];
     }
 
+    /**
+     * @notice Gets the liquidity amount for an LP in a pool.
+     * @param pool The address of the pool.
+     * @param lp The address of the LP.
+     * @return The liquidity amount.
+     */
     function getLPLiquidity(address pool, address lp) external view returns (uint256) {
         return lpLiquidityAmount[pool][lp];
     }
 
+    /**
+     * @notice Gets the total liquidity for a pool.
+     * @param pool The address of the pool.
+     * @return The total liquidity amount.
+     */
     function getTotalLPLiquidity(address pool) external view returns (uint256) {
         return totalLPLiquidity[pool];
     }