stdlib: Update erl_parse(3)

Calls to map_anno(), fold_anno(), and mapfold_anno() with lists of
erl_parse trees have been replaced. Those functions accept lists of
erl_parse trees, but it was not the intention when the functions were
introduced, and it is not documented.

4 files changed, 114 insertions, 70 deletions

diff --git a/lib/stdlib/doc/src/erl_parse.xml b/lib/stdlib/doc/src/erl_parse.xml
index 0938b5dec3..13be488c33 100644
--- a/lib/stdlib/doc/src/erl_parse.xml
+++ b/lib/stdlib/doc/src/erl_parse.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2015</year>
+      <year>1996</year><year>2016</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -44,21 +44,33 @@
   </description>
   <datatypes>
     <datatype>
-      <name name="abstract_clause"></name>
-      <desc><p>Parse tree for Erlang clause.</p>
+      <name>abstract_clause()</name>
+      <desc><p><marker id="type-abstract_clause"/>
+        Abstract form of an Erlang clause.</p>
       </desc>
     </datatype>
     <datatype>
-      <name name="abstract_expr"></name>
-      <desc><p>Parse tree for Erlang expression.</p>
+      <name>abstract_expr()</name>
+      <desc><p><marker id="type-abstract_expr"/>
+        Abstract form of an Erlang expression.</p>
       </desc>
     </datatype>
     <datatype>
-      <name name="abstract_form"></name>
-      <desc><p>Parse tree for Erlang form.</p>
+      <name>abstract_form()</name>
+      <desc><p><marker id="type-abstract_form"/>
+        Abstract form of an Erlang form.</p>
       </desc>
     </datatype>
     <datatype>
+      <name>abstract_type()</name>
+      <desc><p><marker id="type-abstract_type"/>
+        Abstract form of an Erlang type.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="erl_parse_tree"></name>
+    </datatype>
+    <datatype>
       <name name="error_description"></name>
     </datatype>
     <datatype>
@@ -180,7 +192,7 @@
         <p>Converts the Erlang data structure <c><anno>Data</anno></c> into an
           abstract form of type <c><anno>AbsTerm</anno></c>.</p>
         <p>The <c><anno>Line</anno></c> option is the line that will
-          be assigned to each node of the abstract form.</p>
+          be assigned to each node of <c><anno>AbsTerm</anno></c>.</p>
         <p>The <c><anno>Encoding</anno></c> option is used for
           selecting which integer lists will be considered
           as strings. The default is to use the encoding returned by
@@ -196,47 +208,53 @@
     <func>
       <name name="map_anno" arity="2"/>
       <fsummary>
-        Map a function over the annotations of an abstract form
+        Map a function over the annotations of a <c>erl_parse</c> tree
       </fsummary>
       <desc>
-        <p>Modifies the abstract form <anno>Abstr</anno> by applying
-          <anno>Fun</anno> on every collection of annotations of the
-          abstract form. The abstract form is traversed in a
-          depth-first, left-to-right, fashion.
+        <p>Modifies the <c>erl_parse</c> tree <c><anno>Abstr</anno></c>
+	  by applying <c><anno>Fun</anno></c> on each collection of
+	  annotations of the nodes of the <c>erl_parse</c> tree. The
+	  <c>erl_parse</c> tree is traversed in a depth-first,
+	  left-to-right, fashion.
         </p>
       </desc>
     </func>
     <func>
       <name name="fold_anno" arity="3"/>
       <fsummary>
-        Fold a function over the annotations of an abstract form
+        Fold a function over the annotations of a <c>erl_parse</c> tree
       </fsummary>
       <desc>
-        <p>Updates an accumulator by applying <anno>Fun</anno> on
-          every collection of annotations of the abstract form
-          <anno>Abstr</anno>. The first call to <anno>Fun</anno> has
-          <anno>AccIn</anno> as argument, and the returned accumulator
-          <anno>AccOut</anno> is passed to the next call, and so on.
-          The final value of the accumulator is returned. The abstract
-          form is traversed in a depth-first, left-to-right, fashion.
+        <p>Updates an accumulator by applying <c><anno>Fun</anno></c> on
+          each collection of annotations of the <c>erl_parse</c> tree
+          <c><anno>Abstr</anno></c>. The first call to
+          <c><anno>Fun</anno></c> has <c><anno>AccIn</anno></c> as
+          argument, and the returned accumulator
+          <c><anno>AccOut</anno></c> is passed to the next call, and
+          so on. The final value of the accumulator is returned. The
+          <c>erl_parse</c> tree is traversed in a depth-first, left-to-right,
+          fashion.
         </p>
       </desc>
     </func>
     <func>
       <name name="mapfold_anno" arity="3"/>
       <fsummary>
