From fbfe12dad837300942fc4bf0a3f927b25eaf50a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Tue, 26 Jan 2016 08:11:00 +0100
Subject: Update documentation for code-loading functions

Some of the error reasons were not explained.
---
 lib/kernel/doc/src/code.xml | 61 ++++++++++++++++++++++++++++++++++-----------
 1 file changed, 47 insertions(+), 14 deletions(-)

(limited to 'lib/kernel/doc')

diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml
index eb0f4b7a06..1bd52040a0 100644
--- a/lib/kernel/doc/src/code.xml
+++ b/lib/kernel/doc/src/code.xml
@@ -287,6 +287,46 @@
     was given to <c>set_path/1</c>).</p>
   </section>
 
+  <section>
+    <marker id="error_reasons"></marker>
+    <title>Error Reasons for Code-Loading Functions</title>
+
+    <p>Functions that load code (such as <c>load_file/1</c>) will
+    return <c>{error,Reason}</c> if the load operation fails.
+    Here follows a description of the common reasons.</p>
+
+    <taglist>
+      <tag><c>badfile</c></tag>
+      <item>
+	<p>The object code has an incorrect format or the module
+	name in the object code is not the expected module name.</p>
+      </item>
+
+      <tag><c>nofile</c></tag>
+      <item>
+	<p>No file with object code was found.</p>
+      </item>
+
+      <tag><c>not_purged</c></tag>
+      <item>
+	<p>The object code could not be loaded because an old version
+	of the code already existed.</p>
+      </item>
+
+      <tag><c>on_load_failure</c></tag>
+      <item>
+	<p>The module has an
+	<seealso marker="doc/reference_manual:code_loading#on_load">-on_load function</seealso>
+	that failed when it was called.</p>
+      </item>
+
+      <tag><c>sticky_directory</c></tag>
+      <item>
+	<p>The object code resides in a sticky directory.</p>
+      </item>
+
+    </taglist>
+    </section>
   <datatypes>
     <datatype>
       <name name="load_ret"/>
@@ -411,12 +451,8 @@
           be used to load object code with a module name that is
           different from the file name.</p>
         <p>Returns <c>{module, <anno>Module</anno>}</c> if successful, or
-          <c>{error, nofile}</c> if no object code is found, or
-          <c>{error, sticky_directory}</c> if the object code resides in
-          a sticky directory. Also if the loading fails, an error tuple is
-          returned. See
-          <seealso marker="erts:erlang#load_module/2">erlang:load_module/2</seealso>
-          for possible values of <c><anno>What</anno></c>.</p>
+	<c>{error, Reason}</c> if loading fails.
+	See <seealso marker="#error_reasons">Error Reasons for Code-Loading Functions</seealso> for a description of the possible error reasons.</p>
       </desc>
     </func>
     <func>
@@ -428,7 +464,7 @@
       <desc>
         <p>Does the same as <c>load_file(<anno>Module</anno>)</c>, but
           <c><anno>Filename</anno></c> is either an absolute file name, or a
-          relative file name. The code path is not searched. It returns
+           relative file name. The code path is not searched. It returns
           a value in the same way as
           <seealso marker="#load_file/1">load_file/1</seealso>. Note
           that <c><anno>Filename</anno></c> should not contain the extension (for
@@ -444,7 +480,8 @@
           <seealso marker="#load_file/1">load_file/1</seealso>,
 	  unless the module is already loaded.
           In embedded mode, however, it does not load a module which is not
-          already loaded, but returns <c>{error, embedded}</c> instead.</p>
+          already loaded, but returns <c>{error, embedded}</c> instead.
+	  See <seealso marker="#error_reasons">Error Reasons for Code-Loading Functions</seealso> for a description of other possible error reasons.</p>
       </desc>
     </func>
     <func>
@@ -461,12 +498,8 @@
           comes. Accordingly, <c><anno>Filename</anno></c> is not opened and read by
           the code server.</p>
         <p>Returns <c>{module, <anno>Module</anno>}</c> if successful, or
-          <c>{error, sticky_directory}</c> if the object code resides in
-          a sticky directory, or <c>{error, badarg}</c> if any argument
-          is invalid. Also if the loading fails, an error tuple is
-          returned. See
-          <seealso marker="erts:erlang#load_module/2">erlang:load_module/2</seealso>
-          for possible values of <c><anno>What</anno></c>.</p>
+	<c>{error, Reason}</c> if loading fails.
+	See <seealso marker="#error_reasons">Error Reasons for Code-Loading Functions</seealso> for a description of the possible error reasons.</p>
       </desc>
     </func>
     <func>
-- 
cgit v1.2.3