Merge branch 'ks/type-doc-cleanup/OTP-10850'

* ks/type-doc-cleanup/OTP-10850:
  Add support for printing <<_:_*1>> as bitstring()
  Clean up of documentation of type language

1 files changed, 199 insertions, 156 deletions

diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml
index 9207d536d5..1279493ba8 100644
--- a/system/doc/reference_manual/typespec.xml
+++ b/system/doc/reference_manual/typespec.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
 <!DOCTYPE chapter SYSTEM "chapter.dtd">
 
 <chapter>
@@ -13,12 +13,12 @@
       compliance with the License. You should have received a copy of the
       Erlang Public License along with this software. If not, it can be
       retrieved online at http://www.erlang.org/.
-    
+
       Software distributed under the License is distributed on an "AS IS"
       basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
       the License for the specific language governing rights and limitations
       under the License.
-    
+
     </legalnotice>
 
     <title>Types and Function Specifications</title>
@@ -30,111 +30,121 @@
   </header>
 
   <section>
-  <title>Introduction of Types</title>
-  <p>
-    Erlang is a dynamically typed language. Still, it comes with a
-    language extension for declaring sets of Erlang terms to form a
-    particular type, effectively forming a specific sub-type of the set
-    of all Erlang terms.
-  </p>
-  <p> 
-    Subsequently, these types can be used to specify types of record fields 
-    and the argument and return types of functions.
-  </p>
-  <p>
-    Type information can be used to document function interfaces, 
-    provide more information for bug detection tools such as <c>Dialyzer</c>, 
-    and can be exploited by documentation tools such as <c>Edoc</c> for 
-    generating program documentation of various forms. 
-    It is expected that the type language described in this document will 
-    supersede and replace the purely comment-based <c>@type</c> and 
-  <c>@spec</c> declarations used by <c>Edoc</c>.
-  </p>
+    <title>The Erlang Type Language</title>
+    <p>
+      Erlang is a dynamically typed language. Still, it comes with a
+      notation for declaring sets of Erlang terms to form a particular
+      type, effectively forming a specific sub-type of the set of all
+      Erlang terms.
+    </p>
+    <p>
+      Subsequently, these types can be used to specify types of record fields
+      and the argument and return types of functions.
+    </p>
+    <p>
+      Type information can be used to document function interfaces,
+      provide more information for bug detection tools such as <c>Dialyzer</c>,
+      and can be exploited by documentation tools such as <c>Edoc</c> for
+      generating program documentation of various forms.
+      It is expected that the type language described in this document will
+      supersede and replace the purely comment-based <c>@type</c> and
+      <c>@spec</c> declarations used by <c>Edoc</c>.
+    </p>
   </section>
   <section>
     <marker id="syntax"></marker>
     <title>Types and their Syntax</title>
     <p>
-    Types describe sets of Erlang terms. 
-    Types consist and are built from a set of predefined types (e.g. <c>integer()</c>, 
-    <c>atom()</c>, <c>pid()</c>, ...) described below. 
-    Predefined types represent a typically infinite set of Erlang terms which 
-    belong to this type. 
-    For example, the type <c>atom()</c> stands for the set of all Erlang atoms.
-	</p>
-	<p>
-    For integers and atoms, we allow for singleton types (e.g. the integers <c>-1</c> 
-    and <c>42</c> or the atoms <c>'foo'</c> and <c>'bar'</c>).
+      Types describe sets of Erlang terms.
+      Types consist and are built from a set of predefined types
+      (e.g. <c>integer()</c>, <c>atom()</c>, <c>pid()</c>, ...)
+      described below.
+      Predefined types represent a typically infinite set of Erlang terms which
+      belong to this type.  For example, the type <c>atom()</c> stands for the
+      set of all Erlang atoms.
+    </p>
+    <p>
+      For integers and atoms, we allow for singleton types (e.g. the integers
+      <c>-1</c> and <c>42</c> or the atoms <c>'foo'</c> and <c>'bar'</c>).
 
-    All other types are built using unions of either predefined types or singleton 
-    types. In a type union between a type and one of its sub-types the sub-type is 
-    absorbed by the super-type and the union is subsequently treated as if the 
-    sub-type was not a constituent of the union. For example, the type union:
+      All other types are built using unions of either predefined
+      types or singleton types. In a type union between a type and one
+      of its sub-types the sub-type is absorbed by the super-type and
+      the union is subsequently treated as if the sub-type was not a
+      constituent of the union. For example, the type union:
     </p>