-        Map and fold a function over the annotations of an abstract form
+        Map and fold a function over the annotations of a
+        <c>erl_parse</c> tree
       </fsummary>
       <desc>
-        <p>Modifies the abstract form <anno>Abstr</anno> by applying
-          <anno>Fun</anno> on every collection of annotations of the
-          abstract form, while at the same time updating an
-          accumulator. The first call to <anno>Fun</anno> has
-          <anno>AccIn</anno> as second argument, and the returned
-          accumulator <anno>AccOut</anno> is passed to the next call,
-          and so on. The modified abstract form as well as the the
-          final value of the accumulator is returned. The abstract
-          form is traversed in a depth-first, left-to-right, fashion.
+        <p>Modifies the <c>erl_parse</c> tree <c><anno>Abstr</anno></c>
+	  by applying <c><anno>Fun</anno></c> on each collection of
+	  annotations of the nodes of the <c>erl_parse</c> tree, while
+	  at the same time updating an accumulator. The first call to
+	  <c><anno>Fun</anno></c> has <c><anno>AccIn</anno></c> as
+	  second argument, and the returned accumulator
+	  <c><anno>AccOut</anno></c> is passed to the next call, and
+	  so on. The modified <c>erl_parse</c> tree as well as the the
+	  final value of the accumulator are returned. The
+	  <c>erl_parse</c> tree is traversed in a depth-first,
+	  left-to-right, fashion.
         </p>
       </desc>
     </func>
@@ -246,12 +264,15 @@
         Create new annotations
       </fsummary>
       <desc>
-        <p>Creates an abstract form from a term which has the same
-          structure as an abstract form, but <seealso
-          marker="erl_anno#type-location">locations</seealso> where the
-          abstract form has annotations. For each location, <seealso
-          marker="erl_anno#new/1"><c>erl_anno:new/1</c></seealso> is
-          called, and the annotations replace the location.
+        <p>Assumes that <c><anno>Term</anno></c> is a term with the same
+          structure as a <c>erl_parse</c> tree, but with <seealso
+          marker="erl_anno#type-location">locations</seealso> where a
+          <c>erl_parse</c> tree has collections of annotations.
+          Returns a <c>erl_parse</c> tree where each location <c>L</c>
+          has been replaced by the value returned by <seealso
+          marker="erl_anno#new/1"><c>erl_anno:new(L)</c></seealso>.
+          The term <c><anno>Term</anno></c> is traversed in a
+          depth-first, left-to-right, fashion.
         </p>
       </desc>
     </func>
@@ -261,12 +282,14 @@
         Return annotations as terms
       </fsummary>
       <desc>
-        <p>Assumes that <anno>Term</anno> is a term with the same
-          structure as an abstract form, but with terms, T say, on
-          those places where an abstract form has annotations. Returns
-          an abstract form where every term T has been replaced by the
-          value returned by calling <c>erl_anno:from_term(T)</c>. The
-          term <anno>Term</anno> is traversed in a depth-first,
+        <p>Assumes that <c><anno>Term</anno></c> is a term with the same
+          structure as a <c>erl_parse</c> tree, but with terms,
+          <c>T</c> say, where a <c>erl_parse</c> tree has collections
+          of annotations. Returns a <c>erl_parse</c> tree where each
+          term <c>T</c> has been replaced by the value returned by
+          <seealso marker="erl_anno#from_term/1">
+          <c>erl_anno:from_term(T)</c></seealso>. The term
+          <c><anno>Term</anno></c> is traversed in a depth-first,
           left-to-right, fashion.
         </p>
       </desc>
@@ -277,10 +300,13 @@
         Return the representation of annotations
       </fsummary>
       <desc>
