diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/assembly.rst | 6 | ||||
| -rw-r--r-- | docs/bugs_by_version.json | 4 | ||||
| -rw-r--r-- | docs/contracts.rst | 2 | ||||
| -rw-r--r-- | docs/contributing.rst | 12 | ||||
| -rw-r--r-- | docs/frequently-asked-questions.rst | 54 | ||||
| -rw-r--r-- | docs/installing-solidity.rst | 4 | ||||
| -rw-r--r-- | docs/introduction-to-smart-contracts.rst | 2 | ||||
| -rw-r--r-- | docs/layout-of-source-files.rst | 2 | ||||
| -rw-r--r-- | docs/miscellaneous.rst | 6 | ||||
| -rw-r--r-- | docs/solidity-by-example.rst | 2 | ||||
| -rw-r--r-- | docs/style-guide.rst | 61 | ||||
| -rw-r--r-- | docs/types.rst | 92 | ||||
| -rw-r--r-- | docs/using-the-compiler.rst | 24 |
13 files changed, 160 insertions, 111 deletions
diff --git a/docs/assembly.rst b/docs/assembly.rst index 5bb9825a..b2f150ca 100644 --- a/docs/assembly.rst +++ b/docs/assembly.rst @@ -159,8 +159,8 @@ following list can be used as a reference of its opcodes. If an opcode takes arguments (always from the top of the stack), they are given in parentheses. Note that the order of arguments can be seen to be reversed in non-functional style (explained below). -Opcodes marked with ``-`` do not push an item onto the stack, those marked with ``*`` are -special and all others push exactly one item onto the stack. +Opcodes marked with ``-`` do not push an item onto the stack (do not return a result), +those marked with ``*`` are special and all others push exactly one item onto the stack (their "return value"). Opcodes marked with ``F``, ``H``, ``B`` or ``C`` are present since Frontier, Homestead, Byzantium or Constantinople, respectively. Constantinople is still in planning and all instructions marked as such will result in an invalid instruction exception. @@ -346,7 +346,7 @@ Literals You can use integer constants by typing them in decimal or hexadecimal notation and an appropriate ``PUSHi`` instruction will automatically be generated. The following creates code -to add 2 and 3 resulting in 5 and then computes the bitwise and with the string "abc". +to add 2 and 3 resulting in 5 and then computes the bitwise ``AND`` with the string "abc". The final value is assigned to a local variable called ``x``. Strings are stored left-aligned and cannot be longer than 32 bytes. diff --git a/docs/bugs_by_version.json b/docs/bugs_by_version.json index 658aab9c..438abbdd 100644 --- a/docs/bugs_by_version.json +++ b/docs/bugs_by_version.json @@ -616,5 +616,9 @@ "0.5.1": { "bugs": [], "released": "2018-12-03" + }, + "0.5.2": { + "bugs": [], + "released": "2018-12-19" } }
\ No newline at end of file diff --git a/docs/contracts.rst b/docs/contracts.rst index 98419430..682cb378 100644 --- a/docs/contracts.rst +++ b/docs/contracts.rst @@ -1408,7 +1408,7 @@ Interfaces are denoted by their own keyword: :: - pragma solidity >=0.4.11 <0.6.0; + pragma solidity >=0.5.0 <0.6.0; interface Token { enum TokenType { Fungible, NonFungible } diff --git a/docs/contributing.rst b/docs/contributing.rst index 43b2fd38..85816766 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -61,7 +61,7 @@ New features and bugfixes should be added to the ``Changelog.md`` file: please follow the style of previous entries, when applicable. Finally, please make sure you respect the `coding style -<https://raw.githubusercontent.com/ethereum/solidity/develop/CODING_STYLE.md>`_ +<https://github.com/ethereum/solidity/blob/develop/CODING_STYLE.md>`_ for this project. Also, even though we do CI testing, please test your code and ensure that it builds locally before submitting a pull request. @@ -83,14 +83,14 @@ internally. .. note :: - Those working in a Windows environment wanting to run the above basic sets without aleth or libz3 in Git Bash, you would have to do: ``./build/test/RelWithDebInfo/soltest.exe -- --no-ipc --no-smt``. - If you're running this in plain Command Prompt, use ``.\build\test\RelWithDebInfo\soltest.exe -- --no-ipc --no-smt``. + Those working in a Windows environment wanting to run the above basic sets without aleth or libz3 in Git Bash, you would have to do: ``./build/test/Release/soltest.exe -- --no-ipc --no-smt``. + If you're running this in plain Command Prompt, use ``.\build\test\Release\soltest.exe -- --no-ipc --no-smt``. 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 --db memorydb --test -d /tmp/testeth``. To run the actual tests, use: ``./scripts/soltest.sh --ipcpath /tmp/testeth/geth.ipc``. @@ -122,9 +122,9 @@ The CI runs additional tests (including ``solc-js`` and testing third party Soli .. note :: - You can not use some versions of ``aleth`` for testing. We suggest using + Some versions of ``aleth`` can not be used 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 f3c5b1f7..d263e0c6 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? =========================================================================================== @@ -45,31 +16,6 @@ Enums are not supported by the ABI, they are just supported by Solidity. You have to do the mapping yourself for now, we might provide some help later. -Can state variables be initialized in-line? -=========================================== - -Yes, this is possible for all types (even for structs). However, for arrays it -should be noted that you must declare them as static memory arrays. - -Examples:: - - pragma solidity >=0.4.0 <0.6.0; - - contract C { - struct S { - uint a; - uint b; - } - - S public x = S(1, 2); - string name = "Ada"; - string[4] adaArr = ["This", "is", "an", "array"]; - } - - contract D { - C c = new C(); - } - How do structs work? ==================== diff --git a/docs/installing-solidity.rst b/docs/installing-solidity.rst index 2797d8b0..c475d427 100644 --- a/docs/installing-solidity.rst +++ b/docs/installing-solidity.rst @@ -296,13 +296,13 @@ And for Windows: This latter set of instructions should result in the creation of **solidity.sln** in that build directory. Double-clicking on that file should result in Visual Studio firing up. We suggest building -**RelWithDebugInfo** configuration, but all others work. +**Release** configuration, but all others work. Alternatively, you can build for Windows on the command-line, like so: .. code-block:: bash - cmake --build . --config RelWithDebInfo + cmake --build . --config Release CMake options ============= diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst index 34ef012e..7daae06a 100644 --- a/docs/introduction-to-smart-contracts.rst +++ b/docs/introduction-to-smart-contracts.rst @@ -41,7 +41,7 @@ source code (e.g. `pragma once <https://en.wikipedia.org/wiki/Pragma_once>`_). A contract in the sense of Solidity is a collection of code (its *functions*) and data (its *state*) that resides at a specific address on the Ethereum blockchain. The line ``uint storedData;`` declares a state variable called ``storedData`` of -type ``uint`` (*u*nsigned *int*eger of *256* bits). You can think of it as a single slot +type ``uint`` (*u*\nsigned *int*\eger of *256* bits). You can think of it as a single slot in a database that can be queried and altered by calling functions of the code that manages the database. In the case of Ethereum, this is always the owning contract. And in this case, the functions ``set`` and ``get`` can be used to modify 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/solidity-by-example.rst b/docs/solidity-by-example.rst index d07452c5..0041e80c 100644 --- a/docs/solidity-by-example.rst +++ b/docs/solidity-by-example.rst @@ -743,7 +743,7 @@ In general, ECDSA signatures consist of two parameters, ``r`` and ``s``. Signatu Extracting the Signature Parameters ----------------------------------- -Signatures produced by web3.js are the concatenation of ``r``, ``s`` and ``v``, so the first step is to split these parameters apart. You can do this on the client-side, but doing it inside the smart contract means you only need to send one signature parameter rather than three. Splitting apart a byte array into component parts is a messy, so we use `inline assembly <assembly>`_ to do the job in the ``splitSignature`` function (the third function in the full contract at the end of this section). +Signatures produced by web3.js are the concatenation of ``r``, ``s`` and ``v``, so the first step is to split these parameters apart. You can do this on the client-side, but doing it inside the smart contract means you only need to send one signature parameter rather than three. Splitting apart a byte array into component parts is a mess, so we use `inline assembly <assembly>`_ to do the job in the ``splitSignature`` function (the third function in the full contract at the end of this section). Computing the Message Hash -------------------------- 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/types.rst b/docs/types.rst index f67a6d1a..08fbd7b3 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -19,6 +19,7 @@ on its type. To handle any unexpected values, you should use the :ref:`revert fu tuple with a second `bool` value denoting success. .. index:: ! value type, ! type;value +.. _value-types: Value Types =========== @@ -728,6 +729,8 @@ Another example that uses external function types:: .. index:: ! type;reference, ! reference type, storage, memory, location, array, struct +.. _reference-types: + Reference Types =============== @@ -761,14 +764,17 @@ non-persistent area where function arguments are stored, and behaves mostly like depending on the kind of variable, function type, etc., but all complex types must now give an explicit data location. +.. _data-location-assignment: + +Data location and assignment behaviour +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Data locations are not only relevant for persistency of data, but also for the semantics of assignments: -assignments between storage and memory (or from calldata) always create an independent copy. -Assignments from memory to memory only create references. This means that changes to one memory variable -are also visible in all other memory variables that refer to the same data. -Assignments from storage to a local storage variables also only assign a reference. -In contrast, all other assignments to storage always copy. Examples for this case -are assignments to state variables or to members of local variables of storage struct type, even -if the local variable itself is just a reference. + +* Assignments between ``storage`` and ``memory`` (or from ``calldata``) always create an independent copy. +* Assignments from ``memory`` to ``memory`` only create references. This means that changes to one memory variable are also visible in all other memory variables that refer to the same data. +* Assignments from ``storage`` to a local storage variable also only assign a reference. +* All other assignments to ``storage`` always copy. Examples for this case are assignments to state variables or to members of local variables of storage struct type, even if the local variable itself is just a reference. :: @@ -805,40 +811,50 @@ if the local variable itself is just a reference. Arrays ------ -Arrays can have a compile-time fixed size or they can be dynamic. -The are few restrictions for the element, it can also be -another array, a mapping or a struct. The general restrictions for -types apply, though, in that mappings can only be used in storage -and publicly-visible functions need parameters that are :ref:`ABI types <ABI>`. +Arrays can have a compile-time fixed size, or they can have a dynamic size. + +The type of an array of fixed size ``k`` and element type ``T`` is written as ``T[k]``, +and an array of dynamic size as ``T[]``. + +For example, an array of 5 dynamic arrays of ``uint`` is written as +``uint[][5]``. The notation is reversed compared to some other languages. In +Solidity, ``X[3]`` is always an array containing three elements of type ``X``, +even if ``X`` is itself an array. This is not the case in other languages such +as C. -An array of fixed size ``k`` and element type ``T`` is written as ``T[k]``, -an array of dynamic size as ``T[]``. As an example, an array of 5 dynamic -arrays of ``uint`` is ``uint[][5]`` (note that the notation is reversed when -compared to some other languages). To access the second uint in the -third dynamic array, you use ``x[2][1]`` (indices are zero-based and -access works in the opposite way of the declaration, i.e. ``x[2]`` -shaves off one level in the type from the right). +Indices are zero-based, and access is in the opposite direction of the +declaration. -Accessing an array past its end causes a revert. If you want to add -new elements, you have to use ``.push()`` or increase the ``.length`` -member (see below). +For example, if you have a variable ``uint[][5] x memory``, you access the +second ``uint`` in the third dynamic array using ``x[2][1]``, and to access the +third dynamic array, use ``x[2]``. Again, +if you have an array ``T[5] a`` for a type ``T`` that can also be an array, +then ``a[2]`` always has type ``T``. + +Array elements can be of any type, including mapping or struct. The general +restrictions for types apply, in that mappings can only be stored in the +``storage`` data location and publicly-visible functions need parameters that are :ref:`ABI types <ABI>`. + +Accessing an array past its end causes a failing assertion. You can use the ``.push()`` method to append a new element at the end or assign to the ``.length`` :ref:`member <array-members>` to change the size (see below for caveats). +method or increase the ``.length`` :ref:`member <array-members>` to add elements. Variables of type ``bytes`` and ``string`` are special arrays. A ``bytes`` is similar to ``byte[]``, but it is packed tightly in calldata and memory. ``string`` is equal to ``bytes`` but does not allow length or index access. -So ``bytes`` should always be preferred over ``byte[]`` because it is cheaper. -As a rule of thumb, use ``bytes`` for arbitrary-length raw byte data and ``string`` -for arbitrary-length string (UTF-8) data. If you can limit the length to a certain -number of bytes, always use one of ``bytes1`` to ``bytes32`` because they are much cheaper. + +You should use ``bytes`` over ``byte[]`` because it is cheaper, since ``byte[]`` adds 31 padding bytes between the elements. As a general rule, +use ``bytes`` for arbitrary-length raw byte data and ``string`` for arbitrary-length +string (UTF-8) data. If you can limit the length to a certain number of bytes, +always use one of the value types ``bytes1`` to ``bytes32`` because they are much cheaper. .. note:: If you want to access the byte-representation of a string ``s``, use ``bytes(s).length`` / ``bytes(s)[7] = 'x';``. Keep in mind that you are accessing the low-level bytes of the UTF-8 representation, - and not the individual characters! + and not the individual characters. It is possible to mark arrays ``public`` and have Solidity create a :ref:`getter <visibility-and-getters>`. -The numeric index will become a required parameter for the getter. +The numeric index becomes a required parameter for the getter. .. index:: ! array;allocating, new @@ -912,8 +928,10 @@ complications because of how arrays are passed in the ABI. .. index:: ! array;length, length, push, pop, !array;push, !array;pop -Members -^^^^^^^ +.. _array-members: + +Array Members +^^^^^^^^^^^^^ **length**: Arrays have a ``length`` member that contains their number of elements. @@ -1120,9 +1138,10 @@ assigning it to a local variable, as in ``campaigns[campaignID].amount = 0``. .. index:: !mapping +.. _mapping-types: -Mappings --------- +Mapping Types +============= You declare mapping types with the syntax ``mapping(_KeyType => _ValueType)``. The ``_KeyType`` can be any elementary type. This means it can be any of @@ -1189,7 +1208,14 @@ If ``a`` is an LValue (i.e. a variable or something that can be assigned to), th delete ------ -``delete a`` assigns the initial value for the type to ``a``. I.e. for integers it is equivalent to ``a = 0``, but it can also be used on arrays, where it assigns a dynamic array of length zero or a static array of the same length with all elements reset. For structs, it assigns a struct with all members reset. In other words, the value of ``a`` after ``delete a`` is the same as if ``a`` would be declared without assignment, with the following caveat: +``delete a`` assigns the initial value for the type to ``a``. I.e. for integers it is +equivalent to ``a = 0``, but it can also be used on arrays, where it assigns a dynamic +array of length zero or a static array of the same length with all elements set to their +initial value. ``delete a[x]`` deletes the item at index ``x`` of the array and leaves +all other elements and the length of the array untouched. This especially means that it leaves +a gap in the array. If you plan to remove items, a mapping is probably a better choice. + +For structs, it assigns a struct with all members reset. In other words, the value of ``a`` after ``delete a`` is the same as if ``a`` would be declared without assignment, with the following caveat: ``delete`` has no effect on mappings (as the keys of mappings may be arbitrary and are generally unknown). So if you delete a struct, it will reset all members that are not mappings and also recurse into the members unless they are mappings. However, individual keys and what they map to can be deleted: If ``a`` is a mapping, then ``delete a[x]`` will delete the value stored at ``x``. 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: {}, |