Solidity Tutorial

Guide To Comments in Solidity including NatSpec Format

Share on twitter
Share on linkedin
Share on whatsapp
Share on facebook
Share on telegram

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.

NatSpec Comments in Solidity

For more details on NatSpec comment style in Solidity, you can check the documentation.