Merge tag 'OTP-19.0' into sverker/19/binary_to_atom-utf8-crash/ERL-474/OTP-14590

1 files changed, 304 insertions, 0 deletions

diff --git a/lib/stdlib/doc/src/erl_anno.xml b/lib/stdlib/doc/src/erl_anno.xml
new file mode 100644
index 0000000000..f316f63d98
--- /dev/null
+++ b/lib/stdlib/doc/src/erl_anno.xml
@@ -0,0 +1,304 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2015</year>
+      <year>2016</year>
+      <holder>Ericsson AB, All Rights Reserved</holder>
+    </copyright>
+    <legalnotice>
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+ 
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>erl_anno</title>
+    <prepared>Hans Bolinder</prepared>
+    <responsible>Kenneth Lundin</responsible>
+    <docno>1</docno>
+    <approved></approved>
+    <checked></checked>
+    <date>2015-02-26</date>
+    <rev>A</rev>
+    <file>erl_anno.xml</file>
+  </header>
+  <module>erl_anno</module>
+  <modulesummary>Abstract datatype for the annotations of the Erlang Compiler.
+  </modulesummary>
+
+  <description>
+    <p>This module provides an abstract type that is used by the
+      Erlang Compiler and its helper modules for holding data such as
+      column, line number, and text. The data type is a collection of
+      <marker id="annotations"/><em>annotations</em> as
+      described in the following.</p>
+
+    <p>The Erlang Token Scanner returns tokens with a subset of
+      the following annotations, depending on the options:</p>
+
+    <taglist>
+      <tag><c>column</c></tag>
+      <item><p>The column where the token begins.</p></item>
+      <tag><c>location</c></tag>
+      <item><p>The line and column where the token begins, or
+        just the line if the column is unknown.</p></item>
+      <tag><c>text</c></tag>
+      <item><p>The token's text.</p></item>
+    </taglist>
+
+    <p>From this, the following annotation is derived:</p>
+
+    <taglist>
+      <tag><c>line</c></tag>
+      <item><p>The line where the token begins.</p></item>
+    </taglist>
+
+    <p>This module also supports the following annotations,
+      which are used by various modules:</p>
+
+    <taglist>
+      <tag><c>file</c></tag>
+      <item><p>A filename.</p></item>
+      <tag><c>generated</c></tag>
+      <item><p>A Boolean indicating if the abstract code is
+        compiler-generated. The Erlang Compiler does not emit warnings
+        for such code.</p></item>
+      <tag><c>record</c></tag>
+      <item><p>A Boolean indicating if the origin of the abstract
+        code is a record. Used by
+        <seealso marker="dialyzer:dialyzer">Dialyzer</seealso>
+        to assign types to tuple elements.</p>
+      </item>
+    </taglist>
+
+    <p>The functions
+      <seealso marker="erl_scan#column/1"><c>column()</c></seealso>,
+      <seealso marker="erl_scan#end_location/1"><c>end_location()</c></seealso>,
+      <seealso marker="erl_scan#line/1"><c>line()</c></seealso>,
+      <seealso marker="erl_scan#location/1"><c>location()</c></seealso>, and
+      <seealso marker="erl_scan#text/1"><c>text()</c></seealso>
+      in the <c>erl_scan</c> module can be used for inspecting
+      annotations in tokens.</p>
+
+    <p>The functions
+      <seealso marker="erl_parse#anno_from_term/1">
+      <c>anno_from_term()</c></seealso>,
+      <seealso marker="erl_parse#anno_to_term/1">
+      <c>anno_to_term()</c></seealso>,
+      <seealso marker="erl_parse#fold_anno/3"><c>fold_anno()</c></seealso>,
+      <seealso marker="erl_parse#map_anno/2"><c>map_anno()</c></seealso>,
+      <seealso marker="erl_parse#mapfold_anno/3">
+      <c>mapfold_anno()</c></seealso>,
+      and <seealso marker="erl_parse#new_anno/1"><c>new_anno()</c></seealso>,
+      in the <c>erl_parse</c> module can be
+      used for manipulating annotations in abstract code.</p>
+  </description>
+
+  <datatypes>
+    <datatype>
+      <name>anno()</name>
+      <desc><p>A collection of annotations.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="anno_term"></name>
+      <desc>
+        <p>The term representing a collection of annotations. It is
+          either a <c>location()</c> or a list of key-value pairs.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="column"></name>
+    </datatype>
+    <datatype>
+      <name name="line"></name>
+    </datatype>
+    <datatype>
+      <name name="location"></name>
+    </datatype>
+    <datatype>
+      <name name="text"></name>
+    </datatype>
+  </datatypes>
+
+  <funcs>
+    <func>
+      <name name="column" arity="1"/>
+      <fsummary>Return the column.</fsummary>
+      <type name="column"></type>
+      <desc>
+        <p>Returns the column of the annotations <anno>Anno</anno>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="end_location" arity="1"/>
+      <fsummary>Return the end location of the text.</fsummary>
+      <type name="location"></type>
+      <desc>
+        <p>Returns the end location of the text of the
+          annotations <anno>Anno</anno>. If there is no text,
+          <c>undefined</c> is returned.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="file" arity="1"/>
+      <fsummary>Return the filename.</fsummary>
+      <type name="filename"></type>
+      <desc>
+        <p>Returns the filename of the annotations <anno>Anno</anno>.
+          If there is no filename, <c>undefined</c> is returned.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="from_term" arity="1"/>
+      <fsummary>Return annotations given a term.</fsummary>
+      <desc>
+        <p>Returns annotations with representation <anno>Term</anno>.</p>
+        <p>See also <seealso marker="#to_term/1">to_term()</seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="generated" arity="1"/>
+      <fsummary>Return the generated Boolean.</fsummary>
+      <type name="generated"></type>
+      <desc>
+        <p>Returns <c>true</c> if annotations <anno>Anno</anno>
+          is marked as generated. The default is to return
+          <c>false</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="is_anno" arity="1"/>
+      <fsummary>Test for a collection of annotations.</fsummary>
+      <desc>
+        <p>Returns <c>true</c> if <anno>Term</anno> is a collection of
+          annotations, otherwise <c>false</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="line" arity="1"/>
+      <fsummary>Return the line.</fsummary>
+      <type name="line"></type>
+      <desc>
+        <p>Returns the line of the annotations <anno>Anno</anno>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="location" arity="1"/>
+      <fsummary>Return the location.</fsummary>
+      <type name="location"></type>
+      <desc>
+        <p>Returns the location of the annotations <anno>Anno</anno>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="new" arity="1"/>
+      <fsummary>Create a new collection of annotations.</fsummary>
+      <type name="location"></type>
+      <desc>
+        <p>Creates a new collection of annotations given a location.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="set_file" arity="2"/>
+      <fsummary>Modify the filename.</fsummary>
+      <type name="filename"></type>
+      <desc>
+        <p>Modifies the filename of the annotations <anno>Anno</anno>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="set_generated" arity="2"/>
+      <fsummary>Modify the generated marker.</fsummary>
+      <type name="generated"></type>
+      <desc>
+        <p>Modifies the generated marker of the annotations <anno>Anno</anno>.
+        </p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="set_line" arity="2"/>
+      <fsummary>Modify the line.</fsummary>
+      <type name="line"></type>
+      <desc>
+        <p>Modifies the line of the annotations <anno>Anno</anno>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="set_location" arity="2"/>
+      <fsummary>Modify the location.</fsummary>
+      <type name="location"></type>
+      <desc>
+        <p>Modifies the location of the annotations <anno>Anno</anno>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="set_record" arity="2"/>
+      <fsummary>Modify the record marker.</fsummary>
+      <type name="record"></type>
+      <desc>
+        <p>Modifies the record marker of the annotations <anno>Anno</anno>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="set_text" arity="2"/>
+      <fsummary>Modify the text.</fsummary>
+      <type name="text"></type>
+      <desc>
+        <p>Modifies the text of the annotations <anno>Anno</anno>.</p>
+      </desc>
+    </func>
+    <func>
+
+      <name name="text" arity="1"/>
+      <fsummary>Return the text.</fsummary>
+      <type name="text"></type>
+      <desc>
+        <p>Returns the text of the annotations <anno>Anno</anno>.
+          If there is no text, <c>undefined</c> is returned.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="to_term" arity="1"/>
+      <fsummary>Return the term representing a collection of annotations.
+      </fsummary>
+      <desc>
+        <p>Returns the term representing the annotations <anno>Anno</anno>.</p>
+        <p>See also <seealso marker="#from_term/1">from_term()</seealso>.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>See Also</title>
+    <p><seealso marker="erl_parse"><c>erl_parse(3)</c></seealso>,
+      <seealso marker="erl_scan"><c>erl_scan(3)</c></seealso></p>
+  </section>
+</erlref>