From ec4ccf81830b39522fe9074b61fc67bf687954f7 Mon Sep 17 00:00:00 2001
From: minami <minaminaoy@gmail.com>
Date: Thu, 4 Aug 2022 15:51:22 +0900
Subject: [PATCH] Improve docs of possible function inputs and outputs

---
 docs/contracts/functions.rst    | 26 ++++++++++----------------
 docs/layout-of-source-files.rst | 21 ++++++++++++---------
 2 files changed, 22 insertions(+), 25 deletions(-)

diff --git a/docs/contracts/functions.rst b/docs/contracts/functions.rst
index c7b7cc56b..f14e4b8a5 100644
--- a/docs/contracts/functions.rst
+++ b/docs/contracts/functions.rst
@@ -72,16 +72,6 @@ with two integers, you would use something like the following:
 
 Function parameters can be used as any other local variable and they can also be assigned to.
 
-.. note::
-
-  Until version 0.6.0 it was not possible to use a multi-dimensional array or a struct
-  as an input for an :ref:`external function<external-function-calls>`.
-  ``abicoder v2`` made it possible and it's been enabled by default since version 0.8.0
-  (before that you had to enable it with ``pragma abicoder v2;``).
-
-  An :ref:`internal function<internal-function-calls>` can accept a
-  multi-dimensional array or a struct without any restrictions.
-
 .. index:: return array, return string, array, string, array of strings, dynamic array, variably sized array, return struct, struct
 
 Return Variables
@@ -139,12 +129,16 @@ If you use an early ``return`` to leave a function that has return variables,
 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
-    ABI coder v2 by adding ``pragma abicoder v2;``
-    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.
+    You cannot return some types from non-internal functions.
+    This includes the types listed below and any composite types that recursively contain them:
+
+    - mappings,
+    - internal function types,
+    - reference types with location set to ``storage``,
+    - multi-dimensional arrays (applies only to :ref:`ABI coder v1 <abi_coder>`),
+    - structs (applies only to :ref:`ABI coder v1 <abi_coder>`).
+
+    This restriction does not apply to library functions because of their different :ref:`internal ABI <library-selectors>`.
 
 .. _multi-return:
 
diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst
index 729951142..cd231c1fc 100644
--- a/docs/layout-of-source-files.rst
+++ b/docs/layout-of-source-files.rst
@@ -56,7 +56,7 @@ you have to add the pragma to all your files if you want to enable it
 in your whole project. If you :ref:`import<import>` another file, the pragma
 from that file does *not* automatically apply to the importing file.
 
-.. index:: ! pragma, version
+.. index:: ! pragma;version
 
 .. _version_pragma:
 
@@ -91,6 +91,9 @@ these follow the same syntax used by `npm <https://docs.npmjs.com/cli/v6/using-n
   required by the pragma. If it does not match, the compiler issues
   an error.
 
+.. index:: ! ABI coder, ! pragma; abicoder, pragma; ABIEncoderV2
+.. _abi_coder:
+
 ABI Coder Pragma
 ----------------
 
@@ -98,12 +101,11 @@ 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;``.
+arrays and structs. Apart from supporting more types, it involves more extensive
+validation and safety checks, which may result in higher gas costs, but also heightened
+security. It is considered
+non-experimental as of Solidity 0.6.0 and it is enabled by default starting
+with Solidity 0.8.0. There old coder can still be selected 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
@@ -126,8 +128,7 @@ enough to make the error go away.
   by using ``pragma experimental ABIEncoderV2``, but it was not possible
   to explicitly select coder v1 because it was the default.
 
-.. index:: ! pragma, experimental
-
+.. index:: ! pragma; experimental
 .. _experimental_pragma:
 
 Experimental Pragma
@@ -137,6 +138,7 @@ The second pragma is the experimental pragma. It can be used to enable
 features of the compiler or language that are not yet enabled by default.
 The following experimental pragmas are currently supported:
 
+.. index:: ! pragma; ABIEncoderV2
 
 ABIEncoderV2
 ~~~~~~~~~~~~
@@ -145,6 +147,7 @@ Because the ABI coder v2 is not considered experimental anymore,
 it can be selected via ``pragma abicoder v2`` (please see above)
 since Solidity 0.7.4.
 
+.. index:: ! pragma; SMTChecker
 .. _smt_checker:
 
 SMTChecker