From 144909dfb8c0ba58d54c24e68f81db47e044913f Mon Sep 17 00:00:00 2001
From: Chris Ward <chriswhward@gmail.com>
Date: Mon, 24 Sep 2018 14:10:01 +0200
Subject: Clarify creating a contract example as reported in #2661

---
 docs/contracts.rst | 33 ++++++++++++++++++++-------------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/docs/contracts.rst b/docs/contracts.rst
index d4160eac..4d439b26 100644
--- a/docs/contracts.rst
+++ b/docs/contracts.rst
@@ -50,7 +50,7 @@ This means that cyclic creation dependencies are impossible.
     pragma solidity >=0.4.22 <0.6.0;
 
     contract OwnedToken {
-        // TokenCreator is a contract type that is defined below.
+        // `TokenCreator` is a contract type that is defined below.
         // It is fine to reference it as long as it is not used
         // to create a new contract.
         TokenCreator creator;
@@ -61,14 +61,18 @@ This means that cyclic creation dependencies are impossible.
         // creator and the assigned name.
         constructor(bytes32 _name) public {
             // State variables are accessed via their name
-            // and not via e.g. this.owner. This also applies
-            // to functions and especially in the constructors,
-            // you can only call them like that ("internally"),
-            // because the contract itself does not exist yet.
+            // and not via e.g. `this.owner`. Functions can
+            // be accessed directly or through `this.f`,
+            // but the latter provides an external view
+            // to the function. Especially in the constructor,
+            // you should not access functions externally,
+            // because the function does not exist yet.
+            // See the next section for details.
             owner = msg.sender;
+
             // We do an explicit type conversion from `address`
             // to `TokenCreator` and assume that the type of
-            // the calling contract is TokenCreator, there is
+            // the calling contract is `TokenCreator`, there is
             // no real way to check that.
             creator = TokenCreator(msg.sender);
             name = _name;
@@ -86,10 +90,11 @@ This means that cyclic creation dependencies are impossible.
             // Only the current owner can transfer the token.
             if (msg.sender != owner) return;
 
-            // We also want to ask the creator if the transfer
-            // is fine. Note that this calls a function of the
-            // contract defined below. If the call fails (e.g.
-            // due to out-of-gas), the execution also fails here.
+            // We ask the creator contract if the transfer
+            // should proceed by using a function of the
+            // `TokenCreator` contract defined below. If
+            // the call fails (e.g. due to out-of-gas),
+            // the execution also fails here.
             if (creator.isTokenTransferOK(owner, newOwner))
                 owner = newOwner;
         }
@@ -100,8 +105,8 @@ This means that cyclic creation dependencies are impossible.
            public
            returns (OwnedToken tokenAddress)
         {
-            // Create a new Token contract and return its address.
-            // From the JavaScript side, the return type is simply
+            // 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.
             return new OwnedToken(name);
@@ -113,12 +118,14 @@ This means that cyclic creation dependencies are impossible.
             tokenAddress.changeName(name);
         }
 
+        // Perform checks to determine if transferring a token to the
+        // `OwnedToken` contract should proceed
         function isTokenTransferOK(address currentOwner, address newOwner)
             public
             pure
             returns (bool ok)
         {
-            // Check some arbitrary condition.
+            // Check an arbitrary condition to see if transfer should proceed
             return keccak256(abi.encodePacked(currentOwner, newOwner))[0] == 0x7f;
         }
     }
-- 
cgit v1.2.3