-    <pre>
- atom() | 'bar' | integer() | 42</pre>
-    <p>
-    describes the same set of terms as the type union:
-    </p>
-	<pre>
-atom() | integer()</pre>
-	<p>
-	Because of sub-type relations that exist between types, types form a lattice 
-	where the topmost element, any(), denotes the set of all Erlang terms and 
-	the bottom-most element, none(), denotes the empty set of terms.
-	</p>
-	<p>
-	The set of predefined types and the syntax for types is given below:
-	</p>
-	<pre><![CDATA[
-Type :: any()            %% The top type, the set of all Erlang terms.
-      | none()           %% The bottom type, contains no terms.
-      | pid()
-      | port()
-      | reference()
-      | []               %% nil
-      | Atom
-      | Binary
-      | float()
-      | Fun
-      | Integer
-      | List
-      | Tuple
-      | Union
-      | UserDefined      %% described in Section 2
+    <pre>  atom() | 'bar' | integer() | 42</pre>
+    <p>
+      describes the same set of terms as the type union:
+    </p>
+    <pre>  atom() | integer()</pre>
+    <p>
+      Because of sub-type relations that exist between types, types
+      form a lattice where the topmost element, <c>any()</c>, denotes
+      the set of all Erlang terms and the bottom-most element, <c>none()</c>,
+      denotes the empty set of terms.
+    </p>
+    <p>
+      The set of predefined types and the syntax for types is given below:
+    </p>
+    <pre><![CDATA[
+  Type :: any()                 %% The top type, the set of all Erlang terms
+        | none()                %% The bottom type, contains no terms
+        | pid()
+        | port()
+        | reference()
+        | []                    %% nil
+        | Atom
+        | Bitstring
+        | float()
+        | Fun
+        | Integer
+        | List
+        | Tuple
+        | Union
+        | UserDefined           %% described in Section 6.3
 
-Union :: Type1 | Type2
+  Atom :: atom()
+        | Erlang_Atom           %% 'foo', 'bar', ...
 
-Atom :: atom()
-      | Erlang_Atom      %% 'foo', 'bar', ...
+  Bitstring :: <<>>
+             | <<_:M>>          %% M is a positive integer
+             | <<_:_*N>>        %% N is a positive integer
+             | <<_:M, _:_*N>>
 
-Binary :: binary()                        %% <<_:_ * 8>>
-        | <<>>
-        | <<_:Erlang_Integer>>            %% Base size
-        | <<_:_*Erlang_Integer>>          %% Unit size
-        | <<_:Erlang_Integer, _:_*Erlang_Integer>>
+  Fun :: fun()                  %% any function
+       | fun((...) -> Type)     %% any arity, returning Type
+       | fun(() -> Type)
+       | fun((TList) -> Type)
 
-Fun :: fun()                              %% any function
-     | fun((...) -> Type)                 %% any arity, returning Type
-     | fun(() -> Type)
-     | fun((TList) -> Type)
+  Integer :: integer()
+           | Erlang_Integer                 %% ..., -1, 0, 1, ... 42 ...
+           | Erlang_Integer..Erlang_Integer %% specifies an integer range
 
-Integer :: integer()
-         | Erlang_Integer                 %% ..., -1, 0, 1, ... 42 ...
-         | Erlang_Integer..Erlang_Integer %% specifies an integer range
+  List :: list(Type)                        %% Proper list ([]-terminated)
+        | improper_list(Type1, Type2)       %% Type1=contents, Type2=termination
+        | maybe_improper_list(Type1, Type2) %% Type1 and Type2 as above
 
-List :: list(Type)                        %% Proper list ([]-terminated)
-      | improper_list(Type1, Type2)       %% Type1=contents, Type2=termination
-      | maybe_improper_list(Type1, Type2) %% Type1 and Type2 as above
+  Tuple :: tuple()                          %% stands for a tuple of any size
+         | {}
+         | {TList}
 
-Tuple :: tuple()                          %% stands for a tuple of any size
-       | {}
-       | {TList}
+  TList :: Type
+         | Type, TList
 
-TList :: Type
-       | Type, TList
+  Union :: Type1 | Type2
 ]]></pre>
   <p>
+    The general form of bitstrings is <c>&lt;&lt;_:M, _:_*N&gt;&gt;</c>,
+    where <c>M</c> and <c>N</c> are positive integers. It denotes a
+    bitstring that is <c>M + (k*N)</c> bits long (i.e., a bitstring that
+    starts with <c>M</c> bits and continues with <c>k</c> segments of
+    <c>N</c> bits each, where <c>k</c> is also a positive integer).
+    The notations <c>&lt;&lt;_:_*N&gt;&gt;</c>, <c>&lt;&lt;_:M&gt;&gt;</c>,
+    and <c>&lt;&lt;&gt;&gt;</c> are convenient shorthands for the cases
+    that <c>M</c>, <c>N</c>, or both, respectively, are zero.
+  </p>
+  <p>
     Because lists are commonly used, they have shorthand type notations. 
     The type <c>list(T)</c> has the shorthand <c>[T]</c>.
     The shorthand <c>[T,...]</c> stands for 
@@ -154,11 +164,17 @@ TList :: Type
   </p>
   <table>
     <row>
-      <cell><b>Built-in type</b></cell><cell><b>Stands for</b></cell>
+      <cell><b>Built-in type</b></cell><cell><b>Defined as</b></cell>
     </row>
     <row>
       <cell><c>term()</c></cell><cell><c>any()</c></cell>
     </row>
+    <row>
+      <cell><c>binary()</c></cell><cell><c>&lt;&lt;_:*8&gt;&gt;</c></cell>
+    </row>
+    <row>
+      <cell><c>bitstring()</c></cell><cell><c>&lt;&lt;_:*1&gt;&gt;</c></cell>
+    </row>
     <row> 
       <cell><c>boolean()</c></cell><cell><c>'false' | 'true'</c></cell>
     </row>
@@ -169,15 +185,6 @@ TList :: Type
       <cell><c>char()</c></cell><cell><c>0..16#10ffff</c></cell>
     </row>
     <row> 
-      <cell><c>non_neg_integer()</c></cell><cell><c>0..</c></cell>
-    </row>
-    <row> 
-      <cell><c>pos_integer()</c></cell><cell><c>1..</c></cell>
-    </row>
-    <row> 
-      <cell><c>neg_integer()</c></cell><cell><c>..-1</c></cell>
-    </row>
-    <row> 
       <cell><c>number()</c></cell><cell><c>integer() | float()</c></cell>
     </row>
     <row> 
@@ -214,35 +221,54 @@ TList :: Type
       <cell><c>no_return()</c></cell><cell><c>none()</c></cell> 
     </row>
   </table>
+  <p>
+  In addition, the following three built-in types exist and can be
+  thought as defined below, though strictly their "type definition" is
+  not valid syntax according to the type language defined above.
+  </p>
+  <table>
+    <row>
+      <cell><b>Built-in type</b></cell><cell><b>Could be thought defined by the syntax</b></cell>
+    </row>
+    <row>
+      <cell><c>non_neg_integer()</c></cell><cell><c>0..</c></cell>
+    </row>
+    <row>
+      <cell><c>pos_integer()</c></cell><cell><c>1..</c></cell>
+    </row>
+    <row>
+      <cell><c>neg_integer()</c></cell><cell><c>..-1</c></cell>
+    </row>
+  </table>
   
   <p>
     Users are not allowed to define types with the same names as the
     predefined or built-in ones. This is checked by the compiler and
     its violation results in a compilation error. 
-    (For bootstrapping purposes, it can also result to just a warning if this 
-    involves a built-in type which has just been introduced.)
+    (For bootstrapping purposes, it can also result to just a warning
+    if this involves a built-in type which has just been introduced.)
   </p>
   <note>
     The following built-in list types also exist, 
     but they are expected to be rarely used. Hence, they have long names:
   </note>
   <pre>
-nonempty_maybe_improper_list(Type) :: nonempty_maybe_improper_list(Type, any())
-nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any())</pre>
+  nonempty_maybe_improper_list(Type) :: nonempty_maybe_improper_list(Type, any())
+  nonempty_maybe_improper_list() :: nonempty_maybe_improper_list(any())</pre>
   <p>
     where the following two types
     define the set of Erlang terms one would expect:
   </p>
   <pre>
-nonempty_improper_list(Type1, Type2)
-nonempty_maybe_improper_list(Type1, Type2)</pre>
+  nonempty_improper_list(Type1, Type2)
+  nonempty_maybe_improper_list(Type1, Type2)</pre>
   <p>
     Also for convenience, we allow for record notation to be used. 
     Records are just shorthands for the corresponding tuples.
   </p>
   <pre>
-Record :: #Erlang_Atom{}
-        | #Erlang_Atom{Fields}</pre>
+  Record :: #Erlang_Atom{}
+          | #Erlang_Atom{Fields}</pre>
   <p>
     Records have been extended to possibly contain type information. 
     This is described in the sub-section <seealso marker="#typeinrecords">"Type information in record declarations"</seealso> below.
@@ -257,8 +283,8 @@ Record :: #Erlang_Atom{}
       compiler attributes as in the following:
     </p>
     <pre>
--type my_struct_type() :: Type.
--opaque my_opaq_type() :: Type.</pre>
+  -type my_struct_type() :: Type.
+  -opaque my_opaq_type() :: Type.</pre>
     <p>
       where the type name is an atom (<c>'my_struct_type'</c> in the above)
       followed by parentheses. Type is a type as defined in the
@@ -279,23 +305,23 @@ Record :: #Erlang_Atom{}
       definition. A concrete example appears below:
     </p>
     <pre>
--type orddict(Key, Val) :: [{Key, Val}].</pre>
+  -type orddict(Key, Val) :: [{Key, Val}].</pre>
     <p>
       A module can export some types in order to declare that other modules
       are allowed to refer to them as <em>remote types</em>.
       This declaration has the following form:
       <pre>
--export_type([T1/A1, ..., Tk/Ak]).</pre>
+  -export_type([T1/A1, ..., Tk/Ak]).</pre>
       where the Ti's are atoms (the name of the type) and the Ai's are their
       arguments.  An example is given below:
       <pre>
--export_type([my_struct_type/0, orddict/2]).</pre>
+  -export_type([my_struct_type/0, orddict/2]).</pre>
       Assuming that these types are exported from module <c>'mod'</c> then
       one can refer to them from other modules using remote type expressions
       like those below:
       <pre>
-mod:my_struct_type()
-mod:orddict(atom(), term())</pre>
+  mod:my_struct_type()
+  mod:orddict(atom(), term())</pre>
       One is not allowed to refer to types which are not declared as exported.
     </p>
     <p>
@@ -317,19 +343,19 @@ mod:orddict(atom(), term())</pre>
       record. The syntax for this is:
     </p>
     <pre>
--record(rec, {field1 :: Type1, field2, field3 :: Type3}).</pre>
+  -record(rec, {field1 :: Type1, field2, field3 :: Type3}).</pre>
     <p>
       For fields without type annotations, their type defaults to any(). 
       I.e., the above is a shorthand for:
     </p>
     <pre>
--record(rec, {field1 :: Type1, field2 :: any(), field3 :: Type3}).</pre>
+  -record(rec, {field1 :: Type1, field2 :: any(), field3 :: Type3}).</pre>
     <p>
       In the presence of initial values for fields, 
       the type must be declared after the initialization as in the following:
     </p>
     <pre>
--record(rec, {field1 = [] :: Type1, field2, field3 = 42 :: Type3}).</pre>
+  -record(rec, {field1 = [] :: Type1, field2, field3 = 42 :: Type3}).</pre>
     <p>
       Naturally, the initial values for fields should be compatible 
       with (i.e. a member of) the corresponding types. 
@@ -340,13 +366,13 @@ mod:orddict(atom(), term())</pre>
       effects:
     </p>
     <pre>
--record(rec, {f1 = 42 :: integer(),
-              f2      :: float(),
-              f3      :: 'a' | 'b'}).
+  -record(rec, {f1 = 42 :: integer(),
+                f2      :: float(),
+                f3      :: 'a' | 'b'}).
 
--record(rec, {f1 = 42 :: integer(),
-              f2      :: 'undefined' | float(),
-              f3      :: 'undefined' | 'a' | 'b'}).</pre>
+  -record(rec, {f1 = 42 :: integer(),
+                f2      :: 'undefined' | float(),
+                f3      :: 'undefined' | 'a' | 'b'}).</pre>
     <p>
       For this reason, it is recommended that records contain initializers, 
       whenever possible.
@@ -355,15 +381,13 @@ mod:orddict(atom(), term())</pre>
       Any record, containing type information or not, once defined, 
       can be used as a type using the syntax:
     </p>
-    <pre>
-#rec{}</pre>
+    <pre>  #rec{}</pre>
     <p>
       In addition, the record fields can be further specified when using 
       a record type by adding type information about the field in
       the following manner:
     </p>
-    <pre>
-#rec{some_field :: Type}</pre>
+    <pre>  #rec{some_field :: Type}</pre>
     <p>
       Any unspecified fields are assumed to have the type in the original 
       record declaration.
@@ -377,7 +401,7 @@ mod:orddict(atom(), term())</pre>
       compiler attribute <c>'-spec'</c>. The general format is as follows:
     </p>
     <pre>
--spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre>
+  -spec Module:Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre>
     <p>
       The arity of the function has to match the number of arguments, 
       or else a compilation error occurs.
@@ -392,19 +416,19 @@ mod:orddict(atom(), term())</pre>
       For most uses within a given module, the following shorthand suffices:
     </p>
     <pre>
--spec Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre>
+  -spec Function(ArgType1, ..., ArgTypeN) -> ReturnType.</pre>
     <p>
       Also, for documentation purposes, argument names can be given:
     </p>
     <pre>
--spec Function(ArgName1 :: Type1, ..., ArgNameN :: TypeN) -> RT.</pre>
+  -spec Function(ArgName1 :: Type1, ..., ArgNameN :: TypeN) -> RT.</pre>
     <p>
       A function specification can be overloaded. 
       That is, it can have several types, separated by a semicolon (<c>;</c>):
     </p>
     <pre>
--spec foo(T1, T2) -> T3
-       ; (T4, T5) -> T6.</pre>
+  -spec foo(T1, T2) -> T3
+         ; (T4, T5) -> T6.</pre>
     <p>
       A current restriction, which currently results in a warning 
       (OBS: not an error) by the compiler, is that the domains of
@@ -412,8 +436,8 @@ mod:orddict(atom(), term())</pre>
       For example, the following specification results in a warning:
     </p>
     <pre>
--spec foo(pos_integer()) -> pos_integer()
-       ; (integer()) -> integer().</pre>
+  -spec foo(pos_integer()) -> pos_integer()
+         ; (integer()) -> integer().</pre>
     <p>
       Type variables can be used in specifications to specify relations for 
       the input and output arguments of a function. 
@@ -421,47 +445,66 @@ mod:orddict(atom(), term())</pre>
       polymorphic identity function:
     </p>
     <pre>
--spec id(X) -> X.</pre>
+  -spec id(X) -> X.</pre>
     <p>
       However, note that the above specification does not restrict the input 
       and output type in any way. 
-      We can constrain these types by guard-like subtype constraints:
+      We can constrain these types by guard-like subtype constraints
+      and provide bounded quantification:
     </p>
-    <pre>
--spec id(X) -> X when is_subtype(X, tuple()).</pre>
+    <pre>  -spec id(X) -> X when X :: tuple().</pre>
     <p>
-    or equivalently by the more succinct and more modern form of the above:
-    </p>
-    <pre>
--spec id(X) -> X when X :: tuple().</pre>
-    <p>
-      and provide bounded quantification. Currently, the <c>::</c> constraint
-      (the <c>is_subtype/2</c> guard) is the only guard constraint which can 
-      be used in the <c>'when'</c> part of a <c>'-spec'</c> attribute.
+      Currently, the <c>::</c> constraint (read as <c>is_subtype</c>) is
+      the only guard constraint which can be used in the <c>'when'</c>
+      part of a <c>'-spec'</c> attribute.
     </p>
+    <note>
+      <p>
+      The above function specification, using multiple occurrences of
+      the same type variable, provides more type information than the
+      function specification below where the type variables are missing:
+      </p>
+      <pre>  -spec id(tuple()) -> tuple().</pre>
+      <p>
+	The latter specification says that the function takes some tuple
+	and returns some tuple, while the one with the <c>X</c> type
+	variable specifies that the function takes a tuple and returns
+	<em>the same</em> tuple.
+      </p>
+      <p>
+	However, it's up to the tools that process the specs to choose
+	whether to take this extra information into account or ignore it.
+      </p>
+    </note>
     <p>
       The scope of an <c>::</c> constraint is the 
       <c>(...) -> RetType</c> 
       specification after which it appears. To avoid confusion, 
       we suggest that different variables are used in different
-      constituents of	an overloaded contract as in the example below:
+      constituents of an overloaded contract as in the example below:
     </p>
     <pre>
--spec foo({X, integer()}) -> X when X :: atom()
-       ; ([Y]) -> Y when Y :: number().</pre>
+  -spec foo({X, integer()}) -> X when X :: atom()
+         ; ([Y]) -> Y when Y :: number().</pre>
+    <note>
+      For backwards compatibility the following form is also allowed:
+      <pre>  -spec id(X) -> X when is_subtype(X, tuple()).</pre>
+      <p>
+	but its use is discouraged. It will be taken out in a future
+	Erlang/OTP release.
+      </p>
+    </note>
     <p>
       Some functions in Erlang are not meant to return; 
       either because they define servers or because they are used to 
       throw exceptions as the function below:
     </p>
-    <pre>
-my_error(Err) -> erlang:throw({error, Err}).</pre>
+    <pre>  my_error(Err) -> erlang:throw({error, Err}).</pre>
     <p>
-      For such functions we recommend the use of the special no_return() 
+      For such functions we recommend the use of the special <c>no_return()</c>
       type for their "return", via a contract of the form:
     </p>
-    <pre>
--spec my_error(term()) -> no_return().</pre>
+    <pre>  -spec my_error(term()) -> no_return().</pre>
   </section>
 </chapter>