From 714570912d678c10f4aa4b6a6692d958e0fc7fe7 Mon Sep 17 00:00:00 2001
From: Siri Hansen <siri@erlang.org>
Date: Wed, 28 Sep 2016 16:40:19 +0200
Subject: Document the order of directories added with code:add_pathsa/1

code:add_pathsa/1 reverts the list of directories when adding it at
the beginning of the code path. The command line option '-pa' behaves
in the same way. This is now documented.
---
 erts/doc/src/erl.xml        |  8 +++++---
 lib/kernel/doc/src/code.xml | 11 ++++++++---
 lib/sasl/doc/src/script.xml |  2 +-
 3 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index f62d3fb170..eb1d24cf12 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -393,9 +393,11 @@
       <tag><c><![CDATA[-pa Dir1 Dir2 ...]]></c></tag>
       <item>
         <p>Adds the specified directories to the beginning of the code
-          path, similar to <c><![CDATA[code:add_pathsa/1]]></c>; see
-          <seealso marker="kernel:code"><c>code(3)</c></seealso>.
-	  As an alternative to <c>-pa</c>, if several directories are
+          path, similar to <seealso marker="kernel:code#add_pathsa/1">
+	  <c><![CDATA[code:add_pathsa/1]]></c></seealso>. Note that the
+	  order of the given directories will be reversed in the
+	  resulting path.</p>
+	<p>As an alternative to <c>-pa</c>, if several directories are
 	  to be prepended to the code path and the directories have a
 	  common parent directory, that parent directory can be
 	  specified in environment variable <c>ERL_LIBS</c>; see
diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml
index 4db377bcde..3143cdc825 100644
--- a/lib/kernel/doc/src/code.xml
+++ b/lib/kernel/doc/src/code.xml
@@ -382,9 +382,14 @@ zip:create("mnesia-4.4.7.ez",
       <name name="add_pathsa" arity="1"/>
       <fsummary>Add directories to the beginning of the code path.</fsummary>
       <desc>
-        <p>Adds the directories in <c><anno>Dirs</anno></c> to the beginning of
-          the code path. If a <c><anno>Dir</anno></c> exists, it is removed
-          from the old position in the code path.</p>
+	<p>Traverses <c><anno>Dirs</anno></c> and adds
+	  each <c><anno>Dir</anno></c> to the beginning of the code
+	  path. This means that the order of <c><anno>Dirs</anno></c>
+	  is reversed in the resulting code path. For example, if you
+	  add <c>[Dir1,Dir2]</c>, the resulting path will
+	  be <c>[Dir2,Dir1|OldCodePath]</c>.</p>
+	<p>If a <c><anno>Dir</anno></c> already exists in the code
+	  path, it is removed from the old position.</p>
 	<p>Always returns <c>ok</c>, regardless of the validity of each
           individual <c><anno>Dir</anno></c>.</p>
       </desc>
diff --git a/lib/sasl/doc/src/script.xml b/lib/sasl/doc/src/script.xml
index 8ed132354d..b40ff28179 100644
--- a/lib/sasl/doc/src/script.xml
+++ b/lib/sasl/doc/src/script.xml
@@ -88,7 +88,7 @@
           follows:</p>
         <list type="bulleted">
           <item><c>-pa Dir1 Dir2 ... DirN</c> adds the directories
-          <c>Dir1, Dir2, ..., DirN</c> to the front of the initial
+          <c>DirN, DirN-1, ..., Dir2, Dir1</c> to the front of the initial
            load path.</item>
           <item><c>-pz Dir1 Dir2 ... DirN</c> adds the directories
           <c>Dir1, Dir2, ..., DirN</c> to the end of the initial
-- 
cgit v1.2.3