From 42c2a86ea483f3952c92f490d6184c1dfb7d4ca6 Mon Sep 17 00:00:00 2001
From: Tyler Yahn <MrAlias@users.noreply.github.com>
Date: Tue, 28 Jul 2020 15:59:35 -0700
Subject: [PATCH] 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                                  |  1 +
 .../grpctrace/example_interceptor_test.go     | 51 +++++++++++++++++++
 instrumentation/grpctrace/interceptor.go      | 24 ---------
 3 files changed, 52 insertions(+), 24 deletions(-)
 create mode 100644 instrumentation/grpctrace/example_interceptor_test.go

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4497da51da2..b4228b1974d 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/instrumentation/grpctrace/example_interceptor_test.go b/instrumentation/grpctrace/example_interceptor_test.go
new file mode 100644
index 00000000000..7310483df0e
--- /dev/null
+++ b/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)),
+	)
+}
diff --git a/instrumentation/grpctrace/interceptor.go b/instrumentation/grpctrace/interceptor.go
index 7a8d195e21d..1c5092c01d2 100644
--- a/instrumentation/grpctrace/interceptor.go
+++ b/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{},