Documentation fixes

Signed-off-by: Sean Young <sean@mess.org>

docs/conf.py

@@ -26,8 +26,8 @@ def setup(sphinx):
 # -- Project information -----------------------------------------------------
 
 project = 'Solang Solidity Compiler'
-copyright = '2019 - 2021 Sean Young <sean@mess.org>'
-author = 'Sean Young <sean@mess.org>'
+copyright = '2019 - 2022 Solang Maintainers'
+author = 'Sean Young <sean@mess.org>, Cyrill Leutwiler <bigcyrill@hotmail.com>, Lucas Steuernagel <lucas.tnagel@gmail.com>'
 
 # The full version, including alpha/beta/rc tags
 release = os.popen('git describe --tags').readline().strip()

docs/extension.rst

@@ -23,18 +23,7 @@ Both the Visual Studio Code extension code and the language server were develope
 Solidity Language flavour
 -------------------------
 
-The Solidity language flavour depends on what target you are compiling for. For
-example:
-
-* Ethereum style address literals like ``0xE0f5206BBD039e7b0592d8918820024e2a7437b9`` are
-  not supported on Substrate or Solana, but are supported for EVM.
-* On Substrate and Solana, base58 style encoded address literals like
-  ``address"5GBWmgdFAMqm8ZgAHGobqDqX6tjLxJhv53ygjNtaaAn3sjeZ"`` are supported, but
-  not with EVM.
-* On Solana, there is special builtin import file called ``'solana'`` available.
-* Different blockchains offer different builtins. See the :ref:`builtins documentation <builtins>`.
-* See :ref:`language-status` for compatiblity with Ethereum Solidity (solc)
-* There are many more differences, which are noted throughout the documentation.
+The Solidity language flavour depends on what target you are compiling for, see :ref:`language-status` for a brief overview.
 
 You can choose the between the following targets:
 
@@ -48,7 +37,7 @@ evm
    Solidity for any EVM based chain like Ethereum
 
 Note that the language server has support for EVM, but Hyperledger Solang does
-not support compiling for EVM (yet).
+not support compiling for EVM.
 
 Using the extension
 -------------------

docs/index.rst

@@ -14,13 +14,13 @@ Welcome to the Solang Solidity Compiler. Using Solang, you can compile smart con
 `Solana <https://www.solana.com/>`_ and
 `Parity Substrate <https://substrate.io/>`_. It uses the
 `llvm <https://www.llvm.org/>`_ compiler framework to produce WebAssembly
-(wasm) or BPF contract code. As result, the output is highly optimized, which saves you in gas costs.
+(WASM) or BPF contract code. As result, the output is highly optimized, which saves you in gas costs
+or compute units.
 
 Solang aims for source file compatibility with the Ethereum EVM Solidity compiler,
 version 0.8. Where differences exists, this is noted in the language documentation.
 The source code repository can be found on `github <https://github.com/hyperledger/solang>`_
-and we have a `channel #solang on Hyperledger Discord <https://discord.gg/jhn4rkqNsT>`_, and
-a `channel #solang-solidity-compiler on Solana Discord <https://discord.gg/TmE2Ek5ZbW>`_.
+and we have a `channel #solang on Hyperledger Discord <https://discord.gg/jhn4rkqNsT>`_.
 
 Contents
 ========

docs/installing.rst

@@ -4,7 +4,7 @@ Installing Solang
 The Solang compiler is a single binary. It can be installed in different ways, listed below.
 
 1. :ref:`Download from Homebrew <download-brew>` (MacOS only)
-2. :ref:`Download pre-compiled binaries <download-binaries>`
+2. :ref:`Download binaries <download-binaries>`
 3. :ref:`Download from a Docker container <download-docker>`
 4. :ref:`Build using Dockerfile <build-dockerfile>`
 5. :ref:`Build from source <build-source>`
@@ -14,7 +14,7 @@ The Solang compiler is a single binary. It can be installed in different ways, l
 Option 1: Download from Brew
 ----------------------------
 
