File 1032-erlang-module-doc-preciser-description-of-error-1-er.patch of Package erlang

From 7029ba1f6e42641cc35d3f129fbc45de1b78b95f Mon Sep 17 00:00:00 2001
From: Kjell Winblad <kjellwinblad@gmail.com>
Date: Fri, 18 Sep 2020 11:22:24 +0200
Subject: [PATCH 22/39] erlang module doc: preciser description of error/1,
 error/2 and exit/1

* The functions does not stop the current process; they raise
  exceptions.

* Specify what the functions are intended for
---
 erts/doc/src/erlang.xml | 73 ++++++++++++++++++++++++++++++-----------
 1 file changed, 54 insertions(+), 19 deletions(-)

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 0d4c46bd9c..7d44e622c4 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -1667,15 +1667,20 @@ b</pre>
 
     <func>
       <name name="error" arity="1"/>
-      <fsummary>Stop execution with a specified reason.</fsummary>
-      <desc>
-        <p>Stops the execution of the calling process with the reason
-          <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
-          is any term. The exit reason is
-          <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c>
-          is a list of the functions most recently called (the current
-          function first). As evaluating this function causes
-          the process to terminate, it has no return value. Example:</p>
+      <fsummary>Raise exception of class error.</fsummary>
+      <desc>
+        <p>Raises exception of class <c>error</c> with the reason
+        <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
+        is any term. The exit reason is <c>{<anno>Reason</anno>,
+        Where}</c>, where <c>Where</c> is a list of the functions most
+        recently called (the current function first). As evaluating
+        this function causes an exception to be thrown, it has no
+        return value. The intent of the exception class <c>error</c> is to
+        signal that an unexpected error has happened (for example, a
+        function is called with a parameter that has an incorrect
+        type). See the guide about <seealso
+        marker="system/reference_manual:errors">errors and error
+        handling</seealso> for additional information. Example:</p>
         <pre>
 > <input>catch error(foobar).</input>
 {'EXIT',{foobar,[{erl_eval,do_apply,5},
@@ -1693,8 +1698,8 @@ b</pre>
       <name name="error" arity="2"/>
       <fsummary>Stop execution with a specified reason.</fsummary>
       <desc>
-        <p>Stops the execution of the calling process with the reason
-          <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
+        <p>Raises exception of class <c>error</c> with the reason
+        <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
           is any term. The exit reason is
           <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c>
           is a list of the functions most recently called (the current
@@ -1702,19 +1707,49 @@ b</pre>
           list of arguments for the current function; in Beam it is used
           to provide the arguments for the current function in
           the term <c>Where</c>. As evaluating this function causes
-          the process to terminate, it has no return value.</p>
+          an exception to be thrown, it has no return value.
+          The intent of the exception class <c>error</c> is to
+          signal that an unexpected error has happened (for example, a
+          function is called with a parameter that has an incorrect
+          type). See the guide about <seealso
+          marker="system/reference_manual:errors">errors and error
+          handling</seealso> for additional information. Example:</p>
+          <p><c>test.erl</c>:</p>
+<pre>
+-module(test).
+-export([example_fun/2]).
+
+example_fun(A1, A2) ->
+    erlang:error(my_error, [A1, A2]).
+</pre>
+<p>Erlang shell:</p>
+<pre>
+<input>6> c(test).</input>
+{ok,test}
+<input>7> test:example_fun(arg1,"this is the second argument").</input>
+** exception error: my_error
+     in function  test:example_fun/2
+         called as test:example_fun(arg1,"this is the second argument")
+ </pre>
       </desc>
     </func>
 
     <func>
       <name name="exit" arity="1"/>
-      <fsummary>Stop execution with a specified reason.</fsummary>
-      <desc>
-        <p>Stops the execution of the calling process with exit reason
-          <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
-          is any term. As
-          evaluating this function causes the process to terminate, it
-          has no return value. Example:</p>
+      <fsummary>Raise exception of class <c>exit</c> with a specified reason.</fsummary>
+      <desc>
+        <p>Raises exception of class <c>exit</c> with exit reason
+        <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c>
+        is any term. As evaluating this function causes an exception
+        to be thrown, it has no return value. This function should be
+        used when the intent is to stop the current process. This
+        function differ from <c>erlang:error/1</c> and
+        <c>erlang:error/2</c> by causing an exception of a different
+        class and by having an exit reason that does
+        not include the list of functions from the call stack. See the
+        guide about <seealso
+        marker="system/reference_manual:errors">errors and error
+        handling</seealso> for additional information. Example:</p>
         <pre>
 > <input>exit(foobar).</input>
 ** exception exit: foobar
-- 
2.26.2