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 | Tag | Context | Description | |-----|---------|-------------| | `@title` | Contract/interface | Title of the contract | | `@author` | Contract/interface | Author name or team | | `@notice` | Contract/function/event/error | User-facing explanation (shown in etherscan) | | `@dev` | Contract/function/event/error | Developer-facing technical details | | `@param` | Function/event/error | Describes a parameter | | `@return` | Function | Describes a return value | | `@inheritdoc` | Function | Inherits docs from parent contract | | `@custom:tag` | Any | Custom metadata (e.g., `@custom:security-contact` is mandatory) | ## Contract-Level Documentation ```solidity /// @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 security@uniswap.org contract StakingVault is ERC4626, Ownable2Step, ReentrancyGuard { // ... } ``` ## Function Documentation ```solidity /// @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); } ``` ## Multiple Return Values Each return value gets its own `@return` tag, in order. ```solidity /// @notice Returns the position details for a given position ID. /// @param positionId The unique identifier of the position. /// @return owner The address that owns the position. /// @return collateral The amount of collateral deposited (in token decimals). /// @return debt The amount of debt owed (in token decimals). /// @return healthFactor The position's health factor (18 decimals, < 1e18 = liquidatable). function getPosition(uint256 positionId) external view returns ( address owner, uint256 collateral, uint256 debt, uint256 healthFactor ) { // ... } ``` ## @inheritdoc Use `@inheritdoc` to inherit documentation from a parent interface or abstract contract. Add `@dev` for implementation-specific details. ```solidity interface IVault { /// @notice Withdraws tokens by burning vault shares. /// @param shares The number of shares to burn. /// @return amount The number of tokens returned to the caller. function withdraw(uint256 shares) external returns (uint256 amount); } contract Vault is IVault { /// @inheritdoc IVault /// @dev Applies a withdrawal fee of 0.1% (10 bps). The fee is retained /// in the vault, increasing the share price for remaining holders. function withdraw(uint256 shares) external override returns (uint256 amount) { // ... } } ``` ## Event Documentation ```solidity /// @notice Emitted when a user deposits tokens into the vault. /// @param user The address of the depositor. /// @param token The address of the deposited token. /// @param amount The amount deposited (in token's native decimals). /// @param shares The number of vault shares minted. event Deposited(address indexed user, address indexed token, uint256 amount, uint256 shares); ``` ## Error Documentation ```solidity /// @dev Thrown when the oracle price feed returns data older than the staleness threshold. /// @param feed The address of the Chainlink price feed. /// @param updatedAt The timestamp of the last price update. /// @param threshold The maximum allowed age in seconds. error Oracle_StalePrice(address feed, uint256 updatedAt, uint256 threshold); ``` ## Custom Tags ```solidity /// @custom:security-contact security@protocol.xyz /// @custom:oz-upgrades-from StakingVaultV1 /// @custom:storage-location erc7201:protocol.storage.StakingVault contract StakingVaultV2 is StakingVaultV1 { // ... } ``` ## Modifier Documentation ```solidity /// @dev Restricts function access to the designated oracle updater. /// Reverts with {Unauthorized} if caller is not the updater. modifier onlyUpdater() { if (msg.sender != updater) revert Unauthorized(); _; } ``` ## Struct Documentation ```solidity /// @notice Represents a user's staking position. /// @dev Packed into 2 storage slots (64 bytes). See storage-layout skill. /// @param amount The staked token amount (18 decimals). /// @param rewardDebt Used for reward accounting (scaled by ACC_PRECISION). /// @param lockEnd The timestamp when the lock period expires. /// @param boostMultiplier The user's boost factor (100 = 1x, 200 = 2x). struct StakeInfo { uint256 amount; uint256 rewardDebt; uint48 lockEnd; uint16 boostMultiplier; } ``` ## NatSpec Checklist - [ ] Every contract has `@title`, `@author`, `@notice` - [ ] Every public/external function has `@notice`, `@param`, `@return` - [ ] Complex functions have `@dev` with implementation details - [ ] Events have `@notice` and `@param` for each parameter - [ ] Custom errors have `@dev` explaining trigger conditions - [ ] `@inheritdoc` used for interface implementations - [ ] `@custom:security-contact` on all deployable contracts - [ ] No redundant docs (don't restate what the code obviously does) - [ ] Units specified in `@param`/`@return` (decimals, bps, seconds) - [ ] Cross-references to related skills/patterns where helpful