-Solang is available on Brew via a private tap. Currently, this works only for MacOS systems, both Intel and Apple Silicon.
+Solang is available on Brew via a private tap. This works only for MacOS systems, both Intel and Apple Silicon.
 To install Solang via Brew, run the following command:
 
 .. code-block:: text
@@ -23,8 +23,8 @@ To install Solang via Brew, run the following command:
 
 .. _download-binaries:
 
-Option 2: Download release binaries
------------------------------------
+Option 2: Download binaries
+---------------------------
 
 There are binaries available on github releases:
 
@@ -34,6 +34,9 @@ There are binaries available on github releases:
 - `MacOS intel <https://github.com/hyperledger/solang/releases/download/v0.1.13/solang-mac-intel>`_
 - `MacOS arm <https://github.com/hyperledger/solang/releases/download/v0.1.13/solang-mac-arm>`_
 
+Download the file and save it somewhere in your ``$PATH``, for example the bin directory in your home directory. If the
+path you use is not already in ``$PATH``, then you need to add it yourself.
+
 On MacOS, remember to give execution permission to the file and remove it from quarantine by executing the following commands:
 
 .. code-block:: bash
@@ -85,7 +88,7 @@ Option 5: Build Solang from source
 ----------------------------------
 
 In order to build Solang from source, you will need rust 1.63.0 or higher,
-and a build of LLVM based on the Solana LLVM tree. There are a few patches which are not upstream yet.
+and a build of LLVM based on the Solana LLVM tree. There are a few LLVM patches required that are not upstream yet.
 First, follow the steps below for installing LLVM and then proceed from there.
 
 If you do not have the correct version of rust installed, go to `rustup <https://rustup.rs/>`_.
@@ -106,13 +109,13 @@ _____________________________________
 
 Solang needs a build of
 `LLVM with some extra patches <https://github.com/solana-labs/llvm-project/>`_.
-These patches make it possible to generate code for Solana, and fixes some
+These patches make it possible to generate code for Solana, and fixes
 concurrency issues in the lld linker.
 
 You can either download the pre-built libraries from
 `github <https://github.com/hyperledger/solang/releases/tag/v0.1.13>`_
-or :ref:`build your own from source <llvm-from-source>`. After that, you need to add the ``bin`` directory to your
-path, so that the build system of Solang can find the correct version of LLVM to use.
+or :ref:`build your own from source <llvm-from-source>`. After that, you need to add the ``bin`` of your
+LLVM directory to your path, so that the build system of Solang can find the correct version of LLVM to use.
 
 Linux
 ~~~~~

docs/language/contracts.rst

@@ -24,15 +24,15 @@ If a constructor has arguments, they must be supplied when the contract is deplo
 If a contract is expected to receive value on instantiation, the constructor should be declared ``payable``.
 
 .. note::
-    On Substrate, constructors have a name. Solang allows naming constructors in the substrate target:
+    Solang allows naming constructors in the Substrate target:
 
     .. code-block:: solidity
- 
+
         contract Foo {
             constructor my_new_foo() {}
         }
 
-    Unnamed constructors will be called ``new`` in the metadata.
+    Constructors without a name will be called ``new`` in the metadata.
 
     Note that constructor names are only used in the generated metadata. For contract instantiation,
     the correct constructor matching the function signature will be selected automatically.
@@ -94,6 +94,9 @@ The constructor should be declared ``payable`` for this to work.
     If no value is specified, then on Parity Substrate the minimum balance (also know as the
     existential deposit) is sent.
 
+.. note::
+    On Solana, this functionality is not available.
+
 Setting the salt, gas, and space for the new contract
 _____________________________________________________
 

docs/language/expressions.rst

@@ -47,10 +47,6 @@ line argument is specified. No overflow checking is generated in `unchecked` blo
         }
     }
 
-.. warning::
-
-  Overflow checking for types larger than ``int64`` (e.g. ``uint128``) is not implemented yet.
-
 Bitwise operators
 _________________
 
