Merge pull request #1566 from bjorng/bjorn/erts/fix-existing-atom-doc/ERL-453

Document that the compiler may optimize away atoms

OTP-14614

1 files changed, 19 insertions, 0 deletions

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 5afac46d21..2465f49581 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -432,6 +432,16 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code>
           <seealso marker="#binary_to_atom/2"><c>binary_to_atom/2</c></seealso>,
           but the atom must exist.</p>
         <p>Failure: <c>badarg</c> if the atom does not exist.</p>
+	<note>
+	  <p>Note that the compiler may optimize away atoms. For
+	  example, the compiler will rewrite
+	  <c>atom_to_list(some_atom)</c> to <c>"some_atom"</c>. If
+	  that expression is the only mention of the atom
+	  <c>some_atom</c> in the containing module, the atom will not
+	  be created when the module is loaded, and a subsequent call
+	  to <c>binary_to_existing_atom(&lt;&lt;"some_atom"&gt;&gt;, utf8)</c>
+	  will fail.</p>
+	</note>
       </desc>
     </func>
 
@@ -2478,6 +2488,15 @@ os_prompt%</pre>
           but only if there already exists such atom.</p>
         <p>Failure: <c>badarg</c> if there does not already exist an atom
           whose text representation is <c><anno>String</anno></c>.</p>
+	<note>
+	  <p>Note that the compiler may optimize away atoms. For
+	  example, the compiler will rewrite
+	  <c>atom_to_list(some_atom)</c> to <c>"some_atom"</c>. If
+	  that expression is the only mention of the atom
+	  <c>some_atom</c> in the containing module, the atom will not
+	  be created when the module is loaded, and a subsequent call
+	  to <c>list_to_existing_atom("some_atom")</c> will fail.</p>
+	</note>
       </desc>
     </func>