diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | docs/contracts.rst | 2 | ||||
| -rw-r--r-- | docs/control-structures.rst | 2 | ||||
| -rw-r--r-- | docs/layout-of-source-files.rst | 43 | ||||
| -rw-r--r-- | docs/structure-of-a-contract.rst | 127 | ||||
| -rw-r--r-- | docs/types.rst | 6 |
6 files changed, 167 insertions, 14 deletions
@@ -30,6 +30,7 @@ # Build directory build/ docs/_build +docs/utils/__pycache__ # vim stuff *.swp diff --git a/docs/contracts.rst b/docs/contracts.rst index 45391cd9..691da7fe 100644 --- a/docs/contracts.rst +++ b/docs/contracts.rst @@ -359,6 +359,8 @@ possible. .. index:: ! event +.. _events: + ****** Events ****** diff --git a/docs/control-structures.rst b/docs/control-structures.rst index 4becfcf1..989e14ba 100644 --- a/docs/control-structures.rst +++ b/docs/control-structures.rst @@ -20,6 +20,8 @@ there is in C and JavaScript, so `if (1) { ... }` is *not* valid Solidity. .. index:: ! function;call, function;internal, function;external +.. _function-calls: + Function Calls ============== diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index b795d154..48ecfb09 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -17,15 +17,32 @@ Solidity supports import statements that are very similar to those available in At a global level, you can use import statements of the following form: -`import "filename";` will import all global symbols from "filename" (and symbols imported there) into the current global scope (different than in ES6 but backwards-compatible for Solidity). +:: -`import * as symbolName from "filename";` creates a new global symbol `symbolName` whose members are all the global symbols from `"filename"`. + import "filename"; -`import {symbol1 as alias, symbol2} from "filename";` creates new global symbols `alias` and `symbol2` which reference `symbol1` and `symbal2` from `"filename"`, respectively. +...will import all global symbols from "filename" (and symbols imported there) into the +current global scope (different than in ES6 but backwards-compatible for Solidity). + +:: + + import * as symbolName from "filename"; + +...creates a new global symbol `symbolName` whose members are all the global symbols from `"filename"`. + +:: + + import {symbol1 as alias, symbol2} from "filename"; + +...creates new global symbols `alias` and `symbol2` which reference `symbol1` and `symbol2` from `"filename"`, respectively. Another syntax is not part of ES6, but probably convenient: -`import "filename" as symbolName;` is equivalent to `import * as symbolName from "filename";`. +:: + + import "filename" as symbolName; + +...is equivalent to `import * as symbolName from "filename";`. Paths ----- @@ -65,11 +82,15 @@ So as an example, if you clone `github.com/ethereum/dapp-bin/` locally to `/usr/local/dapp-bin`, you can use the following in your source file: -`import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping;` +:: + + import "github.com/ethereum/dapp-bin/library/iterable_mapping.sol" as it_mapping; and then run the compiler as -`solc github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ source.sol` +.. code-block:: shell + + solc github.com/ethereum/dapp-bin/=/usr/local/dapp-bin/ source.sol Note that solc only allows you to include files from certain directories: They have to be in the directory (or subdirectory) of one of the explicitly @@ -98,6 +119,16 @@ Comments Single-line comments (`//`) and multi-line comments (`/*...*/`) are possible. +:: + + // This is a single-line comment. + + /* + This is a + multi-line comment. + */ + + There are special types of comments called natspec comments (documentation yet to be written). These are introduced by triple-slash comments (`///`) or using double asterisks (`/** ... */`). diff --git a/docs/structure-of-a-contract.rst b/docs/structure-of-a-contract.rst index c3683b5e..f00ac968 100644 --- a/docs/structure-of-a-contract.rst +++ b/docs/structure-of-a-contract.rst @@ -1,17 +1,128 @@ .. index:: contract, state variable, function, event, struct, enum, function;modifier +.. _contract_structure: + *********************** Structure of a Contract *********************** Contracts in Solidity are similar to classes in object-oriented languages. -Each contract can contain declarations of **state variables**, **functions**, -**function modifiers**, **events**, **structs types** and **enum types**. +Each contract can contain declarations of :ref:`structure-state-variables`, :ref:`structure-functions`, +:ref:`structure-function-modifiers`, :ref:`structure-events`, :ref:`structure-structs-types` and :ref:`structure-enum-types`. Furthermore, contracts can inherit from other contracts. -* State variables are values which are permanently stored in contract storage. -* Functions are the executable units of code within a contract. -* Function modifiers can be used to amend the semantics of functions in a declarative way. -* Events are convenience interfaces with the EVM logging facilities. -* Structs are custom defined types that can group several variables. -* Enums can be used to create custom types with a finite set of values. +.. _structure-state-variables: + +State Variables +=============== + +State variables are values which are permanently stored in contract storage. + +:: + + contract SimpleStorage { + uint storedData; // State variable + // ... + } + +See the :ref:`types` section for valid state variable types and +:ref:`visibility-and-accessors` for possible choices for +visability. + +.. _structure-functions: + +Functions +========= + +Functions are the executable units of code within a contract. + +:: + + contract SimpleAuction { + function bid() { // Function + // ... + } + } + +:ref:`function-calls` can happen internally or externally +and have different levels of visibility (:ref:`visibility-and-accessors`) +towards other contracts. + +.. _structure-function-modifiers: + +Function Modifiers +================== + +Function modifiers can be used to amend the semantics of functions in a declarative way +(see :ref:`modifiers` in contracts section). + +:: + + contract Purchase { + address public seller; + + modifier onlySeller() { // Modifier + if (msg.sender != seller) throw; + _ + } + + function abort() onlySeller { // Modifier usage + // ... + } + } + + in the section on contracts for a more in-depth explanation. + +.. _structure-events: + +Events +====== + +Events are convenience interfaces with the EVM logging facilities. + +:: + + contract SimpleAuction { + event HighestBidIncreased(address bidder, uint amount); // Event + + function bid() { + // ... + HighestBidIncreased(msg.sender, msg.value); // Triggering event + } + } + +See :ref:`events` in contracts section for information on how events are declared +and can be used from within a dapp. + +.. _structure-structs-types: + +Structs Types +============= + +Structs are custom defined types that can group several variables (see +:ref:`structs` in types section). + +:: + + contract Ballot { + struct Voter { // Struct + uint weight; + bool voted; + address delegate; + uint vote; + } + } + +.. _structure-enum-types: + +Enum Types +========== + +Enums can be used to create custom types with a finite set of values (see +:ref:`enums` in types section). + +:: + + contract Purchase { + enum State { Created, Locked, Inactive } // Enum + } diff --git a/docs/types.rst b/docs/types.rst index 27ab82ff..ad8784b7 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -1,5 +1,7 @@ .. index:: type +.. _types: + ***** Types ***** @@ -146,6 +148,8 @@ String Literals are written with double quotes (`"abc"`). As with integer litera .. index:: enum +.. _enums: + Enums ===== @@ -355,6 +359,8 @@ Members .. index:: ! struct, ! type;struct +.. _structs: + Structs ------- |