fix(internal/gengapic): add iter response access example (googleapis#1468)

* fix(internal/gengapic): add iter response access example

* update example language

Author: noahdietz

internal/gengapic/example.go

@@ -147,7 +147,9 @@ func (g *generator) exampleMethodBody(pkgName, servName string, m *descriptor.Me
 		return err
 	}
 	if pf != nil {
-		g.examplePagingCall(m)
+		if err := g.examplePagingCall(m); err != nil {
+			return err
+		}
 	} else if g.isLRO(m) || g.isCustomOp(m, httpInfo) {
 		g.exampleLROCall(m)
 	} else if *m.OutputType == emptyType {
@@ -211,10 +213,20 @@ func (g *generator) exampleEmptyCall(m *descriptor.MethodDescriptorProto) {
 	p("}")
 }
 
-func (g *generator) examplePagingCall(m *descriptor.MethodDescriptorProto) {
+func (g *generator) examplePagingCall(m *descriptor.MethodDescriptorProto) error {
+	outType := g.descInfo.Type[m.GetOutputType()]
+	if outType == nil {
+		return fmt.Errorf("cannot find type %q, malformed descriptor?", m.GetOutputType())
+	}
+
+	outSpec, err := g.descInfo.ImportSpec(outType)
+	if err != nil {
+		return err
+	}
+
 	p := g.printf
 
-	p("it := c.%s(ctx, req)", *m.Name)
+	p("it := c.%s(ctx, req)", m.GetName())
 	p("for {")
 	p("  resp, err := it.Next()")
 	p("  if err == iterator.Done {")
@@ -225,9 +237,17 @@ func (g *generator) examplePagingCall(m *descriptor.MethodDescriptorProto) {
 	p("  }")
 	p("  // TODO: Use resp.")
 	p("  _ = resp")
+	p("")
+	p("  // If you need to access the underlying RPC response,")
+	p("  // you can do so by casting the `Response` as below.")
+	p("  // Otherwise, remove this line. Only populated after")
+	p("  // first call to Next(). Not safe for concurrent access.")
+	p("  _ = it.Response.(*%s.%s)", outSpec.Name, outType.GetName())
 	p("}")
 
 	g.imports[pbinfo.ImportSpec{Path: "google.golang.org/api/iterator"}] = true
+	g.imports[outSpec] = true
+	return nil
 }
 
 func (g *generator) exampleBidiCall(m *descriptor.MethodDescriptorProto, inType pbinfo.ProtoType, inSpec pbinfo.ImportSpec) {

internal/gengapic/testdata/custom_op_example.want

@@ -121,6 +121,12 @@ func ExampleFooClient_GetManyThings() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*mypackagepb.PageOutputType)
 	}
 }
 

internal/gengapic/testdata/empty_example.want

@@ -138,6 +138,12 @@ func ExampleClient_GetManyThings() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*mypackagepb.PageOutputType)
 	}
 }
 
@@ -292,6 +298,12 @@ func ExampleClient_ListLocations() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*locationpb.ListLocationsResponse)
 	}
 }
 
@@ -423,6 +435,12 @@ func ExampleClient_ListOperations() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*longrunningpb.ListOperationsResponse)
 	}
 }
 

internal/gengapic/testdata/empty_example_grpc.want

@@ -121,6 +121,12 @@ func ExampleClient_GetManyThings() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*mypackagepb.PageOutputType)
 	}
 }
 
@@ -275,6 +281,12 @@ func ExampleClient_ListLocations() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*locationpb.ListLocationsResponse)
 	}
 }
 
@@ -406,6 +418,12 @@ func ExampleClient_ListOperations() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*longrunningpb.ListOperationsResponse)
 	}
 }
 

internal/gengapic/testdata/foo_example.want

@@ -138,6 +138,12 @@ func ExampleFooClient_GetManyThings() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*mypackagepb.PageOutputType)
 	}
 }
 
@@ -292,6 +298,12 @@ func ExampleFooClient_ListLocations() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*locationpb.ListLocationsResponse)
 	}
 }
 
@@ -423,6 +435,12 @@ func ExampleFooClient_ListOperations() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*longrunningpb.ListOperationsResponse)
 	}
 }
 

internal/gengapic/testdata/foo_example_rest.want

@@ -121,6 +121,12 @@ func ExampleFooClient_GetManyThings() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*mypackagepb.PageOutputType)
 	}
 }
 
@@ -275,6 +281,12 @@ func ExampleFooClient_ListLocations() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*locationpb.ListLocationsResponse)
 	}
 }
 
@@ -406,6 +418,12 @@ func ExampleFooClient_ListOperations() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*longrunningpb.ListOperationsResponse)
 	}
 }
 

internal/gengapic/testdata/snippet_GetManyThings.want

@@ -26,6 +26,12 @@ func main() {
 		}
 		// TODO: Use resp.
 		_ = resp
+
+		// If you need to access the underlying RPC response,
+		// you can do so by casting the `Response` as below.
+		// Otherwise, remove this line. Only populated after
+		// first call to Next(). Not safe for concurrent access.
+		_ = it.Response.(*mypackagepb.PageOutputType)
 	}
 }