Move grpctrace examples from comment to code (#984)

* Move grpctrace examples from comment to code

The example use of the interceptors in the grpctrace package includes
invalid syntax and semantics. Instead of doing this, move the example
use to example tests that will be rendered in the godocs.

* Add changes to Changelog

CHANGELOG.md

@@ -45,6 +45,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Use `global.Handle` for span export errors in the OTLP exporter. (#946)
 - Correct Go language formatting in the README documentation. (#961)
 - Remove default SDK dependencies from the `go.opentelemetry.io/otel/api` package. (#977)
+- Move documented examples for `go.opentelemetry.io/otel/instrumentation/grpctrace` interceptors into Go example tests. (#984)
 
 ## [0.9.0] - 2020-07-20
 

instrumentation/grpctrace/example_interceptor_test.go

@@ -0,0 +1,51 @@
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package grpctrace
+
+import (
+	"google.golang.org/grpc"
+
+	"go.opentelemetry.io/otel/api/global"
+)
+
+func ExampleStreamClientInterceptor() {
+	tracer := global.Tracer("client-instrumentation")
+	_, _ = grpc.Dial(
+		"localhost",
+		grpc.WithStreamInterceptor(StreamClientInterceptor(tracer)),
+	)
+}
+
+func ExampleUnaryClientInterceptor() {
+	tracer := global.Tracer("client-instrumentation")
+	_, _ = grpc.Dial(
+		"localhost",
+		grpc.WithUnaryInterceptor(UnaryClientInterceptor(tracer)),
+	)
+}
+
+func ExampleStreamServerInterceptor() {
+	tracer := global.Tracer("server-instrumentation")
+	_ = grpc.NewServer(
+		grpc.StreamInterceptor(StreamServerInterceptor(tracer)),
+	)
+}
+
+func ExampleUnaryServerInterceptor() {
+	tracer := global.Tracer("server-instrumentation")
+	_ = grpc.NewServer(
+		grpc.UnaryInterceptor(UnaryServerInterceptor(tracer)),
+	)
+}

instrumentation/grpctrace/interceptor.go

@@ -63,12 +63,6 @@ var (
 
 // UnaryClientInterceptor returns a grpc.UnaryClientInterceptor suitable
 // for use in a grpc.Dial call.
-//
-// For example:
-//     tracer := global.Tracer("client-tracer")
-//     s := grpc.NewServer(
-//         grpc.WithUnaryInterceptor(grpctrace.UnaryClientInterceptor(tracer)),
-//         ...,  // (existing DialOptions))
 func UnaryClientInterceptor(tracer trace.Tracer) grpc.UnaryClientInterceptor {
 	return func(
 		ctx context.Context,
@@ -242,12 +236,6 @@ func (w *clientStream) sendStreamEvent(eventType streamEventType, err error) {
 
 // StreamClientInterceptor returns a grpc.StreamClientInterceptor suitable
 // for use in a grpc.Dial call.
-//
-// For example:
-//     tracer := global.Tracer("client-tracer")
-//     s := grpc.Dial(
-//         grpc.WithStreamInterceptor(grpctrace.StreamClientInterceptor(tracer)),
-//         ...,  // (existing DialOptions))
 func StreamClientInterceptor(tracer trace.Tracer) grpc.StreamClientInterceptor {
 	return func(
 		ctx context.Context,
@@ -294,12 +282,6 @@ func StreamClientInterceptor(tracer trace.Tracer) grpc.StreamClientInterceptor {
 
 // UnaryServerInterceptor returns a grpc.UnaryServerInterceptor suitable
 // for use in a grpc.NewServer call.
-//
-// For example:
-//     tracer := global.Tracer("server-tracer")
-//     s := grpc.Dial(
-//         grpc.UnaryInterceptor(grpctrace.UnaryServerInterceptor(tracer)),
-//         ...,  // (existing ServerOptions))
 func UnaryServerInterceptor(tracer trace.Tracer) grpc.UnaryServerInterceptor {
 	return func(
 		ctx context.Context,
@@ -382,12 +364,6 @@ func wrapServerStream(ctx context.Context, ss grpc.ServerStream) *serverStream {
 
 // StreamServerInterceptor returns a grpc.StreamServerInterceptor suitable
 // for use in a grpc.NewServer call.
-//
-// For example:
-//     tracer := global.Tracer("server-tracer")
-//     s := grpc.Dial(
-//         grpc.StreamInterceptor(grpctrace.StreamServerInterceptor(tracer)),
-//         ...,  // (existing ServerOptions))
 func StreamServerInterceptor(tracer trace.Tracer) grpc.StreamServerInterceptor {
 	return func(
 		srv interface{},