Contents
Comments in Solidity
In Solidity, there are two types of comments –
- Regular Comments
- NatSpec Comments
Let us see each of them in detail.
Regular Comments
These are regular code comments in Solidity that are used by developers to document their code base for better understanding and maintainability by other developers. Solidity supports the two popular comments styles of // and /* … */
Example – 1
In the below example, the // comment style is used. This comment style works only for a single line, this means if you have to comment multiple lines you will have to use // at the start of each line.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.10;
// This is a comment that only works for single line
// For multiple lines, use // in each line
contract Demo1
{
string public line = "This line is from Demo1.sol";
}
Example – 2
In this example, /* */ comment style is used. This style can be used for multiple lines as shown below.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.10;
/* This is a comment
that can span on multiple lines */
contract Demo1
{
string public line = "This line is from Demo1.sol";
}
NatSpec Comment
Solidity supports a rich comment format called NatSpec for documenting contract, interface, library, function, and events. NatSpec documentation style has been created by Ethereum only but it is quite inspired by Doxygen.
The NatSpec documentation has two target audiences – the end-users and developers and it let you show comments accordingly.
Natspec comment style uses /// for single-line comments and /* */ for multiline comments and you can use the tags shown in the below table, but they are completely optional. If no tags are used then the comments after /// or between /* */ are treated as @notice tag as default.
As per Solidity document, the NatSpec currently works only for functions that are external or public. However, you can still use them for the internal and private functions but they will be ignored by NatSpec.
| Tag | Context | |
|---|---|---|
@title |
A title that should describe the contract/interface | contract, library, interface |
@author |
The name of the author | contract, library, interface |
@notice |
Explain to an end user what this does | contract, library, interface, function, public state variable, event |
@dev |
Explain to a developer any extra details | contract, library, interface, function, state variable, event |
@param |
Documents a parameter just like in Doxygen (must be followed by parameter name) | function, event |
@return |
Documents the return variables of a contract’s function | function, public state variable |
@inheritdoc |
Copies all missing tags from the base function (must be followed by the contract name) | function, public state variable |
@custom:... |
Custom tag, semantics is application-defined | everywhere |
Example
The below examples shows the use of various tags with both /// and /* */ comment style of NatSpec.
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.10;
/// @author Blockchain Knowledge Team
/// @title Demo Contract
contract DemoContract
{
uint storedData;
/// Store `x`.
/// @param x the new value to store
/// @dev stores the number in the state variable `storedData`
function set(uint x) public
{
storedData = x;
}
/// Return the stored value.
/// @dev retrieves the value of the state variable `storedData`
/// @return the stored value
function get() public view returns (uint)
{
return storedData;
}
}
To generate the documentation for the above example, you can run the below command in the command prompt –
solc --userdoc demo.sol
We are however working on Remix IDE and it provides a plugin called ETHDOC – Documentation Generator. It can be activated from the plugin manager which will create a new icon in the left panel. You can use this plugin to generate the documentation which will look like this for the above example.
For more details on NatSpec comment style in Solidity, you can check the documentation.
