NatSpec comments are used for rich documentation of functions, return variables, events, and more in Solidity. NatSpec stands for Ethereum Natural Language Specification Format and it's based on the Doxygen notation style.
There are messages, that are focused on the developer and messages that are focused on the end-user. For example, a message may be shown to the end-user while interacting with the contract, like signing a transaction or similar operation.
single-line NatSpec comments
For a single-line NatSpec comment, use /// at the start of the line.
/// this is a single-line NatSpec comment in a solidity contract
multi-line NatSpec comments
For a multi-line NatSpec comment, begin the comment with /** and end the comment with /* to finish the NatSpec comment block.
/**
This is a multi-line
NatSpec comment
in a Solidity contract
*/
NatSpec tags explained
In NatSpec comments, the following tags can be used but they are optional. If no tags are used, then the comment is treated as @notice tag by default.
| tag |
description |
context |
| @title |
title to describe the context |
contract, library, interface |
| @author |
name of the author |
contract, library, interface |
| @notice |
explanation that can be shown to the end-user of the contract |
contract, library, interface, function, public state variable, event |
| @dev |
explanation that can be shown to the developer for extra details |
contract, library, interface, function, state variable, event |
| @param |
documents a specific parameter and must be followed by the parameter name |
function, event |
| @return |
documents the return variable of the function |
function, public state variable |
| @inheritdoc |
copies missing tags from the base function and must be followed by the contract name |
function, public state variable |
| @custom:... |
custom tag |
- |
If a function returns multiple values, then multiple @return tags have to be used similar to multiple @param tags used for multiple parameters.
Generate User and Developer Documentation
NatSpec comments parsed by the compiler can generate two different JSON files as output: The User Documentation and the Developer Documentation.
To generate Developer and User Documentation run:
solc --userdoc --devdoc myContract.sol
To generate only Developer Documentation run:
solc --devdoc myContract.sol
To generate only User Documentation run:
solc --userdoc myContract.sol