docs: add natspec

Author: PavelNaydanov

src/MetaToken.sol

@@ -3,6 +3,12 @@ pragma solidity 0.8.28;
 
 import {ERC20} from "solmate/tokens/ERC20.sol";
 
+/**
+ * @title Token of MetaLamp
+ * @author Pavel Naydanov
+ * @notice General token of the MetaLamp. Inherited from ERC-20.
+ * All supply of token is minted to the distributor's smart-contract, which releases vesting.
+ */
 contract MetaToken is ERC20 {
     uint256 private constant _INITIAL_TOTAL_SUPPLY = 1_000_000_000e18;
 

src/tokenDistribution/MetaTokenDistributor.sol

@@ -11,16 +11,29 @@ import {Vesting, IVesting} from "./vesting/Vesting.sol";
 import {IVestingParams} from "./vesting/interfaces/IVestingParams.sol";
 import {Schedule, Beneficiary, VestingType} from "./utils/Common.sol";
 
+/**
+ * @title Distributor of MetaLamp token
+ * @author Pavel Naydanov
+ * @notice Deploy vesting contract, which based on vesting params.
+ * At the time of contract deployment, an instance of the meta token is created.
+ * Any account can start vesting after the start time.
+ */
 contract MetaTokenDistributor is IMetaTokenDistributor {
     using SafeERC20 for IERC20;
 
+    /// @notice Implementation of vesting contract for using in Clone
     address private _vestingImpl;
+
+    /// @notice MetaLamp token for distribution
     IERC20 private _META;
 
+    /// @notice A smart contract that stores vesting parameters (allocation, schedule, etc.)
     IVestingParams private _vestingParams;
 
+    /// @notice Stores addresses of created vestings
     mapping(VestingType vestingType => address vesting) private _vestingAddresses;
 
+    /// @dev Validate start vesting time
     modifier validateTime(VestingType vestingType) {
         uint64 startTime = _vestingParams.getStartTime();
 
@@ -46,6 +59,12 @@ contract MetaTokenDistributor is IMetaTokenDistributor {
         emit MetaTokenDeployed(address(_META));
     }
 
+    /**
+     * @notice Start vesting
+     * @param vestingType Type of vesting (Team, Liquidity, etc.)
+     * @return vesting Address of created vesting contract
+     * @dev Any can start vesting after start time
+     */
     function startVesting(VestingType vestingType) external validateTime(vestingType) returns (address vesting) {
         if (_vestingAddresses[vestingType] != address(0)) {
             revert VestingHasAlreadyStarted();
@@ -67,14 +86,20 @@ contract MetaTokenDistributor is IMetaTokenDistributor {
         emit VestingStarted(vesting);
     }
 
+    /// @notice Returns address of MetaLamp token
     function getMETAAddress() external view returns (address) {
         return address(_META);
     }
 
+    /**
+     * @notice Returns address of created vesting contract
+     * @param vestingType Type of vesting (Team, Liquidity, etc.)
+     */
     function getVestingAddress(VestingType vestingType) external view returns (address) {
         return _vestingAddresses[vestingType];
     }
 
+    /// @notice Returns address of VestingParams contract
     function getVestingParamsAddress() external view returns (address) {
         return address(_vestingParams);
     }

src/tokenDistribution/interfaces/IMetaTokenDistributor.sol

@@ -4,11 +4,19 @@ pragma solidity 0.8.28;
 import {VestingType} from "../utils/Common.sol";
 
 interface IMetaTokenDistributor {
+    /// @notice Emit when vesting contract deployed
     event VestingStarted(address vesting);
+
+    /// @notice Emit when MetaLamp token deployed
     event MetaTokenDeployed(address META);
 
+    /// @notice Revert when trying to start vesting at an earlier start time
     error VestingStartTimeHasNotArrived();
+
+    /// @notice Revert when call with zero address
     error ZeroAddress();
+
+    /// @notice Revert when trying to start vesting again
     error VestingHasAlreadyStarted();
 
     function startVesting(VestingType vestingType) external returns (address vesting);

src/tokenDistribution/vesting/Vesting.sol

@@ -9,7 +9,8 @@ import {Schedule, Period, Beneficiary} from "../utils/Common.sol";
 
 /**
  * @title Vesting contract of the base token
- * @dev Each new vesting instance is created through a factory using the Minimal Clones pattern.
+ * @author Pavel Naydanov
+ * @dev Each new vesting instance is created using the Minimal Clones pattern.
  * Vesting settings are set at the time of deploying a new instance in the initialize() function.
  * Beneficiaries can claim the token according to the schedule by calling the claim() function
  */

src/tokenDistribution/vesting/VestingParams.sol

@@ -4,6 +4,13 @@ pragma solidity 0.8.28;
 import {IVestingParams} from "./interfaces/IVestingParams.sol";
 import {VestingType, Beneficiary, Schedule, Period} from "../utils/Common.sol";
 
+/**
+ * @title Vesting params
+ * @author Pavel Naydanov
+ * @notice The contract describes the parameters of the launched vestings.
+ * Includes: total amount of the vestings, the addresses of the beneficiaries, allocations, the unlocking schedule
+ * The start time is common for all types of vesting. Start time and addresses of the beneficiaries are set during contract deployment.
+ */
 contract VestingParams is IVestingParams {
     uint256 public constant MONTH = 30 days;
 
@@ -21,7 +28,10 @@ contract VestingParams is IVestingParams {
     uint256 public constant LIQUIDITY_CLIFF_PERIOD = 4 * MONTH; // 4 month
     uint256 public constant LIQUIDITY_VESTING_PORTION = 400; // 4%
 
+    /// @notice Start time of vestings
     uint64 private _startTime;
+
+    /// @notice List of beneficiaries for vesting type
     mapping(VestingType vestingType => Beneficiary[] beneficiaries) private _beneficiaries;
 
     constructor(
@@ -39,7 +49,12 @@ contract VestingParams is IVestingParams {
         _validateAndStoreBeneficiaries(VestingType.LIQUIDITY, liquidityBeneficiaries, LIQUIDITY_TOTAL_AMOUNT);
     }
 
-    /// @dev Portions 100% equal 10_000. It's _BASIS_POINTS, which declared in Vesting contract
+    /**
+     * @notice Get schedule by vesting type
+     * @param vestingType Type of vesting (Team, Liquidity, etc.)
+     * @dev Portions 100% equal 10_000. It's _BASIS_POINTS, which declared in Vesting contract
+     * @return schedule Schedule structure
+     */
     function getSchedule(VestingType vestingType) public view returns (Schedule memory schedule) {
         (
             ,
@@ -69,14 +84,28 @@ contract VestingParams is IVestingParams {
         });
     }
 
+    /**
+     * @notice Get beneficiaries by vesting type
+     * @param vestingType Type of vesting (Team, Liquidity, etc.)
+     * @return List of the beneficiaries
+     */
     function getBeneficiaries(VestingType vestingType) public view returns (Beneficiary[] memory) {
         return _beneficiaries[vestingType];
     }
 
+    /**
+     * @notice Get vesting constant by vesting type
+     * @param vestingType Type of vesting (Team, Liquidity, etc.)
+     * @return totalAmount Total amount of the vesting type
+     * @return numberOfPeriods Number of vesting periods (includes tge and cliff periods)
+     * @return tgePortions Unlocked tge portion based on BASIS_POINTS from vesting contract
+     * @return cliffPeriod Duration time of the cliff period when unlocked amount is zero
+     * @return vestingPortion Unlocked vesting period portion based on BASIS_POINTS from vesting contract
+     */
     function getVestingConstant(VestingType vestingType)
         public
         pure
-        returns ( // TODO: описать возвращаемые значения в natspec
+        returns (
             uint256 totalAmount,
             uint256 numberOfPeriods,
             uint256 tgePortions,
@@ -85,26 +114,29 @@ contract VestingParams is IVestingParams {
         )
     {
         if (vestingType == VestingType.TEAM) {
-            return (
-                TEAM_TOTAL_AMOUNT,
-                TEAM_NUMBER_OF_PERIODS,
-                TEAM_TGE_PORTION,
-                TEAM_CLIFF_PERIOD,
-                TEAM_VESTING_PORTION
-            );
+            totalAmount = TEAM_TOTAL_AMOUNT;
+            numberOfPeriods = TEAM_NUMBER_OF_PERIODS;
+            tgePortions = TEAM_TGE_PORTION;
+            cliffPeriod = TEAM_CLIFF_PERIOD;
+            vestingPortion = TEAM_VESTING_PORTION;
         }
 
         if (vestingType == VestingType.LIQUIDITY) {
-            return (
-                LIQUIDITY_TOTAL_AMOUNT,
-                LIQUIDITY_NUMBER_OF_PERIODS,
-                LIQUIDITY_TGE_PORTION,
-                LIQUIDITY_CLIFF_PERIOD,
-                LIQUIDITY_VESTING_PORTION
-            );
+            totalAmount = LIQUIDITY_TOTAL_AMOUNT;
+            numberOfPeriods = LIQUIDITY_NUMBER_OF_PERIODS;
+            tgePortions = LIQUIDITY_TGE_PORTION;
+            cliffPeriod = LIQUIDITY_CLIFF_PERIOD;
+            vestingPortion = LIQUIDITY_VESTING_PORTION;
         }
     }
 
+    /**
+     * @notice Get vesting params by vesting type
+     * @param vestingType Type of vesting (Team, Liquidity, etc.)
+     * @return Schedule of the vesting
+     * @return List of the beneficiaries
+     * @return totalAmount Total amount of the vesting type
+     */
     function getVestingParams(VestingType vestingType)
         external
         view
@@ -123,6 +155,7 @@ contract VestingParams is IVestingParams {
         );
     }
 
+    /// @notice Return start time for all vesting types
     function getStartTime() external view returns (uint64) {
         return _startTime;
     }

src/tokenDistribution/vesting/interfaces/IVesting.sol

@@ -6,40 +6,40 @@ import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 import {Schedule, Beneficiary} from "../../utils/Common.sol";
 
 interface IVesting {
-    /// @dev It is forbidden to use a zero address
+    /// @notice Revert when call with zero address
     error ZeroAddress();
 
-    /// @dev The list of beneficiaries must not be zero.
+    /// @notice Revert when call with zero list of beneficiaries
     error ZeroBeneficiaries();
 
-    /// @dev The amount should not be zero
+    /// @notice Revert when call with zero amount
     error ZeroAmount();
 
-    /// @dev Duplication of beneficiary for one vesting is not allowed
+    /// @notice Revert when duplication of beneficiary for one vesting is not allowed
     error DuplicateBeneficiary(address account);
 
-    /// @dev The balance of the base token and the sum of all beneficiaries does not match
+    /// @notice Revert when sum of beneficiaries amount mismatch with total amount
     error IncorrectAmountOfBeneficiaries();
 
-    /// @dev Invalid vesting start time. Must be greater or equal the current block timestamp
+    /// @notice Revert when invalid vesting start time. Must be greater or equal the current block timestamp
     error InvalidStartTime();
 
-    /// @dev Vesting period portion must be less than BASIS_POINTS
+    /// @notice Revert when vesting period portion less than BASIS_POINTS
     error InvalidPortion();
 
-    /// @dev Sum of vesting period portion must be equal BASIS_POINTS
+    /// @notice Revert when sum of vesting period portion not equal BASIS_POINTS
     error IncorrectTotalPeriodPortions();
 
-    /// @dev Each new end period time must be greater then prev
+    /// @notice Revert when each new end period time greater then prev
     error IncorrectPeriodTime();
 
-    /// @dev Emitted when vesting schedule params has been initialized
+    /// @notice Emit when vesting schedule params has been initialized
     event ScheduleInitialized(Schedule schedule);
 
-    /// @dev Emitted when list of beneficiaries has been initialized
+    /// @notice Emit when list of beneficiaries has been initialized
     event BeneficiariesInitialized(Beneficiary[] beneficiaries);
 
-    /// @dev Emitted when beneficiary has claimed vesting token
+    /// @notice Emit when beneficiary has claimed vesting token
     event Claimed(address indexed account, uint256 amount);
 
     function initialize(IERC20 baseToken, Schedule memory schedule, Beneficiary[] memory beneficiaries) external;

src/tokenDistribution/vesting/interfaces/IVestingParams.sol

@@ -4,10 +4,19 @@ pragma solidity 0.8.28;
 import {VestingType, Beneficiary, Schedule} from "../../utils/Common.sol";
 
 interface IVestingParams {
+    /// @notice Revert when call with invalid start time
     error InvalidStartTime();
+
+    /// @notice Revert when call with zero list of beneficiaries
     error ZeroBeneficiaries();
+
+    /// @notice Revert when call with zero address
     error ZeroAddress();
+
+    /// @notice Revert when call with zero amount
     error ZeroAmount();
+
+    /// @notice Revert when sum of beneficiaries amount mismatch with total amount
     error IncorrectBeneficiaryAmounts();
 
     function getSchedule(VestingType vestingType) external view returns (Schedule memory schedule);