Clarify mapping type

1 files changed, 24 insertions, 20 deletions

diff --git a/docs/types.rst b/docs/types.rst
index eaec8ad5..91f0c0ff 100644
--- a/docs/types.rst
+++ b/docs/types.rst
@@ -932,26 +932,30 @@ assigning it to a local variable, as in
 Mappings
 ========
 
-Mapping types are declared as ``mapping(_KeyType => _ValueType)``.
-Here ``_KeyType`` can be almost any type except for a mapping, a dynamically sized array, a contract, a function, an enum and a struct.
-``_ValueType`` can actually be any type, including mappings.
-
-Mappings can be seen as `hash tables <https://en.wikipedia.org/wiki/Hash_table>`_ which are virtually initialized such that
-every possible key exists and is mapped to a value whose byte-representation is
-all zeros: a type's :ref:`default value <default-value>`. The similarity ends here, though: The key data is not actually stored
-in a mapping, only its ``keccak256`` hash used to look up the value.
-
-Because of this, mappings do not have a length or a concept of a key or value being "set".
-
-Mappings are only allowed for state variables (or as storage reference types
+You declare mapping types with the syntax ``mapping(_KeyType => _ValueType)``.
+The ``_KeyType`` can be any elementary type. This means it can be any of
+the built-in value types plus ``bytes`` and ``string``. User-defined
+or complex types like contract types, enums, mappings, structs and any array type
+apart from ``bytes`` and ``string`` are not allowed.
+``_ValueType`` can be any type, including mappings.
+
+You can think of mappings as `hash tables <https://en.wikipedia.org/wiki/Hash_table>`_, which are virtually initialized
+such that every possible key exists and is mapped to a value whose
+byte-representation is all zeros, a type's :ref:`default value <default-value>`. The similarity ends there, the key data is not stored in a
+mapping, only its ``keccak256`` hash is used to look up the value.
+
+Because of this, mappings do not have a length or a concept of a key or
+value being set.
+
+Mappings are **only** allowed for state variables (or as storage reference types
 in internal functions).
 
-It is possible to mark mappings ``public`` and have Solidity create a :ref:`getter <visibility-and-getters>`.
-The ``_KeyType`` will become a required parameter for the getter and it will
-return ``_ValueType``.
-
-The ``_ValueType`` can be a mapping too. The getter will have one parameter
-for each ``_KeyType``, recursively.
+You can mark variables of mapping type as ``public`` and Solidity creates a
+:ref:`getter <visibility-and-getters>` for you. The ``_KeyType`` becomes a
+parameter for the getter. If ``_ValueType`` is a value type or a struct,
+the getter returns ``_ValueType``.
+If ``_ValueType`` is an array or a mapping, the getter has one parameter for
+each ``_KeyType``, recursively. For example with a mapping:
 
 ::
 
@@ -975,8 +979,8 @@ for each ``_KeyType``, recursively.
 
 
 .. note::
-  Mappings are not iterable, but it is possible to implement a data structure on top of them.
-  For an example, see `iterable mapping <https://github.com/ethereum/dapp-bin/blob/master/library/iterable_mapping.sol>`_.
+  Mappings are not iterable, but it is possible to implement a data structure
+  on top of them. For an example, see `iterable mapping <https://github.com/ethereum/dapp-bin/blob/master/library/iterable_mapping.sol>`_.
 
 .. index:: assignment, ! delete, lvalue