Merge pull request #6153 from ethereum/docs-imports

[DOCS] Improve imports documentation

docs/layout-of-source-files.rst

@@ -96,7 +96,7 @@ The component does not yet support all features of the Solidity language
 and likely outputs many warnings. In case it reports unsupported
 features, the analysis may not be fully sound.
 
-.. index:: source file, ! import
+.. index:: source file, ! import, module
 
 .. _import:
 
@@ -106,8 +106,8 @@ Importing other Source Files
 Syntax and Semantics
 --------------------
 
-Solidity supports import statements that are very similar to those available in JavaScript
+Solidity supports import statements to help modularise your code that are similar to those available in JavaScript
-(from ES6 on), although Solidity does not know the concept of a "default export".
+(from ES6 on). However, Solidity does not support the concept of a `default export <https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export#Description>`_.
 
 At a global level, you can use import statements of the following form:
 
@@ -117,29 +117,21 @@ At a global level, you can use import statements of the following form:
 
 This statement imports all global symbols from "filename" (and symbols imported there) into the
 current global scope (different than in ES6 but backwards-compatible for Solidity).
-This simple form is not recommended for use, because it pollutes the namespace in an
+This form is not recommended for use, because it unpredictably pollutes the namespace.
-unpredictable way: If you add new top-level items inside "filename", they will automatically
+If you add new top-level items inside "filename", they automatically
 appear in all files that import like this from "filename". It is better to import specific
 symbols explicitly.
 
 The following example creates a new global symbol ``symbolName`` whose members are all
-the global symbols from ``"filename"``.
+the global symbols from ``"filename"``:
 
 ::
 
   import * as symbolName from "filename";
 
-If there is a naming collision, you can also rename symbols while importing.
+which results in all global symbols being available in the format ``symbolName.symbol``.
-This code
-creates new global symbols ``alias`` and ``symbol2`` which reference ``symbol1`` and ``symbol2`` from inside ``"filename"``, respectively.
 
-::
+A variant of this syntax that is not part of ES6, but possibly useful is:
-
-  import {symbol1 as alias, symbol2} from "filename";
-
-
-
-Another syntax is not part of ES6, but probably convenient:
 
 ::
 
@@ -147,31 +139,37 @@ Another syntax is not part of ES6, but probably convenient:
 
 which is equivalent to ``import * as symbolName from "filename";``.
 
-.. note::
+If there is a naming collision, you can rename symbols while importing. For example,
-  If you use `import "filename.sol" as moduleName;`, you access a contract called `C`
+the code below creates new global symbols ``alias`` and ``symbol2`` which reference
-  from inside `"filename.sol"` as `moduleName.C` and not by using `C` directly.
+``symbol1`` and ``symbol2`` from inside ``"filename"``, respectively.
+
+::
+
+  import {symbol1 as alias, symbol2} from "filename";
 
 Paths
 -----
 
 In the above, ``filename`` is always treated as a path with ``/`` as directory separator,
-``.`` as the current and ``..`` as the parent directory.  When ``.`` or ``..`` is followed by a character except ``/``,
+and ``.`` as the current and ``..`` as the parent directory.  When ``.`` or ``..`` is followed by a character except ``/``,
 it is not considered as the current or the parent directory.
 All path names are treated as absolute paths unless they start with the current ``.`` or the parent directory ``..``.
 
-To import a file ``x`` from the same directory as the current file, use ``import "./x" as x;``.
+To import a file ``filename`` from the same directory as the current file, use ``import "./filename" as symbolName;``.
-If you use ``import "x" as x;`` instead, a different file could be referenced
+If you use ``import "filename" as symbolName;`` instead, a different file could be referenced
 (in a global "include directory").
 
-It depends on the compiler (see below) how to actually resolve the paths.
+It depends on the compiler (see :ref:`import-compiler`) how to actually resolve the paths.
 In general, the directory hierarchy does not need to strictly map onto your local
-filesystem, it can also map to resources discovered via e.g. ipfs, http or git.
+filesystem, and the path can also map to resources such as ipfs, http or git.
 
 .. note::
     Always use relative imports like ``import "./filename.sol";`` and avoid
     using ``..`` in path specifiers. In the latter case, it is probably better to use
     global paths and set up remappings as explained below.
 
+.. _import-compiler:
+
 Use in Actual Compilers
 -----------------------