-        <p>Returns a term where every collection of annotations Anno of
-          <anno>Abstr</anno> has been replaced by the term returned by
-          calling <c>erl_anno:to_term(Anno)</c>. The abstract form is
-          traversed in a depth-first, left-to-right, fashion.
+        <p>Returns a term where each collection of annotations
+          <c>Anno</c> of the nodes of the <c>erl_parse</c> tree
+          <c><anno>Abstr</anno></c> has been replaced by the term
+          returned by <seealso marker="erl_anno#to_term/1">
+          <c>erl_anno:to_term(Anno)</c></seealso>. The
+          <c>erl_parse</c> tree is traversed in a depth-first,
+          left-to-right, fashion.
         </p>
       </desc>
     </func>
diff --git a/lib/stdlib/src/erl_lint.erl b/lib/stdlib/src/erl_lint.erl
index 4a42754d92..9ef4acdf5f 100644
--- a/lib/stdlib/src/erl_lint.erl
+++ b/lib/stdlib/src/erl_lint.erl
@@ -696,7 +696,12 @@ set_form_file({function,L,N,A,C}, File) ->
 set_form_file(Form, _File) ->
     Form.
 
+set_file(Ts, File) when is_list(Ts) ->
+    [anno_set_file(T, File) || T <- Ts];
 set_file(T, File) ->
+    anno_set_file(T, File).
+
+anno_set_file(T, File) ->
     F = fun(Anno) -> erl_anno:set_file(File, Anno) end,
     erl_parse:map_anno(F, T).
 
diff --git a/lib/stdlib/src/erl_parse.yrl b/lib/stdlib/src/erl_parse.yrl
index a525c2ae82..b1c574ea60 100644
--- a/lib/stdlib/src/erl_parse.yrl
+++ b/lib/stdlib/src/erl_parse.yrl
@@ -2,7 +2,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 1996-2015. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2016. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -1489,11 +1489,16 @@ type_preop_prec('-') -> {600,700};
 type_preop_prec('bnot') -> {600,700};
 type_preop_prec('#') -> {700,800}.
 
+-type erl_parse_tree() :: abstract_clause()
+                        | abstract_expr()
+                        | abstract_form()
+                        | abstract_type().
+
 -spec map_anno(Fun, Abstr) -> NewAbstr when
       Fun :: fun((Anno) -> Anno),
       Anno :: erl_anno:anno(),
-      Abstr :: abstract_form() | abstract_expr(),
-      NewAbstr :: abstract_form() | abstract_expr().
+      Abstr :: erl_parse_tree(),
+      NewAbstr :: erl_parse_tree().
 
 map_anno(F0, Abstr) ->
     F = fun(A, Acc) -> {F0(A), Acc} end,
@@ -1506,8 +1511,8 @@ map_anno(F0, Abstr) ->
       Acc0 :: term(),
       AccIn :: term(),
       AccOut :: term(),
-      Abstr :: abstract_form() | abstract_expr(),
-      NewAbstr :: abstract_form() | abstract_expr().
+      Abstr :: erl_parse_tree(),
+      NewAbstr :: erl_parse_tree().
 
 fold_anno(F0, Acc0, Abstr) ->
     F = fun(A, Acc) -> {A, F0(A, Acc)} end,
@@ -1521,26 +1526,26 @@ fold_anno(F0, Acc0, Abstr) ->
       Acc1 :: term(),
       AccIn :: term(),
       AccOut :: term(),
-      Abstr :: abstract_form() | abstract_expr(),
-      NewAbstr :: abstract_form() | abstract_expr().
+      Abstr :: erl_parse_tree(),
+      NewAbstr :: erl_parse_tree().
 
 mapfold_anno(F, Acc0, Abstr) ->
     modify_anno1(Abstr, Acc0, F).
 
 -spec new_anno(Term) -> Abstr when
       Term :: term(),
-      Abstr :: abstract_form() | abstract_expr().
+      Abstr :: erl_parse_tree().
 
 new_anno(Term) ->
     map_anno(fun erl_anno:new/1, Term).
 
 -spec anno_to_term(Abstr) -> term() when
