From dcd4d82b67c250987b17f61043d764d446ed00e3 Mon Sep 17 00:00:00 2001
From: Patrik Nyblom <pan@erlang.org>
Date: Fri, 28 May 2010 18:10:25 +0200
Subject: Add -compile({no_auto_import,[F/A]}) doc to compiler.xml

---
 lib/compiler/doc/src/compile.xml | 74 ++++++++++++++++++++++++++++++----------
 1 file changed, 56 insertions(+), 18 deletions(-)

(limited to 'lib/compiler')

diff --git a/lib/compiler/doc/src/compile.xml b/lib/compiler/doc/src/compile.xml
index bbd3f1043d..3a70f6277b 100644
--- a/lib/compiler/doc/src/compile.xml
+++ b/lib/compiler/doc/src/compile.xml
@@ -310,6 +310,23 @@
 	    (there will not even be a warning if there is a mismatch).</p>
           </item>
 
+          <tag><c>{no_auto_import,[F/A, ...]}</c></tag>
+          <item>
+	  <p>Makes the function <c>F/A</c> no longer beeing
+          auto-imported from the module <c>erlang</c>, which resolves
+          BIF name clashes. This option has to be used to resolve name
+          clashes with BIFs auto-imported before R14A, if one wants to
+          call the local function with the same name as an
+          auto-imported BIF without module prefix.</p>
+	  <note>
+	  <p>From R14A and forward, the compiler resolves calls
+	  without module prefix to local or imported functions before
+	  trying auto-imported BIFs. If the BIF is to be
+	  called, use the <c>erlang</c> module prefix in the call, not
+	  <c>{ no_auto_import,[F/A, ...]}</c></p>
+	  </note>
+	  </item>
+
         </taglist>
 
         <p>If warnings are turned on (the <c>report_warnings</c> option
@@ -338,21 +355,37 @@
 
           <tag><c>nowarn_bif_clash</c></tag>
           <item>
-            <p>By default, there will be a compilation error if a
-              module contains an exported function with the same name
-              as an auto-imported BIF (such as <c>size/1</c>) AND
-              there is a call to it without a qualifying module name.
-              The reason is that the BIF will be called, not
-	      the function in the same module. The recommended way to
-	      eliminate that warning is to use a call with a module
-	      name - either <c>erlang</c> to call the BIF or
-	      <c>?MODULE</c> to call the function in the same module.
-              The warning can also be turned off using this option,
-	      but that is not recommended.</p>
-
-	    <p><em>The use of this option is strongly discouraged,
-	    as code that uses it will probably break in a future
-	    major release (R14 or R15).</em></p>
+            <p>By default, the compiler will issue an error or warning
+            when replacing an auto-imported BIF. For local functions
+            having names clashing with an auto-imported BIF, the error
+            or warning is issued whenever it is called without using a
+            module prefix. For explicitly imported functions, the
+            error or warning will be issued as soon as it's imported
+            (regardless of calls). If the auto-imported BIF was present
+            before OTP R14A it will be a fatal error to override it,
+            otherwise only a warning will be issued.</p>
+
+	    <warning>
+	    <p>Beginning with R14A, the compiler no longer calls the
+	    auto-imported BIF if the name clashes with a local or
+	    explicitly imported function and a call without explicit
+	    module name is issued. Instead the local or imported
+	    function is called. Use of <c>nowarn_bif_clash</c> makes a
+	    module calling functions clashing with autoimported BIFs
+	    compile with both the old and new compilers, but with
+	    completely different semantics, why a warning is always
+	    issued if any code uses this option.</p>
+
+	    <p>The use of this option has always been strongly discouraged.
+	    From OTP R14A and forward it's also deprecated.</p>
+	    <p>The only module who actually could have some legitimate use for
+	    this option is the module <c>erlang</c>, which in
+	    itself contains auto-imported functions, other modules
+	    should never use it.</p>
+	    <p>To resolve BIF clashes, use explicit module names or the
+	    <c>{no_auto_import,[F/A]}</c> directive.</p>
+	    <p><c>nowarn_bif_clash</c> <em>will</em> be removed in a future release.</p>
+	    </warning>
           </item>
 
           <tag><c>{nowarn_bif_clash, FAs}</c></tag>
@@ -360,9 +393,14 @@
             <p>Turns off warnings as <c>nowarn_bif_clash</c> but only
 	      for the mentioned local functions. <c>FAs</c> is a tuple
 	      <c>{Name,Arity}</c> or a list of such tuples.</p>
-	      <p><em>The use of this option is strongly discouraged,
-	      as code that uses it will probably break in a future
-	      major release (R14 or R15).</em></p>
+	    <warning>
+	    <p>The use of this option has always been strongly discouraged.
+	    From OTP R14A and forward it's also deprecated and a warning will be issued
+	    whenever it is used.</p>
+	    <p>To resolve BIF clashes, use explicit module names or the
+	    <c>{no_auto_import,[F/A]}</c> directive instead.</p>
+	    <p><c>nowarn_bif_clash</c> <em>will</em> be removed in a future release.</p>
+	    </warning>
           </item>
 
 	  <tag><c>warn_export_all</c></tag>
-- 
cgit v1.2.3