Move improvements to the NatSpec documentation

docs/layout-of-source-files.rst

@@ -335,27 +335,6 @@ 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,
-which is detailed in the :ref:`style guide<natspec>` section. They are written with a
-triple slash (``///``) or a double asterisk block(``/** ... */``) and
+which is detailed in the :ref:`style guide<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.
-
-In the following example we document the title of the contract, the explanation
-for the two function parameters and two return variables.
-
-::
-
-    // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >=0.4.21 <0.9.0;
-
-    /** @title Shape calculator. */
-    contract ShapeCalculator {
-        /// @dev Calculates a rectangle's surface and perimeter.
-        /// @param w Width of the rectangle.
-        /// @param h Height of the rectangle.
-        /// @return s The calculated surface.
-        /// @return p The calculated perimeter.
-        function rectangle(uint w, uint h) public pure returns (uint s, uint p) {
-            s = w * h;
-            p = 2 * (w + h);
-        }
-    }

docs/natspec-format.rst

@@ -8,7 +8,7 @@ Solidity contracts can use a special form of comments to provide rich
 documentation for functions, return variables and more. This special form is
 named the Ethereum Natural Language Specification Format (NatSpec).
 
-.. note:
+.. note::
 
   NatSpec was inspired by `Doxygen <https://en.wikipedia.org/wiki/Doxygen>`_.
   While it uses Doxygen-style comments and tags, there is no intention to keep
@@ -36,17 +36,16 @@ tools.
 Documentation Example
 =====================
 
-Documentation is inserted above each ``class``, ``interface`` and
-``function`` using the Doxygen notation format.
-
-Note: a ``public`` state variable is equivalent to a ``function``
+Documentation is inserted above each ``contract``, ``interface``,
+``function``, and ``event`` using the Doxygen notation format.
+A ``public`` state variable is equivalent to a ``function``
 for the purposes of NatSpec.
 
 -  For Solidity you may choose ``///`` for single or multi-line
    comments, or ``/**`` and ending with ``*/``.
 
 -  For Vyper, use ``"""`` indented to the inner contents with bare
-   comments. See `Vyper
+   comments. See the `Vyper
    documentation <https://vyper.readthedocs.io/en/latest/natspec.html>`__.
 
 The following example shows a contract and a function using all available tags.
@@ -57,6 +56,8 @@ The following example shows a contract and a function using all available tags.
   public. You are welcome to use similar comments for your internal and
   private functions, but those will not be parsed.
 
+  This may change in the future.
+
 .. code:: Solidity
 
     // SPDX-License-Identifier: GPL-3.0
@@ -125,11 +126,10 @@ Tag
 =============== ====================================================================================== =============================
 
 If your function returns multiple values, like ``(int quotient, int remainder)``
-then use multiple ``@return`` statements in the same format as the
-``@param`` statements.
+then use multiple ``@return`` statements in the same format as the ``@param`` statements.
 
-Custom tags start with ``@custom:`` and can contain lowercase characters and hyphens following that.
-They can be used everywhere and are part of the developer documentation.
+Custom tags start with ``@custom:`` and must be followed by one or more lowercase letters or hyphens.
+It cannot start with a hyphen however. They can be used everywhere and are part of the developer documentation.
 
 .. _header-dynamic:
 
@@ -237,7 +237,7 @@ file should also be produced and should look like this:
       "kind" : "dev",
       "author" : "Larry A. Gardner",
       "details" : "All function calls are currently implemented without side effects",
-      "custom:experimental": "This is an experimental contract.",
+      "custom:experimental" : "This is an experimental contract.",
       "methods" :
       {
         "age(uint256)" :

docs/style-guide.rst

@@ -1136,16 +1136,15 @@ Avoiding Naming Collisions
 This convention is suggested when the desired name collides with that of a
 built-in or otherwise reserved name.
 
+.. _style_guide_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 <https://www.doxygen.nl>`_ notation
-of one or multiple lines starting with ``///`` or a
-multiline comment starting with ``/**`` and ending with ``*/``.
+Solidity contracts can also contain NatSpec comments. They are written with a
+triple slash (``///``) or a double asterisk block (``/** ... */``) and
+they should be used directly above function declarations or statements.
 
 For example, the contract from :ref:`a simple smart contract <simple-smart-contract>` with the comments
 added looks like the one below::
@@ -1153,7 +1152,6 @@ added looks like the one below::
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.4.16 <0.9.0;
 
-
     /// @author The Solidity Team
     /// @title A simple storage example
     contract SimpleStorage {