From ca952bc9c64f1501175de834e327b904db6827c2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nicolas=20Mah=C3=A9?= <nicolas@mesg.com>
Date: Wed, 29 Jan 2020 20:43:48 +0700
Subject: [PATCH] Merge PR #5583: Add to the docs of events and handler to set
 a new EventManager to the Context

---
 docs/building-modules/handler.md | 4 +++-
 docs/core/events.md              | 8 ++++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/building-modules/handler.md b/docs/building-modules/handler.md
index 37b46511a0..1bb9c9b48a 100644
--- a/docs/building-modules/handler.md
+++ b/docs/building-modules/handler.md
@@ -34,6 +34,7 @@ which looks like the following:
 ```go
 func NewHandler(keeper Keeper) sdk.Handler {
 	return func(ctx sdk.Context, msg sdk.Msg) (*sdk.Result, error) {
+		ctx = ctx.WithEventManager(sdk.NewEventManager())
 		switch msg := msg.(type) {
 		case MsgType1:
 			return handleMsgType1(ctx, keeper, msg)
@@ -48,7 +49,8 @@ func NewHandler(keeper Keeper) sdk.Handler {
 }
 ```
 
-This simple switch returns a `handler` function specific to the type of the received `message`. These `handler` functions are the ones that actually process `message`s, and usually follow the following 2 steps:
+First, the `handler` function sets a new `EventManager` to the context to isolate events per `msg`.
+Then, this simple switch returns a `handler` function specific to the type of the received `message`. These `handler` functions are the ones that actually process `message`s, and usually follow the following 2 steps:
 
 - First, they perform *stateful* checks to make sure the `message` is valid. At this stage, the `message`'s `ValidateBasic()` method has already been called, meaning *stateless* checks on the message (like making sure parameters are correctly formatted) have already been performed. Checks performed in the `handler` can be more expensive and require access to the state. For example, a `handler` for a `transfer` message might check that the sending account has enough funds to actually perform the transfer. To access the state, the `handler` needs to call the [`keeper`'s](./keeper.md) getter functions. 
 - Then, if the checks are successfull, the `handler` calls the [`keeper`'s](./keeper.md) setter functions to actually perform the state transition. 
diff --git a/docs/core/events.md b/docs/core/events.md
index aeb0efa1de..359e2b94a4 100644
--- a/docs/core/events.md
+++ b/docs/core/events.md
@@ -61,6 +61,14 @@ ctx.EventManager().EmitEvent(
 )
 ```
 
+Module's `handler` function should also set a new `EventManager` to the `context` to isolate emitted events per `message`:
+```go
+func NewHandler(keeper Keeper) sdk.Handler {
+    return func(ctx sdk.Context, msg sdk.Msg) (*sdk.Result, error) {
+        ctx = ctx.WithEventManager(sdk.NewEventManager())
+        switch msg := msg.(type) {
+```
+
 See the [`Handler`](../building-modules/handler.md) concept doc for a more detailed
 view on how to typically implement `Events` and use the `EventManager` in modules.