diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/contributing.rst | 4 | ||||
| -rw-r--r-- | docs/frequently-asked-questions.rst | 23 | ||||
| -rw-r--r-- | docs/layout-of-source-files.rst | 2 | ||||
| -rw-r--r-- | docs/style-guide.rst | 61 |
4 files changed, 64 insertions, 26 deletions
diff --git a/docs/contributing.rst b/docs/contributing.rst index 12dea7d1..47d0d070 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -90,7 +90,7 @@ The option ``--no-smt`` disables the tests that require ``libz3`` and ``--no-ipc`` disables those that require ``aleth``. If you want to run the ipc tests (that test the semantics of the generated code), -you need to install `aleth <https://github.com/ethereum/cpp-ethereum/releases/download/solidityTester/aleth_2018-06-20_artful>`_ and run it in testing mode: ``aleth --test -d /tmp/testeth`` (make sure to rename it). +you need to install `aleth <https://github.com/ethereum/aleth/releases/download/v1.5.0-alpha.7/aleth-1.5.0-alpha.7-linux-x86_64.tar.gz>`_ and run it in testing mode: ``aleth --test -d /tmp/testeth`` (make sure to rename it). To run the actual tests, use: ``./scripts/soltest.sh --ipcpath /tmp/testeth/geth.ipc``. @@ -124,7 +124,7 @@ The CI runs additional tests (including ``solc-js`` and testing third party Soli You can not use some versions of ``aleth`` for testing. We suggest using the same version that the Solidity continuous integration tests use. - Currently the CI uses ``d661ac4fec0aeffbedcdc195f67f5ded0c798278`` of ``aleth``. + Currently the CI uses version ``1.5.0-alpha.7`` of ``aleth``. Writing and running syntax tests -------------------------------- diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst index e58db133..a4ef3684 100644 --- a/docs/frequently-asked-questions.rst +++ b/docs/frequently-asked-questions.rst @@ -9,29 +9,6 @@ This list was originally compiled by `fivedogit <mailto:fivedogit@gmail.com>`_. Basic Questions *************** -Create a contract that can be killed and return funds -===================================================== - -First, a word of warning: Killing contracts sounds like a good idea, because "cleaning up" -is always good, but as seen above, it does not really clean up. Furthermore, -if Ether is sent to removed contracts, the Ether will be forever lost. - -If you want to deactivate your contracts, it is preferable to **disable** them by changing some -internal state which causes all functions to throw. This will make it impossible -to use the contract and ether sent to the contract will be returned automatically. - -Now to answering the question: Inside a constructor, ``msg.sender`` is the -creator. Save it. Then ``selfdestruct(creator);`` to kill and return funds. - -`example <https://github.com/fivedogit/solidity-baby-steps/blob/master/contracts/05_greeter.sol>`_ - -Note that if you ``import "mortal"`` at the top of your contracts and declare -``contract SomeContract is mortal { ...`` and compile with a compiler that already -has it (which includes `Remix <https://remix.ethereum.org/>`_), then -``kill()`` is taken care of for you. Once a contract is "mortal", then you can -``contractname.kill.sendTransaction({from:eth.coinbase})``, just the same as my -examples. - If I return an ``enum``, I only get integer values in web3.js. How to get the named values? =========================================================================================== diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index ad84b200..fa36fc6a 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -267,7 +267,7 @@ Single-line comments (``//``) and multi-line comments (``/*...*/``) are possible (these are NEL, LS and PS), it will lead to a parser error. Additionally, there is another type of comment called a natspec comment, -for which the documentation is not yet written. They are written with a +which is detailed in the :ref:`style guide<natspec>`. 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 diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 68fee871..bf1be93e 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -1093,3 +1093,64 @@ General Recommendations ======================= TODO + +.. _natspec: + +******* +NatSpec +******* + +Solidity contracts can have a form of comments that are the basis of the +Ethereum Natural Language Specification Format. + +Add comments above functions or contracts following `doxygen <http://www.doxygen.nl>`_ notation +of one or multiple lines starting with `///` or a +multiline comment starting with `/**` and ending with `*/`. + +For example, the contract from `a simple smart contract <simple-smart-contract>`_ with the comments +added looks like the one below:: + + pragma solidity >=0.4.0 <0.6.0; + + /// @author The Solidity Team + /// @title A simple storage example + contract SimpleStorage { + uint storedData; + + /// Store `x`. + /// @param x the new value to store + /// @dev stores the number in the state variable `storedData` + function set(uint x) public { + storedData = x; + } + + /// Return the stored value. + /// @dev retrieves the value of the state variable `storedData` + /// @return the stored value + function get() public view returns (uint) { + return storedData; + } + } + +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. + ++-------------+-------------------------------------------+-------------------------------+ +| 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 | ++-------------+-------------------------------------------+-------------------------------+ |