Add documentation for the new stacktrace syntax

2 files changed, 67 insertions, 12 deletions

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>
 
diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml
index cf2d5034aa..94e40dd077 100644
--- a/system/doc/reference_manual/expressions.xml
+++ b/system/doc/reference_manual/expressions.xml
@@ -1340,9 +1340,9 @@ hello</pre>
     <code type="none">
 try Exprs
 catch
-    [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] ->
+    Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] ->
         ExceptionBody1;
-    [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] ->
+    ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] ->
         ExceptionBodyN
 end</code>
     <p>This is an enhancement of
@@ -1362,10 +1362,12 @@ end</code>
       the evaluation. In that case the exception is caught and
       the patterns <c>ExceptionPattern</c> with the right exception
       class <c>Class</c> are sequentially matched against the caught
-      exception. An omitted <c>Class</c> is shorthand for <c>throw</c>.
-      If a match succeeds and the optional guard sequence
+      exception. If a match succeeds and the optional guard sequence
       <c>ExceptionGuardSeq</c> is true, the corresponding
       <c>ExceptionBody</c> is evaluated to become the return value.</p>
+    <p><c>Stacktrace</c>, if specified, must be the name of a variable
+      (not a pattern). The stack trace is bound to the variable when
+      the corresponding <c>ExceptionPattern</c> matches.</p>
     <p>If an exception occurs during evaluation of <c>Exprs</c> but
       there is no matching <c>ExceptionPattern</c> of the right
       <c>Class</c> with a true guard sequence, the exception is passed
@@ -1373,6 +1375,18 @@ end</code>
       expression.</p>
     <p>If an exception occurs during evaluation of <c>ExceptionBody</c>,
       it is not caught.</p>
+    <p>It is allowed to omit <c>Class</c> and <c>Stacktrace</c>.
+      An omitted <c>Class</c> is shorthand for <c>throw</c>:</p>
+
+    <code type="none">
+try Exprs
+catch
+    ExceptionPattern1 [when ExceptionGuardSeq1] ->
+        ExceptionBody1;
+    ExceptionPatternN [when ExceptionGuardSeqN] ->
+        ExceptionBodyN
+end</code>
+
     <p>The <c>try</c> expression can have an <c>of</c>
       section:
       </p>
@@ -1384,10 +1398,10 @@ try Exprs of
     PatternN [when GuardSeqN] ->
         BodyN
 catch
-    [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] ->
+    Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] ->
         ExceptionBody1;
     ...;
-    [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] ->
+    ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] ->
         ExceptionBodyN
 end</code>
     <p>If the evaluation of <c>Exprs</c> succeeds without an exception,
@@ -1408,10 +1422,10 @@ try Exprs of
     PatternN [when GuardSeqN] ->
         BodyN
 catch
-    [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] ->
+    Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] ->
         ExceptionBody1;
     ...;
-    [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] ->
+    ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] ->
         ExceptionBodyN
 after
     AfterBody
@@ -1470,7 +1484,7 @@ try Expr
 catch
     throw:Term -> Term;
     exit:Reason -> {'EXIT',Reason}
-    error:Reason -> {'EXIT',{Reason,erlang:get_stacktrace()}}
+    error:Reason:Stk -> {'EXIT',{Reason,Stk}}
 end</code>
   </section>