Merge pull request from ethereum/natspec-doc

Improve documentation about NatSpec
This commit is contained in:
chriseth 2021-03-25 10:57:45 +01:00 committed by GitHub
commit 7681a05178
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 20 additions and 13 deletions

View File

@ -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.

View File

@ -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
the source code after the comment, so if it is not an ascii symbol
(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
(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>`. They are written with a
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
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.

View File

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

View File

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