diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/layout-of-source-files.rst | 2 | ||||
| -rw-r--r-- | docs/style-guide.rst | 61 |
2 files changed, 62 insertions, 1 deletions
diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index ad84b200..fa36fc6a 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -267,7 +267,7 @@ Single-line comments (``//``) and multi-line comments (``/*...*/``) are possible (these are NEL, LS and PS), it will lead to a parser error. Additionally, there is another type of comment called a natspec comment, -for which the documentation is not yet written. They are written with a +which is detailed in the :ref:`style guide<natspec>`. They are written with a triple slash (``///``) or a double asterisk block(``/** ... */``) and they should be used directly above function declarations or statements. You can use `Doxygen <https://en.wikipedia.org/wiki/Doxygen>`_-style tags inside these comments to document diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 68fee871..bf1be93e 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -1093,3 +1093,64 @@ General Recommendations ======================= TODO + +.. _natspec: + +******* +NatSpec +******* + +Solidity contracts can have a form of comments that are the basis of the +Ethereum Natural Language Specification Format. + +Add comments above functions or contracts following `doxygen <http://www.doxygen.nl>`_ notation +of one or multiple lines starting with `///` or a +multiline comment starting with `/**` and ending with `*/`. + +For example, the contract from `a simple smart contract <simple-smart-contract>`_ with the comments +added looks like the one below:: + + pragma solidity >=0.4.0 <0.6.0; + + /// @author The Solidity Team + /// @title A simple storage example + contract SimpleStorage { + 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; + } + } + +Natspec uses doxygen style tags with some special meaning. +If no tag is used, then the comment applies to ``@notice``. +The ``@notice`` tag is the main NatSpec tag and its audience is +users of the contract who have never seen the source code, so it should make +as little assumptions about the inner details as possible. +All tags are optional. + ++-------------+-------------------------------------------+-------------------------------+ +| Tag | Description | Context | ++=============+===========================================+===============================+ +| ``@title`` | A title that describes the contract | contract, interface | ++-------------+-------------------------------------------+-------------------------------+ +| ``@author`` | The name of the author | contract, interface, function | ++-------------+-------------------------------------------+-------------------------------+ +| ``@notice`` | Explanation of functionality | contract, interface, function | ++-------------+-------------------------------------------+-------------------------------+ +| ``@dev`` | Any extra details | contract, interface, function | ++-------------+-------------------------------------------+-------------------------------+ +| ``@param`` | Parameter type followed by parameter name | function | ++-------------+-------------------------------------------+-------------------------------+ +| ``@return`` | The return value of a contract's function | function | ++-------------+-------------------------------------------+-------------------------------+ |