@@ -114,9 +110,9 @@ a bool.
 Increment and Decrement operators
 _________________________________
 
-The post-increment and pre-increment operators are implemented like you would expect. So, ``a++``
-evaluates to the value of ``a`` before incrementing, and ``++a`` evaluates to value of ``a``
-after incrementing.
+The post-increment and pre-increment operators are implemented by reading the variable's
+value before or after modifying it. ``i++``returns the value of ``i`` before incrementing,
+and ``++i`` returns the value of ``i`` after incrementing.
 
 this
 ____
@@ -149,6 +145,11 @@ this only works with public functions.
         }
     }
 
+.. note::
+
+    On Solana, this gives the account of contract data. If you want the account with the program code,
+    use ``tx.program_id``.
+
 type(..) operators
 __________________
 
@@ -177,10 +178,10 @@ an interface at runtime, which can be used to write a `supportsInterface()` func
 in the EIP.
 
 The contract code for a contract, i.e. the binary WebAssembly or BPF, can be retrieved using the
-``type(c).creationCode`` and ``type(c).runtimeCode`` fields, as ``bytes``. In Ethereum,
-the constructor code is in the ``creationCode`` WebAssembly and all the functions are in
-the ``runtimeCode`` WebAssembly or BPF. Parity Substrate has a single WebAssembly code for both,
-so both fields will evaluate to the same value.
+``type(c).creationCode`` and ``type(c).runtimeCode`` fields, as ``bytes``. On EVM,
+the constructor code is in the ``creationCode`` and all the functions are in
+the ``runtimeCode``. Parity Substrate and Solana use the same
+code for both, so those fields will evaluate to the same value.
 
 .. code-block:: solidity
 
@@ -227,7 +228,8 @@ Casting
 _______
 
 Solidity is very strict about the sign of operations, and whether an assignment can truncate a
-value. You can force the compiler to accept truncations or differences in sign by adding a cast.
+value. You can force the compiler to accept truncations or sign changes by adding an
+explicit cast.
 
 Some examples:
 
@@ -248,7 +250,7 @@ The compiler will say:
    implicit conversion would truncate from int256 to int64
 
 Now you can work around this by adding a cast to the argument to return ``return int64(bar);``,
-however it would be much nicer if the return value matched the argument. Instead, implement
+however it is idiomatic to match the return value type with the argument type. Instead, implement
 multiple overloaded abs() functions, so that there is an ``abs()`` for each type.
 
 It is allowed to cast from a ``bytes`` type to ``int`` or ``uint`` (or vice versa), only if the length
@@ -281,4 +283,5 @@ A similar example for truncation:
   bytes4 start2 = bytes4(bytes8(start));
   // first cast, then truncate as bytes: start2 = hex"dead"
 
-Since ``byte`` is array of one byte, a conversion from ``byte`` to ``uint8`` requires a cast.
+Since ``byte`` is an array of one byte, a conversion from ``byte`` to ``uint8`` requires a cast. This is
+because ``byte`` is an alias for ``bytes1``.

docs/language/imports.rst

@@ -2,7 +2,7 @@ Imports
 =======
 
 The ``import`` directive is used to import items from other Solidity files. This can be useful to
-keep a single definition in one file, which can be used in other files. For example
+keep a single definition in one file, which can be used in multiple other files. For example,
 you could have an interface in one source file, which several contracts implement or use
 which are in other files. Solidity imports are somewhat similar to JavaScript ES6, however
 there is no export statement, or default export.
@@ -15,10 +15,11 @@ another file.
 - enums definitions
 - event definitions
 - global functions
+- free standing functions
 - contracts, including abstract contract, libraries, and interfaces
 
 There are a few different flavours of import. You can specify if you want everything imported,
-or a just a select few. You can also rename the imports. The following directive imports only
+or just a select few items. You can also rename the imports. The following directive imports only
 `foo` and `bar`:
 
 .. code-block:: solidity
@@ -42,7 +43,7 @@ the command line option ``--importmap @openzeppelin=/opt/openzeppelin-contracts/
 
 .. code-block:: solidity
 
