Add NatSpec to Style-Guide

related to #2270

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                      |
++-------------+-------------------------------------------+-------------------------------+