Merge pull request #7906 from ethereum/docsChange2

[DOCS] Some changes to creation, events and modifiers.

docs/contracts/creating-contracts.rst

@@ -8,16 +8,17 @@ Contracts can be created "from outside" via Ethereum transactions or from within
 
 IDEs, such as `Remix <https://remix.ethereum.org/>`_, make the creation process seamless using UI elements.
 
-Creating contracts programmatically on Ethereum is best done via using the JavaScript API `web3.js <https://github.com/ethereum/web3.js>`_.
+One way to create contracts programmatically on Ethereum is via the JavaScript API `web3.js <https://github.com/ethereum/web3.js>`_.
 It has a function called `web3.eth.Contract <https://web3js.readthedocs.io/en/1.0/web3-eth-contract.html#new-contract>`_
 to facilitate contract creation.
 
-When a contract is created, its :ref:`constructor <constructor>`  (a function declared with the ``constructor`` keyword) is executed once.
+When a contract is created, its :ref:`constructor <constructor>` (a function declared with
+the ``constructor`` keyword) is executed once.
 
 A constructor is optional. Only one constructor is allowed, which means
 overloading is not supported.
 
-After the constructor has executed, the final code of the contract is deployed to the
+After the constructor has executed, the final code of the contract is stored on the
 blockchain. This code includes all public and external functions and all functions
 that are reachable from there through function calls. The deployed code does not
 include the constructor code or internal functions only called from the constructor.
@@ -57,18 +58,20 @@ This means that cyclic creation dependencies are impossible.
             // See the next section for details.
             owner = msg.sender;
 
-            // We do an explicit type conversion from `address`
+            // We perform an explicit type conversion from `address`
             // to `TokenCreator` and assume that the type of
             // the calling contract is `TokenCreator`, there is
-            // no real way to check that.
+            // no real way to verify that.
+            // This does not create a new contract.
             creator = TokenCreator(msg.sender);
             name = _name;
         }
 
         function changeName(bytes32 newName) public {
-            // Only the creator can alter the name --
-            // the comparison is possible since contracts
-            // are explicitly convertible to addresses.
+            // Only the creator can alter the name.
+            // We compare the contract based on its
+            // address which can be retrieved by
+            // explicit conversion to address.
             if (msg.sender == address(creator))
                 name = newName;
         }
@@ -94,9 +97,9 @@ This means that cyclic creation dependencies are impossible.
             returns (OwnedToken tokenAddress)
         {
             // Create a new `Token` contract and return its address.
-            // From the JavaScript side, the return type is
-            // `address`, as this is the closest type available in
-            // the ABI.
+            // From the JavaScript side, the return type
+            // of this function is `address`, as this is
+            // the closest type available in the ABI.
             return new OwnedToken(name);
         }
 

docs/contracts/events.rst

@@ -13,12 +13,12 @@ Events are inheritable members of contracts. When you call them, they cause the
 arguments to be stored in the transaction's log - a special data structure
 in the blockchain. These logs are associated with the address of the contract,
 are incorporated into the blockchain, and stay there as long as a block is
-accessible (forever as of the Frontier and Homestead releases, but this might
+accessible (forever as of now, but this might
 change with Serenity). The Log and its event data is not accessible from within
 contracts (not even from the contract that created them).
 
-It is possible to request a simple payment verification (SPV) for logs, so if
-an external entity supplies a contract with such a verification, it can check
+It is possible to request a Merkle proof for logs, so if
+an external entity supplies a contract with such a proof, it can check
 that the log actually exists inside the blockchain. You have to supply block headers
 because the contract can only see the last 256 block hashes.
 

docs/contracts/function-modifiers.rst

@@ -6,9 +6,14 @@
 Function Modifiers
 ******************
 
-Modifiers can be used to easily change the behaviour of functions.  For example,
-they can automatically check a condition prior to executing the function. Modifiers are
-inheritable properties of contracts and may be overridden by derived contracts.
+Modifiers can be used to change the behaviour of functions in a declarative way.
+For example,
+you can use a modifier to automatically check a condition prior to executing the function.
+
+Modifiers are
+inheritable properties of contracts and may be overridden by derived contracts, but only
+if they are marked ``virtual``. For details, please see
+:ref:`Modifier Overriding <modifier-overriding>`.
 
 ::