-    import "openzeppelin/interfaces/IERC20.sol";
+    import "@openzeppelin/interfaces/IERC20.sol";
 
 will automatically map to `/opt/openzeppelin-contracts/contracts/interfaces/IERC20.sol`.
 
@@ -67,7 +68,7 @@ there can be no naming conflict.
 
     import "defines.sol" as defs;
 
-This also has a slightly more baroque syntax, which does exactly the same.
+There is another syntax, which does exactly the same.
 
 .. code-block:: solidity
 

docs/language/introduction.rst

@@ -18,6 +18,8 @@ Differences:
 
 - libraries are always statically linked into the contract code
 - Solang generates WebAssembly or BPF rather than EVM.
+- Packed encoded uses little endian encoding, as WASM and BPF are little endian
+  virtual machines.
 
 Unique features to Solang:
 
@@ -28,3 +30,12 @@ Unique features to Solang:
 - Base contracts can be declared in any order
 - There is a ``print()`` function for debugging
 - Strings can be formatted with python style format string, which is useful for debugging: ``print("x = {}".format(x));``
+- Ethereum style address literals like ``0xE0f5206BBD039e7b0592d8918820024e2a7437b9`` are
+  not supported on Substrate or Solana, but are supported for EVM.
+- On Substrate and Solana, base58 style encoded address literals like
+  ``address"5GBWmgdFAMqm8ZgAHGobqDqX6tjLxJhv53ygjNtaaAn3sjeZ"`` are supported, but
+  not with EVM.
+- On Solana, there is special builtin import file called ``'solana'`` available.
+- On Substrate, there is special builtin import file called ``'substrate'`` available.
+- Different blockchains offer different builtins. See the :ref:`builtins documentation <builtins>`.
+- There are many more differences, which are noted throughout the documentation.

docs/language/pragmas.rst

@@ -39,5 +39,5 @@ Solang takes a different view:
    but of the build environment. No other language set the compiler version in
    the source code.
 
-If anything some languages allow conditional compilation based on the compiler
+If anything, some languages allow conditional compilation based on the compiler
 version, which is much more useful.

docs/language/statements.rst

@@ -2,8 +2,8 @@ Statements
 ==========
 
 In functions, you can declare variables in code blocks. If the name is the same as
-an existing function, enum type, or another variable, then the compiler will generate a
-warning as the original item is no longer accessible.
+an existing function, enum type, or another variable, then the compiler will shadow
+the original item and generate a warning as it is no longer accessible.
 
 .. code-block:: solidity
 
@@ -56,12 +56,25 @@ condition must evaluate to a ``bool`` value.
 The statements enclosed by ``{`` and ``}`` (commonly known as a *block*) are executed only if
 the condition evaluates to true.
 
+You can optionally add an ``else`` block which is executed only if the condition evaluates to false.
+
+.. code-block:: solidity
+
+    function foo(uint32 n) private {
+        if (n > 10) {
+            // do something
+        } else {
+            // do something different
+        }
+    }
+
+
 While statement
 _______________
 
 Repeated execution of a block can be achieved using ``while``. It syntax is similar to ``if``,
 however the block is repeatedly executed until the condition evaluates to false.
-If the condition is not true on first execution, then the loop is never executed:
+If the condition is not true on first execution, then the loop body is never executed:
 
 .. code-block:: solidity
 
@@ -90,6 +103,9 @@ cease execution of the block, but repeat the loop if the condition still holds:
               // cease execution of this while loop and jump to the "n = 102" statement
               break;
           }
+
+          // only executed if both if statements were false
+          print("neither true");
       }
 
       n = 102;
@@ -99,7 +115,7 @@ Do While statement
 __________________
 
 A ``do { ... } while (condition);`` statement is much like the ``while (condition) { ... }`` except
-that the condition is evaluated after execution the block. This means that the block is executed
+that the condition is evaluated after executing the block. This means that the block is always executed
 at least once, which is not true for ``while`` statements:
 
 .. code-block:: solidity
