From 4a3bc9f9ebd31dc092dcccbfc21cdd9cca6af6c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Sun, 30 May 2010 10:57:18 +0200
Subject: [PATCH] Document erlang:make_fun/3

Document the erlang:make_fun/3 BIF, so that tools that analyze
Erlang code may depend on its behavior. By documenting the BIF,
we implicitly promise not to remove it without prior deprecation
at least one release before the removal.

Before reaching the decision to document erlang:make_fun/3,
I attempted to transform external funs to internal fun and
back again in v3_kernel so that tools would not have to care,
but I encountered the following issues:

First I tried to translate all funs that looked something like:

  fun(A1, ... AN) -> M:F(A1, ... AN) end

to external funs, but that transformation is not safe if
M happens to be an instance of a parameterized module.

My second attempt was to use a non-standard 'id' annotation
in funs that started out as external funs, and transform those
funs back to external funs in v3_kernel, but that failed because
the inliner kills 'id' annotations.

That problem could probably be solved by inventing another
annotation, but now the solutions are becoming too complex for
my taste. Also, there is always the risk that the inliner could
surprise us with an optimization that would lose the annotation so
that an external fun would become internal.
---
 erts/doc/src/erlang.xml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index e683f161f11e..55a18afffd07 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -1794,6 +1794,25 @@ os_prompt%</pre>
         <p>Allowed in guard tests.</p>
       </desc>
     </func>
+    <func>
+      <name>erlang:make_fun(Module, Function, Arity) -> fun()</name>
+      <fsummary>Create an external fun</fsummary>
+      <type>
+        <v>Module = Function = atom()</v>
+        <v>Arity = integer()</v>
+      </type>
+      <desc>
+        <p><c>erlang:make_fun/3</c> is internally used to implement
+	  the <c>fun Module:Function/Arity</c> syntax.
+	  From R14A, variables may be used in the
+	  <c>fun Module:Function/Arity</c> syntax (not only literals),
+	  so there is no longer any reason to call this BIF directly.</p>
+	<warning><p>Calling this BIF directly from your own code is not
+	    recommended. However, tools that analyze Erlang code may want
+	    to handle calls to this BIF specially to improve the analysis.
+	  </p></warning>
+      </desc>
+    </func>
     <func>
       <name>length(List) -> int()</name>
       <fsummary>Length of a list</fsummary>