Natspec in Solidity | Solidity Tips & Examples

Natspec comments are important for Solidity developers to understand because sooner or later you will come across a code base that requires you work with them.

Proponents will say Natspec makes the code more readable and understandable. While I personally disagree with this and prefer to separate code and documentation, the format is popular and it provides a standardized format for code based documentation.

1. Natspec In Solidity
2. Natspec Example Contract
3. Natspec Tags
4. Adding Natspec With ChatGPT
5. Auto-Generating Docs
6. The Future Of Documentation

Natspec In Solidity

Natspec stands for Natural Language Specification and is a standard format for adding documentation to Solidity code using natural language comments. Natspec comments are written in plain English and provide an easily readable description of what a function or contract does, what parameters it takes, what values it returns, and any other relevant information that a developer may need to know when working with the code.

Many development tools, such as the Solidity compilers and IDEs like Remix, can parse natspec comments and generate human-readable documentation that developers can use to understand and work with the code more effectively.

---

Natspec Example Contract

This code is available as part of the Solidity Snippets Github repository:
https://github.com/jamesbachini/Solidity-Snippets/blob/main/contracts/Natspec.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0;

/**
 * @title Natspec
 * @author James Bachini
 * @dev An example contract to demonstrate natspec documentation
 * @notice This contract is untested
 * @custom:experimental This is an experimental contract.
 */
contract Natspec {
    string public txt = "I hate code comments";

    /**
     * @dev Update the txt state variable
     * @notice This returns a uint for no reason
     * @param {string} _txt a new text string
     * @return {uint} just a demo number
     */
    function update(string memory _txt) public returns (uint) {
        txt = _txt;
        return 1;
    }
}

---

Natspec Tags

@title This tag specifies the title of the contract.

@notice This tag is used to describe the effects of a function or contract. It’s meant to be a brief summary of what the function or contract does.

@dev This tag is used to provide additional information that’s only relevant during development. For example, you might use this tag to provide details about how a certain function works or to remind yourself to remove a certain line of code before deploying to production.

@param This tag is used to describe the input parameters for a function. You should include this tag for each parameter and provide a brief description of what the parameter represents.

@return This tag is used to describe the return value of a function. You should include this tag for each return value and provide a brief description of what the return value represents.

@devnote This tag is similar to @dev, but it’s used to provide notes that are specific to the developer. For example, you might use this tag to remind yourself to refactor a certain piece of code in the future.

@inheritdoc This tag is used to indicate that a function or contract inherits its documentation from a parent contract. This is useful if you have a function that’s inherited from a parent contract and you don’t want to duplicate the documentation.

@custom This tag is used to define custom tags that aren’t part of the standard natspec tags. This is useful if you want to create your own documentation tags that are specific to your project.

---

Adding Natspec With ChatGPT

One of my favourite uses of ChatGPT is to take a Solidity contract and ask it to:

“Can you edit this code to add in natspec comments”

As with any automated tool always check any changes made using a diff checker before pushing the code.

---

Auto-Generating Docs

You can create GitBook documentation using Solidity natspec and OpenZeppelin’s docgen tool:

1. Write your Solidity code and include natspec comments in your code to document your functions, variables, and events.
2. Use solidity-docgen or an alternative to extract the natspec comments from your Solidity code and generate documentation files in markdown format.
3. Create a GitBook account and create a new book.
4. In the GitBook editor, create a new chapter for your Solidity documentation.
5. Use the GitBook syntax to format your documentation. You can include headings, text, images, and code snippets. To include your Solidity natspec documentation, use the markdown syntax to include the generated markdown files.
6. Publish your GitBook documentation for others to access and read.

Marvel in your fine documentation and beautifully commented code.

---

The Future Of Documentation

In the future AI will automatically generate documentation from raw code, reducing the need for in-code comments, except where they add real value. Natural language processing and machine learning algorithms will analyse the code and generate high-quality documentation that accurately describes the functionality of the code.

One approach that is evolving rapidly involves translating the code into a more human-readable form, such as pseudocode, and then generating documentation from that. It may in the future be possible to use AI as a bridge between human explained pseudocode and raw bytecode although the use of nocode platforms in blockchain development is terrifying.

Code commenting is a personal preference and it comes down to the decision of the project founder or CTO as to how far devs should go with adding comments. On one extreme we have OpenSea’s seaport codebase where the code is unreadable but it’s explained in huge amounts of code comments. On the other side there are developers who use expressive Solidity with clear function names and parameters who will only add natspec code if they are forced at gun point to do so.

Whichever side you stand with it’s a good idea to have some experience using Natspec and keep it as a sharp instrument in the toolbox.

Hopefully in the future we can have the best of both worlds where documentation lives as a layer on top of a clearly written Solidity code

---