@@ -209,9 +225,12 @@ of elements in both sides of the conditional must match the left hand side of th
 Try Catch Statement
 ___________________
 
+Solidity's try-catch statement can only be used with external calls or constructor calls using ``new``. The
+compiler will refuse to compile any other expression.
+
 Sometimes execution gets reverted due to a ``revert()`` or ``require()``. These types of problems
 usually cause the entire transaction to be aborted. However, it is possible to catch
-some of these problems and continue execution.
+some of these problems in the caller and continue execution.
 
 This is only possible for contract instantiation through new, and external function calls.
 An internal function cannot be called from a try catch statement. Not all problems can be handled,

docs/language/types.rst

@@ -51,7 +51,7 @@ The largest value an ``uint8`` can hold is (2 :superscript:`8`) - 1 = 255. So, t
 
 .. code-block:: none
 
-    literal 300 is too large to fit into type 'uint8'
+    value 300 does not fit into type uint8
 
 .. tip::
 
@@ -64,7 +64,7 @@ The largest value an ``uint8`` can hold is (2 :superscript:`8`) - 1 = 255. So, t
   calculations, which are expensive.
 
   WebAssembly or BPF do not support this. As a result that Solang has to emulate larger types with
-  many instructions, resulting in larger contract code and higher gas cost.
+  many instructions, resulting in larger contract code and higher gas cost or compute units.
 
 Fixed Length byte arrays
 ________________________
@@ -125,8 +125,8 @@ Address and Address Payable Type
 ________________________________
 
 The ``address`` type holds the address of an account. The length of an ``address`` type depends on
-the target being compiled for. On ewasm, an address is 20 bytes. Solana and Substrate have an address
-length of 32 bytes. The format of an address literal depends on what target you are building for. On ewasm,
+the target being compiled for. On EVM, an address is 20 bytes. Solana and Substrate have an address
+length of 32 bytes. The format of an address literal depends on what target you are building for. On EVM,
 ethereum addresses can be specified with a particular hexadecimal number.
 
 .. code-block:: solidity
@@ -330,13 +330,14 @@ in any contract without the prefix.
     }
 
 The `users` struct contains an array of `user`, which is another struct. The `users` struct is
-defined in contract `db`, and can be used in another contract with the type name `db.users`. Astute
-readers may have noticed that the `db.users` struct is used before it is declared. In Solidity,
-types can be always be used before their declaration, or before they are imported.
+defined in contract `db`, and can be used in another contract with the type name `db.users`.
+Notice that the `db.users` struct type is used in the function `authenticate` before it is declared. In Solidity,
+types can be always be used before their declaration, or even before the ``import`` directive.
 
 Structs can be contract storage variables. Structs in contract storage can be assigned to structs
 in memory and vice versa, like in the *set_card1()* function. Copying structs between storage
-and memory is expensive; code has to be generated for each field and executed.
+and memory is expensive; code has to be generated and executed for each field. In the *set_card1* function,
+the following is done:
 
 - The function argument ``c`` has to ABI decoded (1 copy + decoding overhead)
 - The ``card1`` has to load from contract storage (1 copy + contract storage overhead)
@@ -372,13 +373,6 @@ visible in the caller as well.
       }
   }
 
-.. note::
-
-  In the Ethereum Foundation Solidity compiler, you need to add ``pragma experimental ABIEncoderV2;``
-  to use structs as return values or function arguments in public functions. The default ABI encoder
-  of Solang can handle structs, so there is no need for this pragma. The Solang compiler ignores
-  this pragma if present.
-
 Fixed Length Arrays
 ___________________
 
@@ -433,7 +427,7 @@ be reflected in the current function. For example:
         }
 
         function foo() private {
-            int8[4] val = [ int8(1), 2, 3, 4 ];
+            int8[4] val = [ 1, 2, 3, 4 ];
 
             set_2(val);
 
@@ -442,6 +436,8 @@ be reflected in the current function. For example:
         }
     }
 
