From db632b91f41c4a01be68d821d6942ff32b86e40b Mon Sep 17 00:00:00 2001
From: Zandra Norman <zandra@erlang.org>
Date: Mon, 23 Jan 2017 16:07:52 +0100
Subject: stdlib: Make gen_event callbacks optional

---
 lib/stdlib/doc/src/gen_event.xml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

(limited to 'lib/stdlib/doc')

diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml
index 42e952fd46..56cb7974a2 100644
--- a/lib/stdlib/doc/src/gen_event.xml
+++ b/lib/stdlib/doc/src/gen_event.xml
@@ -579,6 +579,13 @@ gen_event:stop             ----->  Module:terminate/2
         <v>Extra = term()</v>
       </type>
       <desc>
+        <note>
+          <p>This callback is optional, so callback modules need not export it.
+            If a release upgrade/downgrade with <c>Change={advanced,Extra}</c>
+            specified in the <c>.appup</c> file is made when <c>code_change/3</c>
+            isn't implemented the event handler will crash with an <c>undef</c> error
+            reason.</p>
+        </note>
         <p>This function is called for an installed event handler that
           is to update its internal state during a release
           upgrade/downgrade, that is, when the instruction
@@ -759,6 +766,12 @@ gen_event:stop             ----->  Module:terminate/2
         <v>&nbsp;&nbsp;Id = term()</v>
       </type>
       <desc>
+        <note>
+          <p>This callback is optional, so callback modules need not
+            export it. The <c>gen_event</c> module provides a default
+            implementation of this function that logs about the unexpected
+            <c>Info</c> message, drops it and returns <c>{noreply, State}</c>.</p>
+        </note>
         <p>This function is called for each installed event handler when
           an event manager receives any other message than an event or
           a synchronous request (or a system message).</p>
@@ -815,6 +828,11 @@ gen_event:stop             ----->  Module:terminate/2
         <v>&nbsp;Args = Reason = Term = term()</v>
       </type>
       <desc>
+        <note>
+          <p>This callback is optional, so callback modules need not
+            export it. The <c>gen_event</c> module provides a default
+            implementation without cleanup.</p>
+        </note>
         <p>Whenever an event handler is deleted from an event manager,
           this function is called. It is to be the opposite of
           <seealso marker="#Module:init/1"><c>Module:init/1</c></seealso>
-- 
cgit v1.2.3