From b40aa91b4101622455ef22cf1eaf31d0ef835cb6 Mon Sep 17 00:00:00 2001
From: Anton Kaliaev <anton.kalyaev@gmail.com>
Date: Fri, 12 Jan 2018 12:47:54 -0600
Subject: [PATCH] document event subscriptions

Refs #1100
---
 rpc/core/events.go | 75 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 69 insertions(+), 6 deletions(-)

diff --git a/rpc/core/events.go b/rpc/core/events.go
index 538134b0f..9353ace6a 100644
--- a/rpc/core/events.go
+++ b/rpc/core/events.go
@@ -13,11 +13,57 @@ import (
 
 // Subscribe for events via WebSocket.
 //
+// To tell which events you want, you need to provide a query. query is a
+// string, which has a form: "condition AND condition ..." (no OR at the
+// moment). condition has a form: "key operation operand". key is a string with
+// a restricted set of possible symbols ( \t\n\r\\()"'=>< are not allowed).
+// operation can be "=", "<", "<=", ">", ">=", "CONTAINS". operand can be a
+// string (escaped with single quotes), number, date or time.
+//
+// Examples:
+//		tm.event = 'NewBlock'								# new blocks
+//		tm.event = 'CompleteProposal'				# node got a complete proposal
+//		tm.event = 'Tx' AND tx.hash = 'XYZ' # single transaction
+//		tm.event = 'Tx' AND tx.height = 5		# all txs of the fifth block
+//		tx.height = 5												# all txs of the fifth block
+//
+// Tendermint provides a few predefined keys: tm.event, tx.hash and tx.height.
+// Note for transactions, you can define additional keys by providing tags with
+// DeliverTx response.
+//
+//		DeliverTx{
+//			Tags: []*KVPair{
+//				"agent.name": "K",
+//			}
+//	  }
+//
+//		tm.event = 'Tx' AND agent.name = 'K'
+//		tm.event = 'Tx' AND account.created_at >= TIME 2013-05-03T14:45:00Z
+//		tm.event = 'Tx' AND contract.sign_date = DATE 2017-01-01
+//		tm.event = 'Tx' AND account.owner CONTAINS 'Igor'
+//
+// See list of all possible events here
+// https://godoc.org/github.com/tendermint/tendermint/types#pkg-constants
+//
+// For complete query syntax, check out
+// https://godoc.org/github.com/tendermint/tmlibs/pubsub/query.
+//
 // ```go
+// import "github.com/tendermint/tmlibs/pubsub/query"
 // import "github.com/tendermint/tendermint/types"
 //
 // client := client.NewHTTP("tcp://0.0.0.0:46657", "/websocket")
-// result, err := client.AddListenerForEvent(types.EventStringNewBlock())
+// ctx, cancel := context.WithTimeout(context.Background(), timeout)
+// defer cancel()
+// query := query.MustParse("tm.event = 'Tx' AND tx.height = 3")
+// txs := make(chan interface{})
+// err := client.Subscribe(ctx, "test-client", query, txs)
+//
+// go func() {
+//   for e := range txs {
+//     fmt.Println("got ", e.(types.TMEventData).Unwrap().(types.EventDataTx))
+//	 }
+// }()
 // ```
 //
 // > The above command returns JSON structured like this:
@@ -35,7 +81,7 @@ import (
 //
 // | Parameter | Type   | Default | Required | Description |
 // |-----------+--------+---------+----------+-------------|
-// | event     | string | ""      | true     | Event name  |
+// | query     | string | ""      | true     | Query       |
 //
 // <aside class="notice">WebSocket only</aside>
 func Subscribe(wsCtx rpctypes.WSRPCContext, query string) (*ctypes.ResultSubscribe, error) {
@@ -68,10 +114,8 @@ func Subscribe(wsCtx rpctypes.WSRPCContext, query string) (*ctypes.ResultSubscri
 // Unsubscribe from events via WebSocket.
 //
 // ```go
-// import 'github.com/tendermint/tendermint/types'
-//
 // client := client.NewHTTP("tcp://0.0.0.0:46657", "/websocket")
-// result, err := client.RemoveListenerForEvent(types.EventStringNewBlock())
+// err := client.Unsubscribe("test-client", query)
 // ```
 //
 // > The above command returns JSON structured like this:
@@ -89,7 +133,7 @@ func Subscribe(wsCtx rpctypes.WSRPCContext, query string) (*ctypes.ResultSubscri
 //
 // | Parameter | Type   | Default | Required | Description |
 // |-----------+--------+---------+----------+-------------|
-// | event     | string | ""      | true     | Event name  |
+// | query     | string | ""      | true     | Query       |
 //
 // <aside class="notice">WebSocket only</aside>
 func Unsubscribe(wsCtx rpctypes.WSRPCContext, query string) (*ctypes.ResultUnsubscribe, error) {
@@ -106,6 +150,25 @@ func Unsubscribe(wsCtx rpctypes.WSRPCContext, query string) (*ctypes.ResultUnsub
 	return &ctypes.ResultUnsubscribe{}, nil
 }
 
+// Unsubscribe from all events via WebSocket.
+//
+// ```go
+// client := client.NewHTTP("tcp://0.0.0.0:46657", "/websocket")
+// err := client.UnsubscribeAll("test-client")
+// ```
+//
+// > The above command returns JSON structured like this:
+//
+// ```json
+// {
+// 	"error": "",
+// 	"result": {},
+// 	"id": "",
+// 	"jsonrpc": "2.0"
+// }
+// ```
+//
+// <aside class="notice">WebSocket only</aside>
 func UnsubscribeAll(wsCtx rpctypes.WSRPCContext) (*ctypes.ResultUnsubscribe, error) {
 	addr := wsCtx.GetRemoteAddr()
 	logger.Info("Unsubscribe from all", "remote", addr)