[FAB-9710] Channel Client: Documentation

Change-Id: I1ae99632166e0aa72bdf0d90f23704b6fd7b2320
Signed-off-by: Sandra Vrtikapa <sandra.vrtikapa@securekey.com>

pkg/client/channel/api.go

@@ -48,7 +48,7 @@ type Response struct {
 	Payload          []byte
 }
 
-//WithTargets encapsulates ProposalProcessors to Option
+//WithTargets allows overriding of the target peers for the request
 func WithTargets(targets ...fab.Peer) RequestOption {
 	return func(ctx context.Client, o *requestOptions) error {
 
@@ -118,7 +118,7 @@ func WithTimeout(timeoutType fab.TimeoutType, timeout time.Duration) RequestOpti
 	}
 }
 
-//WithParentContext encapsulates grpc context parent to Options
+//WithParentContext encapsulates grpc parent context
 func WithParentContext(parentContext reqContext.Context) RequestOption {
 	return func(ctx context.Client, o *requestOptions) error {
 		o.ParentContext = parentContext

pkg/client/channel/chclient.go

@@ -4,7 +4,15 @@ Copyright SecureKey Technologies Inc. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
 */
 
-// Package channel enables access to a channel on a Fabric network.
+// Package channel enables access to a channel on a Fabric network. A channel client instance provides a handler to interact with peers on specified channel.
+// Channel client can query chaincode, execute chaincode and register/unregister for chaincode events on specific channel.
+// An application that requires interaction with multiple channels should create a separate instance of the channel client for each channel.
+//
+//  Basic Flow:
+//  1) Prepare channel client context
+//  2) Create channel client
+//  3) Execute chaincode
+//  4) Query chaincode
 package channel
 
 import (
@@ -37,7 +45,7 @@ type Client struct {
 // ClientOption describes a functional parameter for the New constructor
 type ClientOption func(*Client) error
 
-// New returns a Client instance.
+// New returns a Client instance. Channel client can query chaincode, execute chaincode and register/unregister for chaincode events on specific channel.
 func New(channelProvider context.ChannelProvider, opts ...ClientOption) (*Client, error) {
 
 	channelContext, err := channelProvider()
@@ -78,7 +86,13 @@ func New(channelProvider context.ChannelProvider, opts ...ClientOption) (*Client
 	return &channelClient, nil
 }
 
-// Query chaincode using request and optional options provided
+// Query chaincode using request and optional request options
+//  Parameters:
+//  request holds info about mandatory chaincode ID and function
+//  options holds optional request options
+//
+//  Returns:
+//  the proposal responses from peer(s)
 func (cc *Client) Query(request Request, options ...RequestOption) (Response, error) {
 
 	options = append(options, addDefaultTimeout(fab.Query))
@@ -87,7 +101,13 @@ func (cc *Client) Query(request Request, options ...RequestOption) (Response, er
 	return cc.InvokeHandler(invoke.NewQueryHandler(), request, options...)
 }
 
-// Execute prepares and executes transaction using request and optional options provided
+// Execute prepares and executes transaction using request and optional request options
+//  Parameters:
+//  request holds info about mandatory chaincode ID and function
+//  options holds optional request options
+//
+//  Returns:
+//  the proposal responses from peer(s)
 func (cc *Client) Execute(request Request, options ...RequestOption) (Response, error) {
 	options = append(options, addDefaultTimeout(fab.Execute))
 	options = append(options, addDefaultTargetFilter(cc.context, filter.EndorsingPeer))
@@ -115,7 +135,14 @@ func addDefaultTimeout(tt fab.TimeoutType) RequestOption {
 	}
 }
 
-//InvokeHandler invokes handler using request and options provided
+// InvokeHandler invokes handler using request and optional request options provided
+//  Parameters:
+//  handler to be invoked
+//  request holds info about mandatory chaincode ID and function
+//  options holds optional request options
+//
+//  Returns:
+//  the proposal responses from peer(s)
 func (cc *Client) InvokeHandler(handler invoke.Handler, request Request, options ...RequestOption) (Response, error) {
 	//Read execute tx options
 	txnOpts, err := cc.prepareOptsFromOptions(cc.context, options...)
@@ -242,15 +269,21 @@ func (cc *Client) prepareOptsFromOptions(ctx context.Client, options ...RequestO
 	return txnOpts, nil
 }
 
-// RegisterChaincodeEvent registers chain code event
-// @param {chan bool} channel which receives event details when the event is complete
-// @returns {object} object handle that should be used to unregister
+// RegisterChaincodeEvent registers for chaincode events. Unregister must be called when the registration is no longer needed.
+//  Parameters:
+//  chaincodeID is the chaincode ID for which events are to be received
+//  eventFilter is the chaincode event filter (regular expression) for which events are to be received
+//
+//  Returns:
+//  the registration and a channel that is used to receive events. The channel is closed when Unregister is called.
 func (cc *Client) RegisterChaincodeEvent(chainCodeID string, eventFilter string) (fab.Registration, <-chan *fab.CCEvent, error) {
 	// Register callback for CE
 	return cc.eventService.RegisterChaincodeEvent(chainCodeID, eventFilter)
 }
 
-// UnregisterChaincodeEvent removes chain code event registration
+// UnregisterChaincodeEvent removes the given registration and closes the event channel.
+//  Parameters:
+//  registration is the registration handle that was returned from RegisterChaincodeEvent method
 func (cc *Client) UnregisterChaincodeEvent(registration fab.Registration) {
 	cc.eventService.Unregister(registration)
 }