Merge pull request #11160 from ethereum/natspec-doc

Improve documentation about NatSpec

docs/abi-spec.rst

@@ -199,9 +199,9 @@ on the type of ``X`` being
 
 - ``string``:
 
-  ``enc(X) = enc(enc_utf8(X))``, i.e. ``X`` is utf-8 encoded and this value is interpreted
+  ``enc(X) = enc(enc_utf8(X))``, i.e. ``X`` is UTF-8 encoded and this value is interpreted
   as of ``bytes`` type and encoded further. Note that the length used in this subsequent
-  encoding is the number of bytes of the utf-8 encoded string, not its number of characters.
+  encoding is the number of bytes of the UTF-8 encoded string, not its number of characters.
 
 - ``uint<M>``: ``enc(X)`` is the big-endian encoding of ``X``, padded on the higher-order
   (left) side with zero-bytes such that the length is 32 bytes.

docs/layout-of-source-files.rst

@@ -330,18 +330,14 @@ Single-line comments (``//``) and multi-line comments (``/*...*/``) are possible
 
 .. note::
   A single-line comment is terminated by any unicode line terminator
-  (LF, VF, FF, CR, NEL, LS or PS) in utf8 encoding. The terminator is still part of
+  (LF, VF, FF, CR, NEL, LS or PS) in UTF-8 encoding. The terminator is still part of
-  the source code after the comment, so if it is not an ascii symbol
+  the source code after the comment, so if it is not an ASCII symbol
   (these are NEL, LS and PS), it will lead to a parser error.
 
-Additionally, there is another type of comment called a natspec comment,
+Additionally, there is another type of comment called a NatSpec comment,
-which is detailed in the :ref:`style guide<natspec>`. They are written with a
+which is detailed in the :ref:`style guide<natspec>` section. 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
-functions, annotate conditions for formal verification, and provide a
-**confirmation text** which is shown to users when they attempt to invoke a
-function.
 
 In the following example we document the title of the contract, the explanation
 for the two function parameters and two return variables.

docs/natspec-format.rst

@@ -8,6 +8,13 @@ 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:
+
+  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
+  strict compatibility with Doxygen. Please carefully examine the supported tags
+  listed below.
+
 This documentation is segmented into developer-focused messages and end-user-facing
 messages. These messages may be shown to the end user (the human) at the
 time that they will interact with the contract (i.e. sign a transaction).
@@ -20,13 +27,17 @@ use, and which are understood by the Solidity compiler. Also detailed below is
 output of the Solidity compiler, which extracts these comments into a machine-readable
 format.
 
+NatSpec may also include annotations used by third-party tools. These are most likely
+accomplished via the ``@custom:<name>`` tag, and a good use case is analysis and verification
+tools.
+
 .. _header-doc-example:
 
 Documentation Example
 =====================
 
 Documentation is inserted above each ``class``, ``interface`` and
-``function`` using the doxygen notation format.
+``function`` using the Doxygen notation format.
 
 Note: a ``public`` state variable is equivalent to a ``function``
 for the purposes of NatSpec.
@@ -106,7 +117,7 @@ Tag
 ``@author``     The name of the author                                                                 contract, interface
 ``@notice``     Explain to an end user what this does                                                  contract, interface, function, public state variable, event
 ``@dev``        Explain to a developer any extra details                                               contract, interface, function, state variable, event
-``@param``      Documents a parameter just like in doxygen (must be followed by parameter name)        function, event
+``@param``      Documents a parameter just like in Doxygen (must be followed by parameter name)        function, event
 ``@return``     Documents the return variables of a contract's function                                function, public state variable
 ``@inheritdoc`` Copies all missing tags from the base function (must be followed by the contract name) function, public state variable
 ``@custom:...`` Custom tag, semantics is application-defined                                           everywhere

docs/yul.rst

@@ -688,7 +688,7 @@ We will use a destructuring notation for the AST nodes.
         Let G'', L'', mode = E(Gn, L', block)
         G'', Ln, L''[$ret1], ..., L''[$retm]
     E(G, L, l: StringLiteral) = G, L, utf8EncodeLeftAligned(l),
-        where utf8EncodeLeftAligned performs a utf8 encoding of l
+        where utf8EncodeLeftAligned performs a UTF-8 encoding of l
         and aligns it left into 32 bytes
     E(G, L, n: HexNumber) = G, L, hex(n)
         where hex is the hexadecimal decoding function