From 01f96ee6197a7b5a2c64353a3b38260994ce5ad5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Thu, 16 Nov 2017 06:10:12 +0100
Subject: Add documentation for the new stacktrace syntax

---
 system/doc/reference_manual/errors.xml | 47 +++++++++++++++++++++++++++++++---
 1 file changed, 44 insertions(+), 3 deletions(-)

(limited to 'system/doc/reference_manual/errors.xml')

diff --git a/system/doc/reference_manual/errors.xml b/system/doc/reference_manual/errors.xml
index b16c5da6eb..16d3e7590e 100644
--- a/system/doc/reference_manual/errors.xml
+++ b/system/doc/reference_manual/errors.xml
@@ -108,14 +108,55 @@
       (see <seealso marker="#exit_reasons">Exit Reason</seealso>),
       and a stack trace (which aids in finding the code location of
       the exception).</p>
-    <p>The stack trace can be retrieved using
-      <c>erlang:get_stacktrace/0</c>
-      from within a <c>try</c> expression, and is returned for 
+    <p>The stack trace can be be bound to a variable from within
+      a <c>try</c> expression, and is returned for
       exceptions of class <c>error</c> from a <c>catch</c> expression.</p>
     <p>An exception of class <c>error</c> is also known as a run-time 
       error.</p>
+
+      <section>
+	<title>The call-stack back trace (stacktrace)</title>
+        <p>The stack back-trace (<em>stacktrace</em>) is a list of
+          <c>{Module,Function,Arity,Location}</c>
+          tuples. The field <c>Arity</c> in the first tuple can be the
+          argument list of that function call instead of an arity integer,
+          depending on the exception.</p>
+
+	<p><c>Location</c> is a (possibly empty) list of two-tuples
+	that can indicate the location in the source code of the
+	function.  The first element is an atom describing the type of
+	information in the second element. The following items can
+	occur:</p>
+	<taglist>
+          <tag><c>file</c></tag>
+          <item>The second element of the tuple is a string (list of
+          characters) representing the filename of the source file
+          of the function.
+          </item>
+          <tag><c>line</c></tag>
+          <item>The second element of the tuple is the line number
+          (an integer &gt; 0) in the source file
+          where the exception occurred or the function was called.
+          </item>
+	</taglist>
+	<warning><p>Developers should rely on stacktrace entries only for
+	debugging purposes.</p>
+	<p>The VM performs tail call optimization, which
+	does not add new entries to the stacktrace, and also limits stacktraces
+	to a certain depth. Furthermore, compiler options, optimizations and
+	future changes may add or remove stacktrace entries, causing any code
+	that expects the stacktrace to be in a certain order or contain specific
+	items to fail.</p>
+	<p>The only exception to this rule is the class <c>error</c> with the
+	reason <c>undef</c> which is guaranteed to include the <c>Module</c>,
+	<c>Function</c> and <c>Arity</c> of the attempted
+	function as the first stacktrace entry.</p>
+	</warning>
+      </section>
+
   </section>
 
+
   <section>
     <title>Handling of Run-time Errors in Erlang</title>
 
-- 
cgit v1.2.3