From 18997bf83aae8159dfcaeb19a655fba3915c67b5 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Thu, 18 Feb 2016 10:27:14 +0100 Subject: Added docs/utils/__pycache__ to .gitignore when building docs with Python 3 --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 18cdd96f..260be905 100644 --- a/.gitignore +++ b/.gitignore @@ -30,6 +30,7 @@ # Build directory build/ docs/_build +docs/utils/__pycache__ # vim stuff *.swp -- cgit From 9904dc386d30b6b8a6facb43d403a03269979237 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Thu, 18 Feb 2016 10:34:23 +0100 Subject: Use code blocks for import syntax explanations for better readability --- docs/layout-of-source-files.rst | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index b795d154..3fb64635 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -17,15 +17,33 @@ 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 ----- -- cgit From 0e44481b0fa2a40c756602bd779b871ad6fcd347 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Thu, 18 Feb 2016 11:00:33 +0100 Subject: Code blocks for compiler use section --- docs/layout-of-source-files.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index 3fb64635..07934560 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -34,8 +34,7 @@ current global scope (different than in ES6 but backwards-compatible for Solidit import {symbol1 as alias, symbol2} from "filename"; -...creates new global symbols `alias` and `symbol2` which reference `symbol1` and `symbol2` -from `"filename"`, respectively. +...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: @@ -83,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 -- cgit From 688313cc5131a8aa156c2837a3629842e17ec93c Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Thu, 18 Feb 2016 11:08:20 +0100 Subject: Comment code examples --- docs/layout-of-source-files.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst index 07934560..48ecfb09 100644 --- a/docs/layout-of-source-files.rst +++ b/docs/layout-of-source-files.rst @@ -119,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 (`/** ... */`). -- cgit From 2e52170d7a31e846c30770ec0c1383c68d9b71c6 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Thu, 18 Feb 2016 11:45:15 +0100 Subject: Added examples, references to structure section --- docs/structure-of-a-contract.rst | 111 ++++++++++++++++++++++++++++++++++++--- 1 file changed, 103 insertions(+), 8 deletions(-) diff --git a/docs/structure-of-a-contract.rst b/docs/structure-of-a-contract.rst index c3683b5e..1b80b1c2 100644 --- a/docs/structure-of-a-contract.rst +++ b/docs/structure-of-a-contract.rst @@ -1,17 +1,112 @@ .. 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:`state_variables`, :ref:`functions`, +:ref:`function_modifiers`, :ref:`events`, :ref:`structs_types` and :ref:`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. +.. _state_variables: + +State Variables +=============== + +State variables are values which are permanently stored in contract storage. + +:: + + contract SimpleStorage { + uint storedData; // State variable + // ... + } + +.. _functions: + +Functions +========= + +Functions are the executable units of code within a contract. + +:: + + contract SimpleAuction { + function bid() { // Function + // ... + } + } + +.. _function_modifiers: + +Function Modifiers +================== + +Function modifiers can be used to amend the semantics of functions in a declarative way. + +:: + + contract Purchase { + address public seller; + + modifier onlySeller() { // Modifier + if (msg.sender != seller) throw; + _ + } + + function abort() onlySeller { // Modifier usage + // ... + } + } + +.. _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 + } + } + +.. _structs_types: + +Structs Types +============= + +Structs are custom defined types that can group several variables. + +:: + + contract Ballot { + struct Voter { // Struct + uint weight; + bool voted; + address delegate; + uint vote; + } + } + +.. _enum_types: + +Enum Types +========== + +Enums can be used to create custom types with a finite set of values. + +:: + + contract Purchase { + enum State { Created, Locked, Inactive } // Enum + } -- cgit From 6640e9e91897e4b030d1fea1a3c7a227c902bd26 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Fri, 19 Feb 2016 11:03:30 +0100 Subject: Changed reference naming from understore to dash separation for consistency with existing naming --- docs/structure-of-a-contract.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/structure-of-a-contract.rst b/docs/structure-of-a-contract.rst index 1b80b1c2..2916c3f1 100644 --- a/docs/structure-of-a-contract.rst +++ b/docs/structure-of-a-contract.rst @@ -7,11 +7,11 @@ Structure of a Contract *********************** Contracts in Solidity are similar to classes in object-oriented languages. -Each contract can contain declarations of :ref:`state_variables`, :ref:`functions`, -:ref:`function_modifiers`, :ref:`events`, :ref:`structs_types` and :ref:`enum_types`. +Each contract can contain declarations of :ref:`state-variables`, :ref:`functions`, +:ref:`function-modifiers`, :ref:`events`, :ref:`structs-types` and :ref:`enum-types`. Furthermore, contracts can inherit from other contracts. -.. _state_variables: +.. _state-variables: State Variables =============== @@ -40,7 +40,7 @@ Functions are the executable units of code within a contract. } } -.. _function_modifiers: +.. _function-modifiers: Function Modifiers ================== @@ -80,7 +80,7 @@ Events are convenience interfaces with the EVM logging facilities. } } -.. _structs_types: +.. _structs-types: Structs Types ============= @@ -98,7 +98,7 @@ Structs are custom defined types that can group several variables. } } -.. _enum_types: +.. _enum-types: Enum Types ========== -- cgit From acee4b7040b5b7991b540ecf59a9dd5d7fc1fb5a Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Fri, 19 Feb 2016 11:30:00 +0100 Subject: Added in-depth links for further reading to the state variable, function and function modifier overview in the structure section --- docs/control-structures.rst | 2 ++ docs/structure-of-a-contract.rst | 10 ++++++++++ docs/types.rst | 2 ++ 3 files changed, 14 insertions(+) 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/structure-of-a-contract.rst b/docs/structure-of-a-contract.rst index 2916c3f1..7b3dca60 100644 --- a/docs/structure-of-a-contract.rst +++ b/docs/structure-of-a-contract.rst @@ -25,6 +25,10 @@ State variables are values which are permanently stored in contract storage. // ... } +See the :ref:`types` section for valid state variable types and +:ref:`visibility-and-accessors` for possible choices for +visability. + .. _functions: Functions @@ -40,6 +44,10 @@ Functions are the executable units of code within a contract. } } +Functions can be called internally or externally (:ref:`function-calls`) +and have different levels of visibility (:ref:`visibility-and-accessors`) +towards other contracts. + .. _function-modifiers: Function Modifiers @@ -62,6 +70,8 @@ Function modifiers can be used to amend the semantics of functions in a declarat } } +See :ref:`modifiers` in the section on contracts for a more in-depth explanation. + .. _events: Events diff --git a/docs/types.rst b/docs/types.rst index 27ab82ff..a9cd9cfd 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -1,5 +1,7 @@ .. index:: type +.. _types: + ***** Types ***** -- cgit From 448d1601ce4c90e33ab43d896d08d34d2b870843 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Fri, 19 Feb 2016 11:47:16 +0100 Subject: Name-spacing the structure reference links for not being confused with the globally probably more used in-depth links --- docs/structure-of-a-contract.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/structure-of-a-contract.rst b/docs/structure-of-a-contract.rst index 7b3dca60..8691d33a 100644 --- a/docs/structure-of-a-contract.rst +++ b/docs/structure-of-a-contract.rst @@ -7,11 +7,11 @@ Structure of a Contract *********************** Contracts in Solidity are similar to classes in object-oriented languages. -Each contract can contain declarations of :ref:`state-variables`, :ref:`functions`, -:ref:`function-modifiers`, :ref:`events`, :ref:`structs-types` and :ref:`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: +.. _structure-state-variables: State Variables =============== @@ -29,7 +29,7 @@ See the :ref:`types` section for valid state variable types and :ref:`visibility-and-accessors` for possible choices for visability. -.. _functions: +.. _structure-functions: Functions ========= @@ -44,11 +44,11 @@ Functions are the executable units of code within a contract. } } -Functions can be called internally or externally (:ref:`function-calls`) +:ref:`function-calls` can happen internally or externally and have different levels of visibility (:ref:`visibility-and-accessors`) towards other contracts. -.. _function-modifiers: +.. _structure-function-modifiers: Function Modifiers ================== @@ -72,7 +72,7 @@ Function modifiers can be used to amend the semantics of functions in a declarat See :ref:`modifiers` in the section on contracts for a more in-depth explanation. -.. _events: +.. _structure-events: Events ====== @@ -90,7 +90,7 @@ Events are convenience interfaces with the EVM logging facilities. } } -.. _structs-types: +.. _structure-structs-types: Structs Types ============= @@ -108,7 +108,7 @@ Structs are custom defined types that can group several variables. } } -.. _enum-types: +.. _structure-enum-types: Enum Types ========== -- cgit From aec2f4879a34fc0242a3352a7e52da564fe49ab4 Mon Sep 17 00:00:00 2001 From: holgerd77 Date: Fri, 19 Feb 2016 12:05:56 +0100 Subject: Added in-depth links to function modifiers, structs and enums in structure section --- docs/contracts.rst | 2 ++ docs/structure-of-a-contract.rst | 14 ++++++++++---- docs/types.rst | 4 ++++ 3 files changed, 16 insertions(+), 4 deletions(-) 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/structure-of-a-contract.rst b/docs/structure-of-a-contract.rst index 8691d33a..f00ac968 100644 --- a/docs/structure-of-a-contract.rst +++ b/docs/structure-of-a-contract.rst @@ -53,7 +53,8 @@ towards other contracts. Function Modifiers ================== -Function modifiers can be used to amend the semantics of functions in a declarative way. +Function modifiers can be used to amend the semantics of functions in a declarative way +(see :ref:`modifiers` in contracts section). :: @@ -70,7 +71,7 @@ Function modifiers can be used to amend the semantics of functions in a declarat } } -See :ref:`modifiers` in the section on contracts for a more in-depth explanation. + in the section on contracts for a more in-depth explanation. .. _structure-events: @@ -90,12 +91,16 @@ Events are convenience interfaces with the EVM logging facilities. } } +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. +Structs are custom defined types that can group several variables (see +:ref:`structs` in types section). :: @@ -113,7 +118,8 @@ Structs are custom defined types that can group several variables. Enum Types ========== -Enums can be used to create custom types with a finite set of values. +Enums can be used to create custom types with a finite set of values (see +:ref:`enums` in types section). :: diff --git a/docs/types.rst b/docs/types.rst index a9cd9cfd..ad8784b7 100644 --- a/docs/types.rst +++ b/docs/types.rst @@ -148,6 +148,8 @@ String Literals are written with double quotes (`"abc"`). As with integer litera .. index:: enum +.. _enums: + Enums ===== @@ -357,6 +359,8 @@ Members .. index:: ! struct, ! type;struct +.. _structs: + Structs ------- -- cgit