cerc-io/solidity
11
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

Add NatSpec documentation.

Browse Source
This commit is contained in:
William Entriken
2019-04-19 00:54:08 +02:00
committed by chriseth
parent 4312f6ec23
commit 916e151f46
4 changed files with 203 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/style-guide.rst
+2 -23
View File
@@ -1088,8 +1088,6 @@ Avoiding Naming Collisions
This convention is suggested when the desired name collides with that of a
built-in or otherwise reserved name.
.. _natspec:
*******
NatSpec
*******
@@ -1126,25 +1124,6 @@ added looks like the one below::
}
}
Natspec uses doxygen style tags with some special meaning.
If no tag is used, then the comment applies to ``@notice``.
The ``@notice`` tag is the main NatSpec tag and its audience is
users of the contract who have never seen the source code, so it should make
as little assumptions about the inner details as possible.
All tags are optional.
It is recommended that Solidity contracts are fully annontated using `NatSpec <natspec>`_ for all public interfaces (everything in the ABI).
+-------------+-------------------------------------------+-------------------------------+
| Tag | Description | Context |
+=============+===========================================+===============================+
| ``@title`` | A title that describes the contract | contract, interface |
+-------------+-------------------------------------------+-------------------------------+
| ``@author`` | The name of the author | contract, interface, function |
+-------------+-------------------------------------------+-------------------------------+
| ``@notice`` | Explanation of functionality | contract, interface, function |
+-------------+-------------------------------------------+-------------------------------+
| ``@dev`` | Any extra details | contract, interface, function |
+-------------+-------------------------------------------+-------------------------------+
| ``@param`` | Parameter type followed by parameter name | function |
+-------------+-------------------------------------------+-------------------------------+
| ``@return`` | The return value of a contract's function | function |
+-------------+-------------------------------------------+-------------------------------+
Please see the sectian about `NatSpec <natspec>`_ for a detailed explanation.