Merge pull request #5233 from gyuho/client-doc

clientv3: fix README, add error handling example

clientv3/README.md

@@ -52,21 +52,22 @@ For more detail, please read [Go vendor design](https://golang.org/s/go15vendor)
 etcd client returns 2 types of errors:
 
 1. context error: canceled or deadline exceeded.
-2. gRPC error: see [v3rpc/error](https://github.com/coreos/etcd/blob/master/etcdserver/api/v3rpc/error.go).
+2. gRPC error: see [api/v3rpc/rpctypes](https://godoc.org/github.com/coreos/etcd/etcdserver/api/v3rpc/rpctypes).
 
 Here is the example code to handle client errors:
 
 ```go
 resp, err := kvc.Put(ctx, "", "")
 if err != nil {
-	if err == context.Canceled {
-		// ctx is canceled by another routine
-	} else if err == context.DeadlineExceeded {
-		// ctx is attached with a deadline and it exceeded
-	} else if verr, ok := err.(*v3rpc.ErrEmptyKey); ok {
-		// process (verr.Errors)
-	} else {
-		// bad cluster endpoints, which are not etcd servers
+	switch err {
+	case context.Canceled:
+		log.Fatalf("ctx is canceled by another routine: %v", err)
+	case context.DeadlineExceeded:
+		log.Fatalf("ctx is attached with a deadline is exceeded: %v", err)
+	case rpctypes.ErrEmptyKey:
+		log.Fatalf("client-side error: %v", err)
+	default:
+		log.Fatalf("bad cluster endpoints, which are not etcd servers: %v", err)
 	}
 }
 ```

clientv3/example_kv_test.go

@@ -19,6 +19,7 @@ import (
 	"log"
 
 	"github.com/coreos/etcd/clientv3"
+	"github.com/coreos/etcd/etcdserver/api/v3rpc/rpctypes"
 	"golang.org/x/net/context"
 )
 
@@ -40,6 +41,34 @@ func ExampleKV_put() {
 	}
 }
 
+func ExampleKV_putErrorHandling() {
+	cli, err := clientv3.New(clientv3.Config{
+		Endpoints:   endpoints,
+		DialTimeout: dialTimeout,
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer cli.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), requestTimeout)
+	_, err = cli.Put(ctx, "", "sample_value")
+	cancel()
+	if err != nil {
+		switch err {
+		case context.Canceled:
+			fmt.Printf("ctx is canceled by another routine: %v\n", err)
+		case context.DeadlineExceeded:
+			fmt.Printf("ctx is attached with a deadline is exceeded: %v\n", err)
+		case rpctypes.ErrEmptyKey:
+			fmt.Printf("client-side error: %v\n", err)
+		default:
+			fmt.Printf("bad cluster endpoints, which are not etcd servers: %v\n", err)
+		}
+	}
+	// Output: client-side error: etcdserver: key is not provided
+}
+
 func ExampleKV_get() {
 	cli, err := clientv3.New(clientv3.Config{
 		Endpoints:   endpoints,