+On Solang, it is not necessary to cast the first element of the array literal.
+
 .. note::
 
   In Solidity, an fixed array of 32 bytes (or smaller) can be declared as ``bytes32`` or
@@ -450,8 +446,9 @@ be reflected in the current function. For example:
   32 bytes. However, since ``bytes32`` is a primitive in itself, this will only be 32
   bytes when ABI encoded.
 
-  In Substrate, the `SCALE <https://docs.substrate.io/reference/scale-codec/>`_
-  encoding uses 32 bytes for both types.
+  On Substrate, the `SCALE <https://docs.substrate.io/reference/scale-codec/>`_
+  encoding uses 32 bytes for both types. Similarly, the `borsh encoding <https://borsh.io/>`_
+  used on Solana uses 32 bytes for both types.
 
 Dynamic Length Arrays
 _____________________
@@ -462,7 +459,7 @@ on whether they are contract storage variables or stored in memory.
 
 Memory dynamic arrays must be allocated with ``new`` before they can be used. The ``new``
 expression requires a single unsigned integer argument. The length can be read using
-``length`` member variable. Once created, the length of the array cannot be changed.
+``length`` member variable.
 
 .. code-block:: solidity
 
@@ -509,7 +506,7 @@ methods.
     }
 
 Calling the method ``pop()`` on an empty array is an error and contract execution will abort,
-just like when you access an element beyond the end of an array.
+just like when accessing an element beyond the end of an array.
 
 ``push()`` without any arguments returns a storage reference. This is only available for types
 that support storage references (see below).
@@ -657,7 +654,7 @@ Mappings are declared with ``mapping(keytype => valuetype)``, for example:
 
 If you access a non-existing field on a mapping, all the fields will read as zero. So, it
 is common practise to have a boolean field called ``exists``. Since mappings are not iterable,
-it is not possible to do a ``delete`` on an mapping, but an entry can be deleted.
+it is not possible to ``delete`` an entire mapping itself, but individual mapping entries can be deleted.
 
 .. note::
 
@@ -680,7 +677,7 @@ ______________
 
 In Solidity, other smart contracts can be called and created. So, there is a type to hold the
 address of a contract. This is in fact simply the address of the contract, with some syntax
-sugar for calling functions it.
+sugar for calling functions on it.
 
 A contract can be created with the new statement, followed by the name of the contract. The
 arguments to the constructor must be provided.

docs/running.rst

@@ -29,24 +29,24 @@ followed by one or more solidity source filenames.
 
 Options:
 
--v, \\-\\-verbose
+-v, \-\-verbose
   Make the output more verbose. The compiler tell you what contracts have been
   found in the source, and what files are generated. Without this option Solang
   will be silent if there are no errors or warnings.
 
-\\-\\-target *target*
+\-\-target *target*
   This takes one argument, which can either be ``solana`` or ``substrate``. The target
   must be specified.
 
-\\-\\-address\\-length *length-in-bytes*
+\-\-address\-length *length-in-bytes*
   Change the default address length on Substrate. By default, Substate uses an address type of 32 bytes. This option
   is ignored for any other target.
 
-\\-\\-value\\-length *length-in-bytes*
+\-\-value\-length *length-in-bytes*
   Change the default value length on Substrate. By default, Substate uses an value type of 16 bytes. This option
   is ignored for any other target.
 
--o, \\-\\-output *directory*
+-o, \-\-output *directory*
   This option takes one argument, which is the directory where output should
   be saved. The default is the current directory.
 
@@ -54,25 +54,25 @@ Options:
   This takes one argument, which can either be ``none``, ``less``, ``default``,
   or ``aggressive``. These correspond to llvm optimization levels.
 
-\\-\\-importpath *directory*
+\-\-importpath *directory*
   When resolving ``import`` directives, search this directory. By default ``import``
   will only search the current directory. This option can be specified multiple times
   and the directories will be searched in the order specified.
 
-\\-\\-importmap *map=directory*
+\-\-importmap *map=directory*
   When resolving ``import`` directives, if the first part of the path matches *map*,
   search the directory provided for the file. This option can be specified multiple times
   with different values for map.
 
