diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/frequently-asked-questions.rst | 29 | ||||
| -rw-r--r-- | docs/layout-of-source-files.rst | 2 | ||||
| -rw-r--r-- | docs/miscellaneous.rst | 6 | ||||
| -rw-r--r-- | docs/style-guide.rst | 61 | ||||
| -rw-r--r-- | docs/using-the-compiler.rst | 24 |
5 files changed, 83 insertions, 39 deletions
diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst index f3c5b1f7..a4ef3684 100644 --- a/docs/frequently-asked-questions.rst +++ b/docs/frequently-asked-questions.rst @@ -9,35 +9,6 @@ This list was originally compiled by `fivedogit <mailto:fivedogit@gmail.com>`_. Basic Questions *************** -What is the transaction "payload"? -================================== - -This is just the bytecode "data" sent along with the request. - - -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/miscellaneous.rst b/docs/miscellaneous.rst index 017d5b81..5a6f3875 100644 --- a/docs/miscellaneous.rst +++ b/docs/miscellaneous.rst @@ -224,9 +224,9 @@ for displaying the current position in the source code inside a debugger or for breakpoint handling. Both kinds of source mappings use integer identifiers to refer to source files. -These are regular array indices into a list of source files usually called -``"sourceList"``, which is part of the combined-json and the output of -the json / npm compiler. +The identifier of a source file is stored in +``output['sources'][sourceName]['id']`` where ``output`` is the output of the +standard-json compiler interface parsed as JSON. .. note :: In the case of instructions that are not associated with any particular source file, 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 | ++-------------+-------------------------------------------+-------------------------------+ diff --git a/docs/using-the-compiler.rst b/docs/using-the-compiler.rst index 9ba6caa5..4749ef1f 100644 --- a/docs/using-the-compiler.rst +++ b/docs/using-the-compiler.rst @@ -200,15 +200,27 @@ Input Description "MyLib": "0x123123..." } } - // The following can be used to select desired outputs. - // If this field is omitted, then the compiler loads and does type checking, but will not generate any outputs apart from errors. - // The first level key is the file name and the second is the contract name, where empty contract name refers to the file itself, - // while the star refers to all of the contracts. + // The following can be used to select desired outputs based + // on file and contract names. + // If this field is omitted, then the compiler loads and does type checking, + // but will not generate any outputs apart from errors. + // The first level key is the file name and the second level key is the contract name. + // An empty contract name is used for outputs that are not tied to a contract + // but to the whole source file like the AST. + // A star as contract name refers to all contracts in the file. + // Similarly, a star as a file name matches all files. + // To select all outputs the compiler can possibly generate, use + // "outputSelection: { "*": { "*": [ "*" ], "": [ "*" ] } }" + // but note that this might slow down the compilation process needlessly. // // The available output types are as follows: - // abi - ABI + // + // File level (needs empty string as contract name): // ast - AST of all source files // legacyAST - legacy AST of all source files + // + // Contract level (needs the contract name or "*"): + // abi - ABI // devdoc - Developer documentation (natspec) // userdoc - User documentation (natspec) // metadata - Metadata @@ -281,7 +293,7 @@ Output Description // This contains the file-level outputs. In can be limited/filtered by the outputSelection settings. sources: { "sourceFile.sol": { - // Identifier (used in source maps) + // Identifier of the source (used in source maps) id: 1, // The AST object ast: {}, |