misc: Natspec added

Author: donosonaumczuk

src/ATokenVaultRevenueSplitterOwner.sol

@@ -8,44 +8,98 @@ import {IATokenVault} from "./interfaces/IATokenVault.sol";
 import {IERC20} from "@openzeppelin/token/ERC20/IERC20.sol";
 import {SafeERC20} from "@openzeppelin/token/ERC20/utils/SafeERC20.sol";
 
+/**
+ * @title ATokenVaultRevenueSplitterOwner
+ * @author Aave Protocol
+ * @notice ATokenVault owner with revenue split capabilities.
+ */
 contract ATokenVaultRevenueSplitterOwner is Ownable {
     using SafeERC20 for IERC20;
 
+    /**
+     * @dev Emitted at construction time for each recipient set
+     * @param recipient The address of the recipient set
+     * @param shareInBps The recipient's share of the revenue in basis points
+     */
     event RecipientSet(address indexed recipient, uint16 shareInBps);
 
+    /**
+     * @dev Emitted when revenue is split for each recipient and asset
+     * @param recipient The address of the recipient receiving the revenue
+     * @param asset The asset being split
+     * @param amount The amount of revenue sent to the recipient in the split asset
+     */
     event RevenueSplit(address indexed recipient, address indexed asset, uint256 amount);
 
-    uint256 public constant TOTAL_SHARE_IN_BPS = 10_000; // 100.00%
+    /**
+     * @dev The sum of all recipients' shares in basis points, represents 100.00%. Each basis point is 0.01%.
+     */
+    uint256 public constant TOTAL_SHARE_IN_BPS = 10_000;
 
+    /**
+     * @dev The aToken Vault to own, whose revenue is split.
+     */
     IATokenVault public immutable VAULT;
-
+    
+    /**
+     * @dev A struct to represent a recipient and its share of the revenue in basis points.
+     * @param addr The address of the recipient
+     * @param shareInBps The recipient's share of the revenue in basis points
+     */
     struct Recipient {
         address addr;
         uint16 shareInBps;
     }
 
+    /**
+     * @dev The recipients set for this revenue splitter. Set at construction time only, cannot be modified afterwards.
+     */
     Recipient[] internal _recipients;
 
+    /**
+     * @dev Constructor.
+     * @param vault The address of the aToken Vault to own, whose revenue is split.
+     * @param owner The address owning this contract, the effective owner of the vault.
+     * @param recipients The recipients to set for the revenue split. Cannot be modified afterwards.
+     */
     constructor(address vault, address owner, Recipient[] memory recipients) {
         VAULT = IATokenVault(vault);
         _setRecipients(recipients);
         _transferOwnership(owner);
     }
 
-    function transferVaultOwnership(address newOwner) public onlyOwner {
+    /**
+     * @dev Transfers the ownership of the aToken vault to a new owner. Claims all fees and rewards prior to transfer,
+     * to secure already accrued fees and rewards for the configured split recipients.
+     * @dev Only callable by the owner of this contract.
+     * @dev DO NOT confuse with `transferOwnership` which transfers the ownership of this contract instead.
+     * @param newVaultOwner The address of the new aToken vault owner.
+     */
+    function transferVaultOwnership(address newVaultOwner) public onlyOwner {
         _claimRewards();
         _withdrawFees();
-        Ownable(address(VAULT)).transferOwnership(newOwner);
+        Ownable(address(VAULT)).transferOwnership(newVaultOwner);
     }
 
+    /**
+     * @dev Withdraws all vault fees to this contract, so they can be split among the configured recipients.
+     */
     function withdrawFees() public {
         _withdrawFees();
     }
 
+    /**
+     * @dev Claims all vault rewards to this contract, so they can be split among the configured recipients.
+     */
     function claimRewards() external {
         _claimRewards();
     }
 
+    /**
+     * @dev Splits the revenue from the given assets among the configured recipients. Assets must follow the ERC-20
+     * interface and be held by this contract.
+     * @param assets The assets to split the revenue from.
+     */
     function splitRevenue(address[] calldata assets) public {
         Recipient[] memory recipients = _recipients;
         for (uint256 i = 0; i < assets.length; i++) {
@@ -60,8 +114,12 @@ contract ATokenVaultRevenueSplitterOwner is Ownable {
         }
     }
 
+    // TODO: Should we support splitting native currency revenue or only ERC20s?
     // TODO: address(0) used in the event instead of ad-hoc event for native revenue?
     // TODO: Should we assume recipients will succeed at receiving native? If one fails, the whole call fails.
+    /**
+     * @dev Splits the native currency revenue among the configured recipients.
+     */
     function splitRevenue() public {
         uint256 amountToSplit = address(this).balance;
         for (uint256 j = 0; j < _recipients.length; j++) {
@@ -74,14 +132,33 @@ contract ATokenVaultRevenueSplitterOwner is Ownable {
         }
     }
 
+    /**
+     * @dev Rescues assets that may have accidentally been transferred to the vault.
+     * @dev Only callable by the owner of this contract.
+     * @dev The asset to rescue cannot be the vault's aToken.
+     * @dev Fees cannot be "rescued" as they are accrued in the vault's aToken. Rewards cannot be "rescued" as they are 
+     * not held by the vault contract. Thus, already accrued fees and rewards cannot be taken from split recipients.
+     * @param asset The asset to rescue from the vault.
+     * @param to The address to send the rescued assets to.
+     * @param amount The amount of assets to rescue from the vault.
+     */
     function emergencyRescue(address asset, address to, uint256 amount) public onlyOwner {
         VAULT.emergencyRescue(asset, to, amount);
     }
 
+    /**
+     * @dev Sets the fee for the vault.
+     * @dev Only callable by the owner of this contract.
+     * @param newFee The new fee for the vault.
+     */
     function setFee(uint256 newFee) public onlyOwner {
         VAULT.setFee(newFee);
     }
 
+    /**
+     * @dev Getter for the revenue split configured recipients.
+     * @return The configured recipients with their corresponding share in basis points.
+     */
     function getRecipients() public view returns (Recipient[] memory) {
         return _recipients;
     }
@@ -95,7 +172,9 @@ contract ATokenVaultRevenueSplitterOwner is Ownable {
         VAULT.withdrawFees(address(this), feesToWithdraw);
     }
 
-    // Assumes no duplicates
+    /**
+     * @dev Does not check for duplicates in the recipients array. Sum of shares must be represent 100.00% in BPS.
+     */
     function _setRecipients(Recipient[] memory recipients) internal {
         uint256 accumulatedShareInBps = 0;
         for (uint256 i = 0; i < recipients.length; i++) {