cerc-io/solidity
16
0
Fork 0
mirror of https://github.com/ethereum/solidity synced 2023-10-03 13:03:40 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Improve documentation about NatSpec

Browse Source 
Clarify the connection to Doxygen.
This commit is contained in:
Alex Beregszaszi 2021-03-24 16:14:47 +00:00
parent 7ac891600d
commit 78a66787d4
2 changed files with 15 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/layout-of-source-files.rst
View File

@ -334,14 +334,10 @@ Single-line comments (``//``) and multi-line comments (``/*...*/``) are possible
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.

15
docs/natspec-format.rst
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