cerc-io/solidity
15
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 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. (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 triple slash (``///``) or a double asterisk block(``/** ... */``) and
they should be used directly above function declarations or statements. 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 In the following example we document the title of the contract, the explanation
for the two function parameters and two return variables. 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 documentation for functions, return variables and more. This special form is
named the Ethereum Natural Language Specification Format (NatSpec). 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 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 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). 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 output of the Solidity compiler, which extracts these comments into a machine-readable
format. 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: .. _header-doc-example:
Documentation Example Documentation Example
===================== =====================
Documentation is inserted above each ``class``, ``interface`` and 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`` Note: a ``public`` state variable is equivalent to a ``function``
for the purposes of NatSpec. for the purposes of NatSpec.
@ -106,7 +117,7 @@ Tag
``@author`` The name of the author contract, interface ``@author`` The name of the author contract, interface
``@notice`` Explain to an end user what this does contract, interface, function, public state variable, event ``@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 ``@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 ``@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 ``@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 ``@custom:...`` Custom tag, semantics is application-defined everywhere