[FAB-9849] Document status, multi, retry packages

Change-Id: I8c2d83022ed223b675f4a9f95992c1a6ba74481e
Signed-off-by: Divyank Katira <Divyank.Katira@securekey.com>

pkg/common/errors/multi/example_test.go

@@ -0,0 +1,34 @@
+/*
+Copyright SecureKey Technologies Inc. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
+*/
+
+package multi
+
+import (
+	"fmt"
+)
+
+func Example() {
+	errs := Errors{}
+	errs = append(errs, fmt.Errorf("peer0 failed"))
+	errs = append(errs, fmt.Errorf("peer1 failed"))
+
+	// Multi errors implement the standard error interface and are returned as regular errors
+	err := interface{}(errs).(error)
+
+	// We can extract multi errors from a standard error
+	errs, ok := err.(Errors)
+	fmt.Println(ok)
+
+	// And handle each error individually
+	for _, e := range errs {
+		fmt.Println(e)
+	}
+
+	// Output:
+	// true
+	// peer0 failed
+	// peer1 failed
+}

pkg/common/errors/multi/multi.go

@@ -4,6 +4,10 @@ Copyright SecureKey Technologies Inc. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
 */
 
+// Package multi is an error type that holds multiple errors. These errors
+// typically originate from operations that target multiple nodes.
+// For example, a transaction proposal with two endorsers could return
+// a multi error type if both endorsers return errors
 package multi
 
 import (

pkg/common/errors/retry/retry.go

@@ -4,7 +4,13 @@ Copyright SecureKey Technologies Inc. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
 */
 
-// Package retry provides retransmission capabilities to fabric-sdk-go
+// Package retry provides retransmission capabilities to fabric-sdk-go.
+// The only user interaction with this package is expected to be with the
+// defaults defined below.
+// They can be used in conjunction with the WithRetry setting offered by certain
+// clients in the SDK:
+// https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/channel#WithRetry
+// https://godoc.org/github.com/hyperledger/fabric-sdk-go/pkg/client/resmgmt#WithRetry
 package retry
 
 import (

pkg/common/errors/status/example_test.go

@@ -0,0 +1,30 @@
+/*
+Copyright SecureKey Technologies Inc. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0
+*/
+
+package status
+
+import "fmt"
+
+func Example() {
+	// Status errors are returned for certain transient errors by clients in the SDK
+	statusError := New(ClientStatus, EndorsementMismatch.ToInt32(), "proposal responses do not match", nil)
+
+	// Status errors implement the standard error interface and are returned as regular errors
+	err := interface{}(statusError).(error)
+
+	// A user can extract status information from a status
+	status, ok := FromError(err)
+	fmt.Println(ok)
+	fmt.Println(status.Group)
+	fmt.Println(Code(status.Code))
+	fmt.Println(status.Message)
+
+	// Output:
+	// true
+	// Client Status
+	// ENDORSEMENT_MISMATCH
+	// proposal responses do not match
+}

pkg/common/errors/status/status.go

@@ -7,6 +7,9 @@ SPDX-License-Identifier: Apache-2.0
 // Package status defines metadata for errors returned by fabric-sdk-go. This
 // information may be used by SDK users to make decisions about how to handle
 // certain error conditions.
+// Status codes are divided by group, where each group represents a particular
+// component and the codes correspond to those returned by the component.
+// These are defined in detail below.
 package status
 
 import (