working on contract docs

docs/callbacks-promises-events.rst

@@ -7,10 +7,12 @@ we provide multiple ways to act on asynchronous functions.
 
 Most web3.js objects allow a callback as the last parameter, as well as returning promises to chain functions.
 
-Ethereum as a blockchain has different level of finality and therefore we return for some functions,
-like ``web3.eth.sendTransaction`` or contract methods a "promiEvent". This is a promise combined with an event emitter.
+Ethereum as a blockchain has different levels of finality and therefore needs to return multiple "stages" of an action.
+To cope with requirement we return a "promiEvent" for functions like ``web3.eth.sendTransaction`` or contract methods.
+This "promiEvent" is a promise combined with an event emitter to allow acting on different stages of action on the blockchain, like a transaction.
 
-This promiEvent works like a normal promise with added ``on`` and ``once`` functions to watch for additional events like "receipt" or "transactionHash"
+PromiEvents work like a normal promises with added ``on`` and ``once`` functions.
+This way developers can watch for additional events like on "receipt" or "transactionHash".
 
 .. code-block:: javascript
 

docs/glossary.rst

@@ -48,7 +48,7 @@ Example
     contract Test {
         bytes32 b;
 
-        function Test(){ b = 0x12345678901234567890123456789012; }
+        function Test() returns(address b){ b = 0x12345678901234567890123456789012; }
 
         event Event(uint indexed a, bytes32 b)
 
@@ -60,22 +60,22 @@ Example
     // would result in the JSON:
 
     [{
-    "type":"event",
-    "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
-    "name":"Event"
+        "type":"function",
+        "name":"foo",
+        "inputs": [{"name":"a","type":"uint256"}],
+        "outputs": [{"name":"b","type":"address"}]
+    },{
+        "type":"event",
+        "name":"Event"
+        "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
     }, {
-    "type":"event",
-    "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
-    "name":"Event2"
+        "type":"event",
+        "name":"Event2"
+        "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
     }, {
-    "type":"event",
-    "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
-    "name":"Event2"
-    }, {
-    "type":"function",
-    "inputs": [{"name":"a","type":"uint256"}],
-    "name":"foo",
-    "outputs": []
+        "type":"event",
+        "name":"Event2"
+        "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
     }]
 
 

docs/index.rst

@@ -6,7 +6,7 @@ web3.js is a collection of libraries which allow you to interact with a local or
 using a HTTP or IPC connection.
 
 The following documentation will guide you through :ref:`installing and running web3.js <adding-web3>`,
-as well as providing a :ref:`API reference documentation <api-reference>` with examples.
+as well as providing a :ref:`API reference documentation <#id1>` with examples.
 
 Contents:
 
@@ -20,7 +20,6 @@ Contents:
    callbacks-promises-events
    glossary
 
-.. _api-reference:
 
 .. toctree::
     :maxdepth: 2

docs/web3-eth-contract.rst

@@ -27,13 +27,18 @@ Creates a new contract instance with all its methods and events defined in its :
 Parameters
 ----------
 
-``Object`` - a valid provider with at least ``send``, ``on`` function
+``Object`` - jsonInterface: The json interface for the contract to instantiate
+``String`` - address (optional): The address of the smart contract to call, can be added later using `myContract.address = '0x1234..'`
+``Object`` - options (optional): The fallback options used for calls and transactions made to this contract.
+    * ``String`` - from: The address transactions should be made from.
+    * ``String`` - gasPrice: The gas price in wei to use for transactions.
+    * ``Number`` - gas: The maximum gas provided for a transaction (gas limit).
 
 -------
 Returns
 -------
 
-``undefined``
+``Object``: The contract instance with all its methods and events.
 
 -------
 Example
@@ -41,7 +46,10 @@ Example
 
 .. code-block:: javascript
 
-    web3.setProvider(new web3.providers.HttpProvider('http://localhost:8545'));
+    var myContract = new web3.eth.contract([...], '0x1234....', {
+        from: '0x1234' // default from address
+        gasPrice: '20000000000000' // default gas price in wei
+    });
 
 
 ------------------------------------------------------------------------------

docs/web3-eth.rst

@@ -19,7 +19,7 @@ When called changes the current provider for all modules.
 Parameters
 ----------
 
-``Object`` - a valid provider with at least ``send``, ``on`` function
+``Object`` - myProvider : a valid provider with at least ``send``, ``on`` function
 
 -------
 Returns

docs/web3-utils.rst

@@ -20,7 +20,7 @@ When called changes the current provider for all modules.
 Parameters
 ----------
 
-``Object`` - a valid provider with at least ``send``, ``on`` function
+``Object`` - myProvider : a valid provider with at least ``send``, ``on`` function
 
 -------
 Returns

docs/web3.rst

@@ -19,7 +19,7 @@ Contains the version of the ``web3`` container object.
 Returns
 -------
 
-``String`` - The current version.
+``String``: The current version.
 
 -------
 Example
@@ -46,7 +46,7 @@ Will return an object with different available providers to use when instantiati
 Returns
 -------
 
-``Object`` - A list of providers.
+``Object``: A list of providers.
 
 -------
 Example
@@ -76,7 +76,7 @@ When called changes the current provider for all modules.
 Parameters
 ----------
 
-``Object`` - a valid provider with at least ``send``, ``on`` function
+``Object`` - myProvider : a valid provider with at least ``send``, ``on`` function
 
 -------
 Returns
@@ -109,7 +109,7 @@ Will return the current provider, otherwise ``null``.
 Returns
 -------
 
-``Object`` - The current provider set or ``null``;
+``Object``: The current provider set or ``null``;
 
 -------
 Example