Merge pull request #399 from holgerd77/develop

Readability improvements and additional code examples for the Solidity docs

6 files changed, 167 insertions, 14 deletions

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
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
 -------