Merge pull request #399 from holgerd77/develop

Readability improvements and additional code examples for the Solidity docs

1 files changed, 119 insertions, 8 deletions

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