Solidity 16 – NatSpec

Published by Mario Oettler on

Commenting source code is important to keep the code maintainable and help others to understand what each section is supposed to do.

That’s why NatSpec (Ethereum Natural Language Specification Format) was introduced.

But NatSpec goes even one step further. It also includes messages that can be useful for the end user.

NatSpec comments are placed above every

  • Contract
  • Interface
  • Library
  • Event
  • Function
  • Public variable (since it creates a get function for this variable)

Scheme

/// or /** @tag Message

You can use the following tags:

TagDescriptionLocation
@title:Title of the contract, library, or interfaceContract, library, or interface
@authorName of the authorContract, library, or interface
@noticeTells the end-user what this function, library, public state variable, etc. does.
It should be readable by people who are not familiar with coding.
contract, library, interface, event function, or public state variable,
@devProvides further details for the developer such as what a formula does or why a certain way was chosen.contract, library, interface, function, state variable, or event
@param <param name>Gives detailed information about the function parameters.function or event
@return <return value>Tells the developer what the function should return.function or public state variable
@inheritdocCopies any missing tags in this location from the base contract.function or public state variable
@<custom>Custom tags can be used for your own comments or for documentation software.anywhere
Table with NatSpec tags.
Categories: