From d0a08a7b8a8d4dd8d825f5bc0d2ee9687c549516 Mon Sep 17 00:00:00 2001
From: Kostis Sagonas <kostis@it.uu.se>
Date: Wed, 19 Jun 2019 10:08:02 +0200
Subject: The map() type is an alias; not a predefined type

This pull request corrects an historical accident.
At some point in time, the set of Erlang terms was extended to include
maps, and at that time the `map()' type was also introduced to the
language as an easy, albeit quite coarse, way to declare map terms.
At some later point in time, the type language was extended with the
ability to declare _type associations_ in maps and also with a notation
to declare mandatory (:=) and optional (=>) type associations.

At that point in time, it should have been realized that the `map()'
type is nothing more than an alias (for `#{any() => any()}') instead
of being a _predefined_ type.  (The situation is analogous to e.g.
the `binary()' type being just an alias for `<<_:_*8>>'.)

This pull request corrects the documentation (the reference manual).
---
 system/doc/reference_manual/typespec.xml | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml
index 27cd0ba83d..f517259a64 100644
--- a/system/doc/reference_manual/typespec.xml
+++ b/system/doc/reference_manual/typespec.xml
@@ -4,7 +4,7 @@
 <chapter>
   <header>
     <copyright>
-      <year>2003</year><year>2018</year>
+      <year>2003</year><year>2019</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -140,8 +140,7 @@
         | nonempty_improper_list(Type1, Type2) %% Type1 and Type2 as above
         | nonempty_list(Type)                  %% Proper non-empty list
 
-  Map :: map()                                 %% denotes a map of any size
-       | #{}                                   %% denotes the empty map
+  Map :: #{}                                   %% denotes the empty map
        | #{AssociationList}
 
   Tuple :: tuple()                             %% denotes a tuple of any size
@@ -192,17 +191,16 @@
     <c>AssociationList</c> are allowed to overlap, and if they do, the
     leftmost association takes precedence. A map association has a key in
     <c>AssociationList</c> if it belongs to this type.
-    <c>AssociationList</c> can contain both mandatory and optional
-    association types.
+    <c>AssociationList</c> can contain both mandatory <c>(:=)</c> and
+    optional <c>(=&gt;)</c> association types.
     If an association type is mandatory, an association with that type
-    is to be present.
+    needs to be present.
     In the case of an optional association type it is not required for
     the key type to be present.
   </p>
   <p>
-    Notice that the syntactic representation of <c>map()</c> is
-    <c>#{any() =&gt; any()}</c> (or <c>#{_ =&gt; _}</c>), not <c>#{}</c>.
     The notation <c>#{}</c> specifies the singleton type for the empty map.
+    Note that this notation is not a shorthand for the <c>map()</c> type.
   </p>
   <p>
     For convenience, the following types are also built-in.
@@ -258,6 +256,9 @@
     <row>
       <cell><c>iolist()</c></cell><cell><c>maybe_improper_list(byte() | binary() | iolist(), binary() | [])</c></cell>
     </row>
+    <row>
+      <cell><c>map()</c></cell><cell><c>#{any() =&gt; any()}</c></cell>
+    </row>
     <row>
       <cell><c>function()</c></cell><cell><c>fun()</c></cell>
     </row>
-- 
cgit v1.2.3