-      Abstr :: abstract_form() | abstract_expr().
+      Abstr :: erl_parse_tree().
 
 anno_to_term(Abstract) ->
     map_anno(fun erl_anno:to_term/1, Abstract).
 
--spec anno_from_term(Term) -> abstract_form() | abstract_expr() when
+-spec anno_from_term(Term) -> erl_parse_tree() when
       Term :: term().
 
 anno_from_term(Term) ->
diff --git a/lib/stdlib/src/qlc_pt.erl b/lib/stdlib/src/qlc_pt.erl
index 9577d17a85..9f69cd5003 100644
--- a/lib/stdlib/src/qlc_pt.erl
+++ b/lib/stdlib/src/qlc_pt.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 2004-2015. All Rights Reserved.
+%% Copyright Ericsson AB 2004-2016. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -200,7 +200,7 @@ exclude_integers_from_unique_line_numbers(Forms, NodeInfo) ->
 
 find_integers(Forms) ->
     F = fun(A) ->
-                Fs1 = erl_parse:map_anno(fun(_) -> A end, Forms),
+                Fs1 = map_anno(fun(_) -> A end, Forms),
                 ordsets:from_list(integers(Fs1, []))
         end,
     ordsets:to_list(ordsets:intersection(F(anno0()), F(anno1()))).
@@ -319,13 +319,13 @@ badarg(Forms, State) ->
     E0.
 
 lc_nodes(E, NodeInfo) ->
-    erl_parse:map_anno(fun(Anno) ->
-                               N = erl_anno:line(Anno),
-                               [{N, Data}] = ets:lookup(NodeInfo, N),
-                               NData = Data#{inside_lc => true},
-                               true = ets:insert(NodeInfo, {N, NData}),
-                               Anno
-                       end, E).
+    map_anno(fun(Anno) ->
+                     N = erl_anno:line(Anno),
+                     [{N, Data}] = ets:lookup(NodeInfo, N),
+                     NData = Data#{inside_lc => true},
+                     true = ets:insert(NodeInfo, {N, NData}),
+                     Anno
+             end, E).
 
 used_genvar_messages(MsL, S) ->
     [{File,[{Loc,?APIMOD,{used_generator_variable,V}}]}
@@ -416,7 +416,7 @@ intro_anno(LC, Where, QId, NodeInfo) ->
                   true = ets:insert(NodeInfo, {Location,Data}),
                   Anno
           end,
-    erl_parse:map_anno(Fun, save_anno(LC, NodeInfo)).
+    map_anno(Fun, save_anno(LC, NodeInfo)).
 
 compile_errors(FormsNoShadows) ->
     case compile_forms(FormsNoShadows, []) of
@@ -1650,7 +1650,7 @@ reset_anno(T) ->
     set_anno(T, anno0()).
 
 set_anno(T, A) ->
-    erl_parse:map_anno(fun(_L) -> A end, T).
+    map_anno(fun(_L) -> A end, T).
 
 -record(fstate, {state, bind_fun, imported}).
 
@@ -2609,7 +2609,7 @@ save_anno(Abstr, NodeInfo) ->
                 true = ets:insert(NodeInfo, Data),
                 erl_anno:new(N)
         end,
-    erl_parse:map_anno(F, Abstr).
+    map_anno(F, Abstr).
 
 next_slot(T) ->
     I = ets:update_counter(T, var_n, 1),
@@ -2633,7 +2633,7 @@ restore_anno(Abstr, NodeInfo) ->
                         Anno
                 end
         end,
-    erl_parse:map_anno(F, Abstr).
+    map_anno(F, Abstr).
 
 restore_loc(Location, #state{node_info = NodeInfo}) ->
   case ets:lookup(NodeInfo, Location) of
@@ -2872,6 +2872,14 @@ var_mapfold(F, A0, [E0 | Es0]) ->
 var_mapfold(_F, A, E) ->
     {E, A}.
 
+map_anno(F, AbstrList) when is_list(AbstrList) ->
+    [map_anno1(F, Abstr) || Abstr <- AbstrList];
+map_anno(F, Abstr) ->
+    map_anno1(F, Abstr).
+
+map_anno1(F, Abstr) ->
+    erl_parse:map_anno(F, Abstr).
+
 family_list(L) ->
     sofs:to_external(family(L)).