From 73fb496d2f072ab5b026d71faec3cc2b8907a268 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= <bjorn@erlang.org>
Date: Wed, 23 Jan 2013 11:41:28 +0100
Subject: Add a warning to discourage abuse of $handle_undefined_function/2

---
 lib/kernel/doc/src/error_handler.xml | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'lib/kernel/doc')

diff --git a/lib/kernel/doc/src/error_handler.xml b/lib/kernel/doc/src/error_handler.xml
index 610b65f0a2..769a869ffa 100644
--- a/lib/kernel/doc/src/error_handler.xml
+++ b/lib/kernel/doc/src/error_handler.xml
@@ -62,6 +62,19 @@
           <c>'$handle_undefined_function'(</c><anno>Function</anno>,
 	  <anno>Args</anno>).
 	</p>
+	<warning>
+	  <p>Defining <c>'$handle_undefined_function'/2</c> in
+	  ordinary application code is highly discouraged. It is very
+	  easy to make subtle errors that can take a long time to
+	  debug.  Furthermore, none of the tools for static code
+	  analysis (such as Dialyzer and Xref) supports the use of
+	  <c>'$handle_undefined_function'/2</c> and no such support
+	  will be added. Only use this function after having carefully
+	  considered other, less dangerous, solutions.  One example of
+	  potential legitimate use is creating stubs for other
+	  sub-systems during testing and debugging.
+	  </p>
+	</warning>
 	<p>Otherwise an <c>undef</c> exception will be raised.</p>
       </desc>
     </func>
-- 
cgit v1.2.3