docs: improve godoc comments & client README.md

docs/pkg/client/README.md

@@ -31,7 +31,7 @@ It includes lower-level interfaces for working with transactions and subscribing
 | **`TxClient`**          | A high-level client used to build, sign, and broadcast transaction from cosmos-sdk messages.       |
 | **`TxContext`**         | Abstracts and encapsulates the transaction building, signing, encoding, and broadcasting concerns. |
 | **`BlockClient`**       | Exposes methods for receiving notifications about newly committed blocks.                          |
-| **`EventsQueryClient`** | Encapsulates blockchain event subscriptions in .                                                   |
+| **`EventsQueryClient`** | Encapsulates blockchain event subscriptions.                                                       |
 | **`Connection`**        | A transport agnostic communication channel for sending and receiving messages.                     |
 | **`Dialer`**            | Abstracts the establishment of connections.                                                        |
 
@@ -77,7 +77,7 @@ tx --"#EventsBytes()"--> evt
 bl --"#EventsBytes()"--> evt
 evt --> conn
 evt --"#DialContext()"--> dial
-dial --(returns)--> conn
+dial --"(returns)"--> conn
 ```
 
 > **Figure 2**: An overview which articulates the dependency relationships between the various client interfaces and their subcompnents.

internal/testclient/testeventsquery/client.go

@@ -27,12 +27,11 @@ func NewLocalnetClient(t *testing.T, opts ...client.EventsQueryClientOption) cli
 }
 
 // NewOneTimeEventsQuery creates a mock of the EventsQueryClient which expects
-// a single call to the EventsBytes method. It returns a mock client whose event
-// bytes method always constructs a new observable. query is the query string
-// for which event bytes subscription is expected to be for.
-// The caller can simulate blockchain events by sending on publishCh, the value
-// of which is set to the publish channel of the events bytes observable publish
-// channel.
+// a single call to the EventsBytes method. query is the query string which is
+// expected to be received by that call.
+// It returns a mock client whose event bytes method constructs a new observable.
+// The caller can simulate blockchain events by sending on the value publishCh
+// points to, which is set by this helper function.
 func NewOneTimeEventsQuery(
 	ctx context.Context,
 	t *testing.T,
@@ -57,9 +56,8 @@ func NewOneTimeEventsQuery(
 // NewOneTimeTxEventsQueryClient creates a mock of the Events that expects
 // a single call to the EventsBytes method where the query is for transaction
 // events for sender address matching that of the given key.
-// The caller can simulate blockchain events by sending on publishCh, the value
-// of which is set to the publish channel of the events bytes observable publish
-// channel.
+// The caller can simulate blockchain events by sending on the value publishCh
+// points to, which is set by this helper function.
 func NewOneTimeTxEventsQueryClient(
 	ctx context.Context,
 	t *testing.T,

pkg/client/interface.go

@@ -70,6 +70,7 @@ type TxContext interface {
 
 // BlocksObservable is an observable which is notified with an either
 // value which contains either an error or the event message bytes.
+//
 // TODO_HACK: The purpose of this type is to work around gomock's lack of
 // support for generic types. For the same reason, this type cannot be an
 // alias (i.e. EventsBytesObservable = observable.Observable[either.Either[[]byte]]).
@@ -94,23 +95,24 @@ type Block interface {
 	Hash() []byte
 }
 
-// TODO_CONSIDERATION: the cosmos-sdk CLI code seems to use a cometbft RPC client
-// which includes a `#Subscribe()` method for a similar purpose. Perhaps we could
-// replace this custom websocket client with that.
-// (see: https://github.com/cometbft/cometbft/blob/main/rpc/client/http/http.go#L110)
-// (see: https://github.com/cosmos/cosmos-sdk/blob/main/client/rpc/tx.go#L114)
-//
-// NOTE: a branch which attempts this is available at:
-// https://github.com/pokt-network/poktroll/pull/74
-
 // EventsBytesObservable is an observable which is notified with an either
 // value which contains either an error or the event message bytes.
+//
 // TODO_HACK: The purpose of this type is to work around gomock's lack of
 // support for generic types. For the same reason, this type cannot be an
 // alias (i.e. EventsBytesObservable = observable.Observable[either.Bytes]).
 type EventsBytesObservable observable.Observable[either.Bytes]
 
 // EventsQueryClient is used to subscribe to chain event messages matching the given query,
+//
+// TODO_CONSIDERATION: the cosmos-sdk CLI code seems to use a cometbft RPC client
+// which includes a `#Subscribe()` method for a similar purpose. Perhaps we could
+// replace our custom implementation with one which wraps that.
+// (see: https://github.com/cometbft/cometbft/blob/main/rpc/client/http/http.go#L110)
+// (see: https://github.com/cosmos/cosmos-sdk/blob/main/client/rpc/tx.go#L114)
+//
+// NOTE: a branch which attempts this is available at:
+// https://github.com/pokt-network/poktroll/pull/74
 type EventsQueryClient interface {
 	// EventsBytes returns an observable which is notified about chain event messages
 	// matching the given query. It receives an either value which contains either an