Merge pull request #964 from Denton-L/fix-documentation

Fix documentation

5 files changed, 38 insertions, 30 deletions

diff --git a/docs/contracts.rst b/docs/contracts.rst
index dfdcaf18..d3a89c1e 100644
--- a/docs/contracts.rst
+++ b/docs/contracts.rst
@@ -195,45 +195,47 @@ return parameter list for functions.
         uint public data;
     }
 
-An other contract ``D`` can call ``c.getData()`` to retrieve the value of data in state
-storage and is not able to call ``f``. Contract ``E`` is derived from ``C`` and can call
-``compute``.
+In the following example, ``D``, can call ``c.getData()`` to retrieve the value of
+``data`` in state storage, but is not able to call ``f``. Contract ``E`` is derived from
+``C`` and, thus, can call ``compute``.
 
 ::
 
     contract C {
+        uint private data;
+
         function f(uint a) private returns(uint b) { return a + 1; }
         function setData(uint a) { data = a; }
-        function getData() public returns(uint) {return data;}
-        function compute(uint a, uint b) internal returns (uint) { return a+b;}
-        uint private data;
+        function getData() public returns(uint) { return data; }
+        function compute(uint a, uint b) internal returns (uint) { return a+b; }
     }
 
+
     contract D {
         function readData() {
             C c = new C();
-            local = c.f(7); // error: member "f" is not visible
+            uint local = c.f(7); // error: member "f" is not visible
             c.setData(3);
-            uint local = c.getData();
-            local = c.compute(3,5); // error: member "compute" is not visible
+            local = c.getData();
+            local = c.compute(3, 5); // error: member "compute" is not visible
         }
     }
 
+
     contract E is C {
         function g() {
             C c = new C();
-            uint val = compute(3,5);  // acces to internal member (from derivated to parent contract)
+            uint val = compute(3, 5);  // acces to internal member (from derivated to parent contract)
         }
     }
 
-
 .. index:: ! accessor;function, ! function;accessor
 
 Accessor Functions
 ==================
 
 The compiler automatically creates accessor functions for
-all public state variables. For the contract given below the compiler will
+all public state variables. For the contract given below, the compiler will
 generate a function called ``data`` that does not take any
 arguments and returns a ``uint``, the value of the state
 variable ``data``. The initialization of state variables can
@@ -245,6 +247,7 @@ be done at declaration.
         uint public data = 42;
     }
 
+
     contract Caller {
         C c = new C();
         function f() {
@@ -254,8 +257,8 @@ be done at declaration.
 
 The accessor functions have external visibility. If the
 symbol is accessed internally (i.e. without ``this.``),
-it is evaluated as state variable and if it is accessed externally
-(i.e. with ``this.``), it is evaluated as function.
+it is evaluated as a state variable and if it is accessed externally
+(i.e. with ``this.``), it is evaluated as a function.
 
 ::
 
diff --git a/docs/index.rst b/docs/index.rst
index 2c983d1e..a5ab3f86 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -66,7 +66,7 @@ Discontinued:
 
 
 Solidity Tools
--------------------------------
+--------------
 
 * `Solidity REPL <https://github.com/raineorshine/solidity-repl>`_
     Try Solidity instantly with a command-line Solidity console.
diff --git a/docs/installing-solidity.rst b/docs/installing-solidity.rst
index e1322f12..f8393f2d 100644
--- a/docs/installing-solidity.rst
+++ b/docs/installing-solidity.rst
@@ -93,18 +93,18 @@ you should fork Solidity and add your personal fork as a second remote:
 .. code:: bash
 
     cd solidity
-    git remote add personal git@github.com:[username]/solidity.git
+    git remote add personal git@github.com:\<username\>/solidity.git
 
 
 Prerequisites - macOS
-----------------------
+---------------------
 
 For macOS, ensure that you have the latest version of
-`xcode installed <https://developer.apple.com/xcode/download/>`_.
+`Xcode installed <https://developer.apple.com/xcode/download/>`_.
 This contains the `Clang C++ compiler <https://en.wikipedia.org/wiki/Clang>`_, the
-`xcode IDE <https://en.wikipedia.org/wiki/Xcode>`_ and other Apple development
+`Xcode IDE <https://en.wikipedia.org/wiki/Xcode>`_ and other Apple development
 tools which are required for building C++ applications on OS X.
-If you are installing xcode for the first time, or have just installed a new
+If you are installing Xcode for the first time, or have just installed a new
 version then you will need to agree to the license before you can do
 command-line builds:
 
@@ -120,7 +120,7 @@ if you ever want to start again from scratch.
 
 
 Prerequisites - Windows
-------------------------
+-----------------------
 
 You will need to install the following dependencies for Windows builds of Solidity:
 
@@ -152,7 +152,7 @@ manual process, but is now a one-liner:
 
 Or, on Windows:
 
-.. code:: bash
+.. code:: bat
 
     scripts\install_deps.bat
 
diff --git a/docs/introduction-to-smart-contracts.rst b/docs/introduction-to-smart-contracts.rst
index fbce4244..6fcd4854 100644
--- a/docs/introduction-to-smart-contracts.rst
+++ b/docs/introduction-to-smart-contracts.rst
@@ -220,7 +220,7 @@ only the person holding the keys to the account can transfer money from it.
 Blocks
 ======
 
-One major obstacle to overcome is what, in Bitcoin terms, is called "double-spend attack":
+One major obstacle to overcome is what, in Bitcoin terms, is called a "double-spend attack":
 What happens if two transactions exist in the network that both want to empty an account,
 a so-called conflict?
 
@@ -444,13 +444,13 @@ receives the address of the new contract on the stack.
 
 .. index:: selfdestruct
 
-Selfdestruct
-============
+``selfdestruct``
+================
 
 The only possibility that code is removed from the blockchain is
-when a contract at that address performs the ``SELFDESTRUCT`` operation.
+when a contract at that address performs the ``selfdestruct`` operation.
 The remaining Ether stored at that address is sent to a designated
 target and then the storage and code is removed.
 
-Note that even if a contract's code does not contain the ``SELFDESTRUCT``
-opcode, it can still perform that operation using delegatecall or callcode.
+Note that even if a contract's code does not contain a call to ``selfdestruct``,
+it can still perform that operation using ``delegatecall`` or ``callcode``.
diff --git a/docs/types.rst b/docs/types.rst
index d6445ed9..737fbe7d 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -661,13 +661,18 @@ Explicit Conversions
 --------------------
 
 If the compiler does not allow implicit conversion but you know what you are
-doing, an explicit type conversion is sometimes possible::
+doing, an explicit type conversion is sometimes possible. Note that this may
+give you some unexpected behaviour so be sure to test to ensure that the
+result is what you want! Take the following example where you are converting
+a negative ``int8`` to a ``uint``:
+
+::
 
     int8 y = -3;
     uint x = uint(y);
 
 At the end of this code snippet, ``x`` will have the value ``0xfffff..fd`` (64 hex
-characters), which is -3 in two's complement representation of 256 bits.
+characters), which is -3 in the two's complement representation of 256 bits.
 
 If a type is explicitly converted to a smaller type, higher-order bits are
 cut off::