From 3242b0020bf6d6837dcd5425d3291c8b43f96f44 Mon Sep 17 00:00:00 2001
From: Dean Eigenmann <7621705+decanus@users.noreply.github.com>
Date: Mon, 4 Jan 2021 12:57:26 +0100
Subject: [PATCH] fix/message-notification-descriptive (#327)

* moved

* added docs

* Update message_notifier.nim

* Update waku_types.nim
---
 waku/v2/protocol/message_notifier.nim | 23 +++++++++++++++++++----
 waku/v2/waku_types.nim                |  4 +++-
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/waku/v2/protocol/message_notifier.nim b/waku/v2/protocol/message_notifier.nim
index e9168c00a..9f48a6581 100644
--- a/waku/v2/protocol/message_notifier.nim
+++ b/waku/v2/protocol/message_notifier.nim
@@ -3,11 +3,26 @@ import
   chronos,
   ../waku_types
 
-# The Message Notification system is a method to notify various protocols
-# running on a node when a new message was received.
+## The Message Notification system is a method to notify various protocols
+## running on a node when a new message was received.
 #
-# Protocols can subscribe to messages of specific topics, then when one is received
-# The notification handler function will be called.
+## Protocols can subscribe to messages of specific topics, then when one is received
+## The notification handler function will be called.
+## 
+## This works as follows:
+## 
+## .. code-block::
+##   var topic = "foo"
+##   
+##   proc handle(topic: string, msg: WakuMessage) {.async.} =
+##    info "new message", msg = msg
+##
+##   MessageNotificationSubscription.init(@[topic], handle)
+## 
+##   var subscriptions = newTable[string, MessageNotificationSubscription]()
+##   subscriptions["identifier"] = subscription
+## 
+##   await subscriptions.notify(topic, WakuMessage(payload: @[byte 1, 2, 3], contentTopic: ContentTopic(1)))
 proc subscribe*(subscriptions: MessageNotificationSubscriptions, name: string, subscription: MessageNotificationSubscription) =
   subscriptions.add(name, subscription)
 
diff --git a/waku/v2/waku_types.nim b/waku/v2/waku_types.nim
index 468149016..d8d6be1a2 100644
--- a/waku/v2/waku_types.nim
+++ b/waku/v2/waku_types.nim
@@ -38,11 +38,13 @@ type
   MessageNotificationHandler* = proc(topic: string, msg: WakuMessage): Future[
       void] {.gcsafe, closure.}
 
-  MessageNotificationSubscriptions* = TableRef[string, MessageNotificationSubscription]
+  MessageNotificationSubscriptionIdentifier* = string
 
   MessageNotificationSubscription* = object
     topics*: seq[string] # @TODO TOPIC
     handler*: MessageNotificationHandler
+ 
+  MessageNotificationSubscriptions* = TableRef[MessageNotificationSubscriptionIdentifier, MessageNotificationSubscription]
 
   FilterRequest* = object
     contentFilters*: seq[ContentFilter]