Smart Contract Documentation (NatSpec)
A contract without documentation is a contract that cannot be safely integrated. A developer who will use your token six months from now shouldn't have to reconstruct logic from bytecode and tests. NatSpec is the inline documentation standard for Solidity, read by humans, generated by tools, and displayed in MetaMask when signing transactions.
What NatSpec Is and How It Works
NatSpec (Natural Language Specification) is a set of tags in Solidity comments that the compiler includes in the ABI and a separate JSON document. Supports two formats: single-line (///) and block (/** */).
Main tags:
-
@title— contract name -
@notice— description for end user (displayed in MetaMask) -
@dev— technical details for developer -
@param— description of function parameter -
@return— description of return value -
@custom:tag— custom tags (audit notes, security notices)
Example of properly documented function:
/// @notice Transfers tokens to the specified address
/// @dev Doesn't work with ERC-777 tokens due to hooks; use safeTransfer for unknown recipients
/// @param to Recipient address, cannot be address(0)
/// @param amount Number of tokens in minimum units (wei)
/// @return success True if transfer succeeded
function transfer(address to, uint256 amount) external returns (bool success);
What Gets Generated from NatSpec
forge doc (Foundry) or solidity-docgen generates Markdown/HTML documentation from NatSpec comments. Result is structured API reference with descriptions of each contract, function, event, and error.
For public protocols this is critical: auditors work faster with documented code, integrators don't ask questions in Discord, users see clear text in wallet before signing.
@custom:security and @custom:oz-upgrades-unsafe-allow are special tags read by tools (OpenZeppelin Upgrades checks marked unsafe patterns). Not just documentation — machine-readable annotations.
What to Document
Mandatory: all public and external functions, all events (event), all custom errors (error), all state-changing operations. @notice from user perspective, @dev from integrator perspective.
Optional but useful: internal functions in libraries, complex algorithms (AMM formulas, reward calculation), security-critical assumptions (@dev Assumes price oracle is not manipulable within single block).
Full documentation of a medium-sized contract (500-1000 lines) — 1 working day. Documentation generation and docgen pipeline setup — another 2-4 hours.