Documentation updates for internal constructors and function signature (#3365)

* Add a note explaining return values not included in function signature

* Add section on Constructors in documentation

* Improve documented definition for abstract contract

* Add benefits of abstraction to documentation

1 files changed, 6 insertions, 0 deletions

diff --git a/docs/abi-spec.rst b/docs/abi-spec.rst
index 07c8e0ce..4a61d91f 100644
--- a/docs/abi-spec.rst
+++ b/docs/abi-spec.rst
@@ -26,6 +26,10 @@ The first four bytes of the call data for a function call specifies the function
 first (left, high-order in big-endian) four bytes of the Keccak (SHA-3) hash of the signature of the function. The signature is defined as the canonical expression of the basic prototype, i.e.
 the function name with the parenthesised list of parameter types. Parameter types are split by a single comma - no spaces are used.
 
+.. note::
+    The return type of a function is not part of this signature. In :ref:`Solidity's function overloading <overload-function>` return types are not considered. The reason is to keep function call resolution context-independent.
+    The JSON description of the ABI however contains both inputs and outputs. See (the :ref:`JSON ABI <abi_json>`)
+
 Argument Encoding
 =================
 
@@ -290,6 +294,8 @@ In effect, a log entry using this ABI is described as:
 
 For all fixed-length Solidity types, the ``EVENT_INDEXED_ARGS`` array contains the 32-byte encoded value directly. However, for *types of dynamic length*, which include ``string``, ``bytes``, and arrays, ``EVENT_INDEXED_ARGS`` will contain the *Keccak hash* of the encoded value, rather than the encoded value directly. This allows applications to efficiently query for values of dynamic-length types (by setting the hash of the encoded value as the topic), but leaves applications unable to decode indexed values they have not queried for. For dynamic-length types, application developers face a trade-off between fast search for predetermined values (if the argument is indexed) and legibility of arbitrary values (which requires that the arguments not be indexed). Developers may overcome this tradeoff and achieve both efficient search and arbitrary legibility by defining events with two arguments — one indexed, one not — intended to hold the same value.
 
+.. _abi_json:
+
 JSON
 ====