natspec-standards

To write NatSpec documentation for Solidity smart contracts, apply standard tags like @notice, @param, and @return to public functions, and use @dev to explain complex internal logic, state variables, and modifiers. This ensures contract clarity and auditability.

NatSpec standards for Solidity events and errors require using specific tags to describe their purpose and parameters. Documenting events, errors, structs, and enums with proper NatSpec tags ensures that smart contract interfaces are clear and securely auditable.

You need to use the @dev tag in Solidity smart contract documentation when explaining implementation details, complex logic, effects, and security considerations. It is used alongside @notice to provide developers with deeper auditing context.

Yes, NatSpec documentation works with Foundry and Hardhat generation tools. These frameworks process standard Solidity NatSpec tags to automatically generate external documentation from your smart contract code.

Common mistakes to avoid when auditing Solidity NatSpec include missing @param or @return tags on public functions, failing to document complex logic in @dev blocks, and improperly tagging events, errors, and state variables.

The best way to document complex functions in Solidity smart contracts is to use NatSpec patterns that outline requirements, effects, and security considerations within the @dev tag, while keeping user-facing information in the @notice tag.