-\\-\\-help, -h
+\-\-help, -h
   This displays a short description of all the options
 
-\\-\\-standard-json
+\-\-standard-json
   This option causes Solang to emulate the behaviour of Solidity
   `standard json output <https://solidity.readthedocs.io/en/v0.5.13/using-the-compiler.html#output-description>`_. No output files are written, all the
   output will be in json on stdout.
 
-\\-\\-emit *phase*
+\-\-emit *phase*
   This option is can be used for debugging Solang itself. This is used to
   output early phases of compilation.
 
@@ -97,22 +97,22 @@ Options:
   object
     Output wasm object file; this is the contract before final linking.
 
-\\-\\-no\\-constant\\-folding
+\-\-no\-constant\-folding
    Disable the :ref:`constant-folding` codegen optimization
 
-\\-\\-no\\-strength\\-reduce
+\-\-no\-strength\-reduce
    Disable the :ref:`strength-reduce` codegen optimization
 
-\\-\\-no\\-dead\\-storage
+\-\-no\-dead\-storage
    Disable the :ref:`dead-storage` optimization
 
-\\-\\-no\\-vector\\-to\\-slice
+\-\-no\-vector\-to\-slice
    Disable the :ref:`vector-to-slice` optimization
 
-\\-\\-no\\-cse
+\-\-no\-cse
    Disable the :ref:`common-subexpression-elimination` optimization
 
-\\-\\-log\\-api\\-return\\-codes
+\-\-log\-api\-return\-codes
    Disable the :ref:`common-subexpression-elimination` optimization
 
 Generating Documentation Usage
@@ -129,37 +129,37 @@ followed by one or more solidity source filenames.
 
 Options:
 
-\\-\\-target *target*
+\-\-target *target*
   This takes one argument, which can either be ``solana`` or ``substrate``. The target
   must be specified.
 
-\\-\\-address\\-length *length-in-bytes*
+\-\-address\-length *length-in-bytes*
   Change the default address length on Substrate. By default, Substate uses an address type of 32 bytes. This option
   is ignored for any other target.
 
-\\-\\-value\\-length *length-in-bytes*
+\-\-value\-length *length-in-bytes*
   Change the default value length on Substrate. By default, Substate uses an value type of 16 bytes. This option
   is ignored for any other target.
 
-\\-\\-importpath *directory*
+\-\-importpath *directory*
   When resolving ``import`` directives, search this directory. By default ``import``
   will only search the current directory. This option can be specified multiple times
   and the directories will be searched in the order specified.
 
-\\-\\-importmap *map=directory*
+\-\-importmap *map=directory*
   When resolving ``import`` directives, if the first part of the path matches *map*,
   search the directory provided for the file. This option can be specified multiple times
   with different values for map.
 
-\\-\\-help, -h
+\-\-help, -h
   This displays a short description of all the options
 
 .. _idl_command:
 
-Using the idl command
-_____________________
+Generate Solidity interface from IDL
+____________________________________
 
-This command converts Anchor IDL into Solidity import files in order to call
+This command converts Anchor IDL into Solidity import files, so they can be used to call
 Anchor Programs from Solidity.
 
   solang idl [--output DIR] [IDLFILE]...
@@ -169,17 +169,17 @@ for an example of how to use this.
 
 .. note::
 
-  There is only support for Solana at this time.
+  There is only supported on Solana.
 
-Running Solang using container
-______________________________
+Running Solang using a container
+________________________________
 
 First pull the last Solang container from
 `solang containers <https://github.com/hyperledger/solang/pkgs/container/solang>`_:
 
 .. code-block:: bash
 
-    docker pull ghcr.io/hyperledger/solang
+    docker image pull ghcr.io/hyperledger/solang
 
 And if you are using podman:
 
@@ -199,8 +199,8 @@ Or podman:
 
 	  podman container run --rm -it ghcr.io/hyperledger/solang --version
 
