natspec-standards

NatSpec Standards

Required Documentation

Every public and external function must have NatSpec. Internal functions that are non-trivial should also be documented.

Tags Reference

Contract-Level Documentation

/// @title Staking Vault
/// @author Uniswap Labs
/// @notice Handles staking deposits and reward distribution for protocol governance tokens.
/// @dev Uses ERC-4626 vault standard with custom reward distribution.
///      Storage layout is proxy-compatible (see storage-layout skill).
/// @custom:security-contact [email protected]
contract StakingVault is ERC4626, Ownable2Step, ReentrancyGuard {
    // ...
}

Function Documentation

/// @notice Deposits tokens into the vault and mints shares to the caller.
/// @dev Follows CEI pattern. Emits {Deposited} event. The share calculation
///      uses the current exchange rate, which may be manipulated in the same
///      block — see economic-attack-vectors for first-depositor defense.
/// @param token The address of the ERC-20 token to deposit.
/// @param amount The amount of tokens to deposit (in token's native decimals).
/// @return shares The number of vault shares minted to the caller.
function deposit(address token, uint256 amount)
    external
    nonReentrant
    whenNotPaused
    returns (uint256 shares)
{
    if (token == address(0)) revert ZeroAddress();
    if (amount == 0) revert ZeroAmount();

    shares = convertToShares(amount);
    _mint(msg.sender, shares);

    IERC20(token).safeTransferFrom(msg.sender, address(this), amount);

    emit Deposited(msg.sender, token, amount, shares);
}