Documentation.

Changelog.md

@@ -1,5 +1,8 @@
 ### 0.7.5 (unreleased)
 
+Language Features:
+ * Ability to select the abi coder using ``pragma abicoder v1`` and ``pragma abicoder v2``.
+
 Compiler Features:
  * SMTChecker: Add division by zero checks in the CHC engine.
  * SMTChecker: Support ``selector`` for expressions with value known at compile-time.

docs/060-breaking-changes.rst

@@ -132,7 +132,7 @@ Yul Optimizer
 
 Together with the legacy bytecode optimizer, the :doc:`Yul <yul>` optimizer is now enabled by default when you call the compiler
 with ``--optimize``. It can be disabled by calling the compiler with ``--no-optimize-yul``.
-This mostly affects code that uses ABIEncoderV2.
+This mostly affects code that uses ABI coder v2.
 
 C API Changes
 ~~~~~~~~~~~~~

docs/abi-spec.rst

@@ -589,8 +589,8 @@ As an example, the code
 ::
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >=0.4.19 <0.8.0;
+    pragma solidity >0.7.4;
-    pragma experimental ABIEncoderV2;
+    pragma abicoder v2;
 
     contract Test {
         struct S { uint a; uint[] b; T[] c; }

docs/contracts/functions.rst

@@ -67,8 +67,8 @@ Function parameters can be used as any other local variable and they can also be
 
   An :ref:`external function<external-function-calls>` cannot accept a
   multi-dimensional array as an input
-  parameter. This functionality is possible if you enable the new
+  parameter. This functionality is possible if you enable the ABI coder v2
-  ``ABIEncoderV2`` feature by adding ``pragma experimental ABIEncoderV2;`` to your source file.
+  by adding ``pragma abicoder v2;`` to your source file.
 
   An :ref:`internal function<external-function-calls>` can accept a
   multi-dimensional array without enabling the feature.
@@ -128,8 +128,8 @@ you must provide return values together with the return statement.
 .. note::
     You cannot return some types from non-internal functions, notably
     multi-dimensional dynamic arrays and structs. If you enable the
-    new ``ABIEncoderV2`` feature by adding ``pragma experimental
+    ABI coder v2 by adding ``pragma abicoder v2;``
-    ABIEncoderV2;`` to your source file then more types are available, but
+    to your source file then more types are available, but
     ``mapping`` types are still limited to inside a single contract and you
     cannot transfer them.
 

docs/layout-of-source-files.rst

@@ -88,6 +88,41 @@ these follow the same syntax used by `npm <https://docs.npmjs.com/misc/semver>`_
   required by the pragma. If it does not match, the compiler issues
   an error.
 
+ABI Coder Pragma
+----------------
+
+By using ``pragma abicoder v1`` or ``pragma abicoder v2`` you can
+select between the two implementations of the ABI encoder and decoder.
+
+The new ABI coder (v2) is able to encode and decode arbitrarily nested
+arrays and structs. It might produce less optimal code and has not
+received as much testing as the old encoder, but is considered
+non-experimental as of Solidity 0.6.0. You still have to explicitly
+activate it using ``pragma abicoder v2;``. Since it will be
+activated by default starting from Solidity 0.8.0, there is the option to select
+the old coder using ``pragma abicoder v1;``.
+
+The set of types supported by the new encoder is a strict superset of
+the ones supported by the old one. Contracts that use it can interact with ones
+that do not without limitations. The reverse is possible only as long as the
+non-``abicoder v2`` contract does not try to make calls that would require
+decoding types only supported by the new encoder. The compiler can detect this
+and will issue an error. Simply enabling ``abicoder v2`` for your contract is
+enough to make the error go away.
+
+.. note::
+  This pragma applies to all the code defined in the file where it is activated,
+  regardless of where that code ends up eventually. This means that a contract
+  whose source file is selected to compile with ABI coder v1
+  can still contain code that uses the new encoder
+  by inheriting it from another contract. This is allowed if the new types are only
+  used internally and not in external function signatures.
+
+.. note::
+  Up to Solidity 0.7.4, it was possible to select the ABI coder v2
+  by using ``pragma experimental ABIEncoderV2``, but it was not possible
+  to explicitly select coder v1 because it was the default.
+
 .. index:: ! pragma, experimental
 
 .. _experimental_pragma:
@@ -103,28 +138,9 @@ The following experimental pragmas are currently supported:
 ABIEncoderV2
 ~~~~~~~~~~~~
 
-The new ABI encoder is able to encode and decode arbitrarily nested
+Because the ABI coder v2 is not considered experimental anymore,
-arrays and structs. It might produce less optimal code and has not
+it can be selected via ``pragma abicoder v2`` (please see above)
-received as much testing as the old encoder, but is considered
+since Solidity 0.7.4.
-non-experimental as of Solidity 0.6.0. You still have to explicitly
-activate it using ``pragma experimental ABIEncoderV2;`` - we kept
-the same pragma, even though it is not considered experimental
-anymore.
-
-The set of types supported by the new encoder is a strict superset of
-the ones supported by the old one. Contracts that use it can interact with ones
-that do not without limitations. The reverse is possible only as long as the
-non-``ABIEncoderV2`` contract does not try to make calls that would require
-decoding types only supported by the new encoder. The compiler can detect this
-and will issue an error. Simply enabling ``ABIEncoderV2`` for your contract is
-enough to make the error go away.
-
-.. note::
-  This pragma applies to all the code defined in the file where it is activated,
-  regardless of where that code ends up eventually. This means that a contract
-  without the ``ABIEncoderV2`` pragma can still contain code that uses the new encoder
-  by inheriting it from another contract. This is allowed if the new types are only
-  used internally and not in external function signatures.
 
 .. _smt_checker:
 

docs/types/reference-types.rst

@@ -290,7 +290,7 @@ Array Members
 
 .. note::
     To use arrays of arrays in external (instead of public) functions, you need to
-    activate ABIEncoderV2.
+    activate ABI coder v2.
 
 .. note::
     In EVM versions before Byzantium, it was not possible to access

docs/using-the-compiler.rst

@@ -231,7 +231,7 @@ Input Description
             "cse": false,
             // Optimize representation of literal numbers and strings in code.
             "constantOptimizer": false,
-            // The new Yul optimizer. Mostly operates on the code of ABIEncoderV2
+            // The new Yul optimizer. Mostly operates on the code of ABI coder v2
             // and inline assembly.
             // It is activated together with the global optimizer setting
             // and can be deactivated here.