-If you want to compile some solidity files, the source file needs to be
-available inside the container. You can do this via the -v command line.
+If you want to compile some Solidity files, the source files need to be
+available inside the container. You can do this via the ``-v`` docker command line.
 In this example ``/local/path`` should be replaced with the absolute path
 to your solidity files:
 

docs/targets/solana.rst

@@ -9,9 +9,12 @@ Solana has the following differences to Ethereum Solidity:
 - An address literal has to be specified using the ``address"36VtvSbE6jVGGQytYWSaDPG7uZphaxEjpJHUUpuUbq4D"`` syntax
 - There is no ``ecrecover()`` builtin function, but there is a ``signatureVerify()`` function which can check ed25519
   signatures.
-- Solana has no concept of gas, so there is no gas functions
+- There is no concept of gas, so there is no gas functions
 - Solana balance is stored in a ``uint64``, so *address* ``.balance``, ``.transfer()`` and ``.send()``
   all use ``uint64`` rather than ``uint256``.
+- Solana uses different accounts for the program code, and the contract data.
+- Programs are upgradable. There is no need to implement upgrades in Solidity.
+- Solana provides different builtins, e.g. ``tx.program_id`` and ``tx.accounts``.
 
 This is how to build your Solidity for Solana:
 
@@ -79,14 +82,14 @@ Calling Anchor Programs from Solidity
 _____________________________________
 
 It is possible to call `Anchor Programs <https://github.com/coral-xyz/anchor>`_
-from Solidity. You first have to generate an interface file from the IDL file using
+from Solidity. You first have to generate a Solidity interface file from the IDL file using
 the :ref:`idl_command`. Then, import the Solidity file in your Solidity using the
-``import "...";`` syntax. Say you have an anchor program called `solidity_from_idl` with a
-function `idl_defined_function`, you can call it like so:
+``import "...";`` syntax. Say you have an anchor program called `bobcat` with a
+function `pounce`, you can call it like so:
 
 .. code-block:: solidity
 
-    import "solidity_from_idl.sol";
+    import "bobcat.sol";
     import "solana";
 
     contract example {
@@ -99,7 +102,7 @@ function `idl_defined_function`, you can call it like so:
             ];
 
             // Any return values are decoded automatically
-            int64 res = solidity_from_idl.idl_defined_function{accounts: am}(arg1, arg2);
+            int64 res = bobcat.pounce{accounts: am}(arg1, arg2);
         }
     }
 
@@ -118,7 +121,7 @@ Solana Cross Program Invocation (CPI) does not support this. This means that:
 
 .. note::
 
-    Hypothetically, this could be implemented like so: the caller could transfer
+    A naive way to implement this is to let the caller transfer
     native balance and then inform the callee about the amount transferred by
     specifying this in the instruction data. However, it would be trivial to
     forge such an operation.
@@ -137,7 +140,7 @@ Builtin Imports
 ________________
 
 Some builtin functionality is only available after importing. The following structs
-can be imported via the special import file ``solana``.
+can be imported via the special builtin import file ``solana``.
 
 .. code-block:: solidity
 
@@ -253,7 +256,7 @@ Solana Library
 ______________
 
 In Solang's Github repository, there is a directory called ``solana-library``. It contains libraries for Solidity contracts
-to interact with Solana specific instructions. Currently, there are two libraries there: one for SPL tokens and another
+to interact with Solana specific instructions. We provide two libraries: one for SPL tokens and another
 for Solana's system instructions. In order to use those functionalities, copy the correspondent library
 file to your project and import it.
 

docs/targets/substrate.rst

@@ -1,7 +1,7 @@
 Parity Substrate
 ================
 
-Solang works with Parity Substrate 3.0. Note that for recent Substrate Version, cross-contract calls as well as using `address`
+Solang works with Parity Substrate 3.0. Note that for recent Substrate versions, cross-contract calls as well as using `address`
 type as function argument or return values are not supported. We are currently working on fixing any regressions.
 
 The Parity Substrate has the following differences to Ethereum Solidity: