mirror of
https://github.com/ethereum/solidity
synced 2023-10-03 13:03:40 +00:00
Merge pull request #11160 from ethereum/natspec-doc
Improve documentation about NatSpec
This commit is contained in:
commit
7681a05178
@ -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.
|
||||
|
@ -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.
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user