How to document Solidity smart contracts with no sweat

Programming smart contracts on blockchain can sometimes be harder then we are used to when compared with other programming languages, especially because there are not many tools which we can help us in the process. Below you will find how we solved the documentation generation in Solidity.

Why is commenting Solidity smart contracts important? There are two main reasons:

• help out developer who will inherit that smart contract,
• help out developer or a user that will consume your smart contract.

So, how should you do it? Well, there is Ethereum natural specification format that is developed and promoted by Ethereum itself. It’s very similar to documentation format of other popular programming languages but with one distinctions — it uses /// instead of // (although /** ... */ blocks are supported).

Here are the Ethereum natural specification tags and rules:

Ethereum Natural Specification Format tags

Whatever the reason that made you document your code, you will soon find it’s quite tedious and time consuming to write documentation since there is quite a lot of boilerplate text for each function. That’s why we’ve made simple Atom plugin — solidity-comments. It contains basic functionally for generating all the boilerplate documentation for your Solidity smart contract by pressing the following combination of keys: Ctrl + Alt + G.

For example, if you have following code:

pragma solidity 0.4.24;
contract SomeContract {
function test(uint _param1, uint _param2) external {
        require(_param1 == 1 && _param2 == 2);
    }
}

and you press Ctrl + Alt + G , you will get:

pragma solidity 0.4.24;
/// @title SomeContract
/// @notice
/// @dev
contract SomeContract {
    /// @notice
    /// @dev
    /// @param _param1
    /// @param _param2
    /// @return
    function test(uint _param1, uint _param2) external {
        require(_param1 == 1 && _param2 == 2);
    }
}

and then you just have to fill in the blanks. Cool, right?

We know, not everyone uses Atom, that’s why we extracted logic into separate solidity-comments-core library and we will soon implement a CLI interface for this. As for other IDEs, we would very much like to port this plugin to other editors especially Webstorm, so we are currently investigating what is the easiest way to port that JavaScript library into other languages (Java for Webstorm and Python for Sublime Text). If you have any suggestion for porting, feel free to leave a comment below!

Plugin still misses couple of necessary features, where most important one is to update function documentation if params have changed. If you want to contribute or make plugin for some other IDE, checkout our repository:

NodeFactoryio/solidity-comments-core

When you need to export your documentation into HTML, you can use documentation generator like Doxity from Ethereum or docgen from OpenZeppelin.

Happy documented coding!

Follow us on Medium or Twitter if you want more blockchain development insights like this.

Get Best Software Deals Directly In Your Inbox

Node Factory is a blockchain development company committed to developing new technologies and leveraging them to make better applications worldwide. Let us know what we can do for you.