examples: improve package comments (grpc#7658)

janardhanvissa · Oct 7, 2024 · 5fd9853 · 5fd9853
1 parent 859602c
commit 5fd9853
Show file tree

Hide file tree

Showing 43 changed files with 81 additions and 44 deletions.
diff --git a/examples/features/authz/client/main.go b/examples/features/authz/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to include authorization credentials in the
+// form of metadata in every RPC for server side validation.
 package main
 
 import (

diff --git a/examples/features/authz/server/main.go b/examples/features/authz/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to validate authorization credential metadata
+// for incoming RPCs.
 package main
 
 import (

diff --git a/examples/features/cancellation/client/main.go b/examples/features/cancellation/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to cancel in-flight RPCs by canceling the
+// context passed to the RPC.
 package main
 
 import (

diff --git a/examples/features/cancellation/server/main.go b/examples/features/cancellation/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to handle canceled contexts when a client
+// cancels an in-flight RPC.
 package main
 
 import (

diff --git a/examples/features/compression/client/main.go b/examples/features/compression/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to specify compression options when performing
+// RPCs.
 package main
 
 import (

diff --git a/examples/features/compression/server/main.go b/examples/features/compression/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to install and support compressors for
+// incoming RPCs.
 package main
 
 import (
@@ -27,7 +28,9 @@ import (
 	"net"
 
 	"google.golang.org/grpc"
-	_ "google.golang.org/grpc/encoding/gzip" // Install the gzip compressor
+	// Installing the gzip encoding registers it as an available compressor.
+	// gRPC will automatically negotiate and use gzip if the client supports it.
+	_ "google.golang.org/grpc/encoding/gzip"
 
 	pb "google.golang.org/grpc/examples/features/proto/echo"
 )

diff --git a/examples/features/deadline/client/main.go b/examples/features/deadline/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to set deadlines for RPCs and how to handle
+// deadline-exceeded errors.
 package main
 
 import (

diff --git a/examples/features/deadline/server/main.go b/examples/features/deadline/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to handle RPCs with deadlines and how to
+// propagate deadlines in requests.
 package main
 
 import (

diff --git a/examples/features/debugging/client/main.go b/examples/features/debugging/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to use logging and Channelz for debugging
+// gRPC operations.
 package main
 
 import (

diff --git a/examples/features/debugging/server/main.go b/examples/features/debugging/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to enable logging and Channelz for debugging
+// gRPC services.
 package main
 
 import (

diff --git a/examples/features/encryption/ALTS/client/main.go b/examples/features/encryption/ALTS/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to use ALTS credentials for secure
+// gRPC communication.
 package main
 
 import (

diff --git a/examples/features/encryption/ALTS/server/main.go b/examples/features/encryption/ALTS/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to use ALTS credentials to secure gRPC
+// services.
 package main
 
 import (

diff --git a/examples/features/encryption/TLS/client/main.go b/examples/features/encryption/TLS/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to use TLS credentials for secure
+// gRPC communication.
 package main
 
 import (

diff --git a/examples/features/encryption/TLS/server/main.go b/examples/features/encryption/TLS/server/main.go
@@ -16,7 +16,7 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to use TLS credentials to secure gRPC services.
 package main
 
 import (

diff --git a/examples/features/error_details/client/main.go b/examples/features/error_details/client/main.go
@@ -16,7 +16,7 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to handle error messages from a gRPC server.
 package main
 
 import (

diff --git a/examples/features/error_details/server/main.go b/examples/features/error_details/server/main.go
@@ -16,7 +16,7 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to provide error messages in gRPC responses.
 package main
 
 import (

diff --git a/examples/features/error_handling/client/main.go b/examples/features/error_handling/client/main.go
@@ -16,7 +16,7 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to handle errors returned by a gRPC server.
 package main
 
 import (

diff --git a/examples/features/error_handling/server/main.go b/examples/features/error_handling/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to return specific error codes in gRPC
+// responses.
 package main
 
 import (

diff --git a/examples/features/flow_control/client/main.go b/examples/features/flow_control/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how the gRPC flow control blocks sending when the
+// receiver is not ready.
 package main
 
 import (

diff --git a/examples/features/flow_control/server/main.go b/examples/features/flow_control/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how gRPC flow control block sending when the
+// receiver is not ready.
 package main
 
 import (

diff --git a/examples/features/health/client/main.go b/examples/features/health/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to check and observe gRPC server health using
+// the health library.
 package main
 
 import (

diff --git a/examples/features/health/server/main.go b/examples/features/health/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to manage and report its health status using
+// the gRPC health library.
 package main
 
 import (

diff --git a/examples/features/interceptor/client/main.go b/examples/features/interceptor/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to use interceptors to observe or control the
+// behavior of gRPC including logging, authentication,metrics collection, etc.
 package main
 
 import (

diff --git a/examples/features/interceptor/server/main.go b/examples/features/interceptor/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to use interceptors to observe or control the
+// behavior of gRPC including logging, authentication,metrics collection, etc.
 package main
 
 import (

diff --git a/examples/features/keepalive/client/main.go b/examples/features/keepalive/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to configure keepalive pings to maintain
+// connectivity and detect stale connections.
 package main
 
 import (

diff --git a/examples/features/keepalive/server/main.go b/examples/features/keepalive/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to enforce keepalive settings and manage idle
+// connections to maintain active client connections.
 package main
 
 import (

diff --git a/examples/features/load_balancing/client/main.go b/examples/features/load_balancing/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to configure load balancing policies to
+// distribute RPCs across backend servers.
 package main
 
 import (

diff --git a/examples/features/load_balancing/server/main.go b/examples/features/load_balancing/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to spin up multiple server backends
+// to enable client-side load balancing.
 package main
 
 import (

diff --git a/examples/features/metadata/client/main.go b/examples/features/metadata/client/main.go
@@ -16,7 +16,7 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to send and receive metadata to and from an RPC.
 package main
 
 import (

diff --git a/examples/features/metadata/server/main.go b/examples/features/metadata/server/main.go
@@ -16,7 +16,7 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to send and read metadata to and from RPC.
 package main
 
 import (

diff --git a/examples/features/metadata_interceptor/client/main.go b/examples/features/metadata_interceptor/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to receive metadata in RPC headers
+// and trailers.
 package main
 
 import (

diff --git a/examples/features/metadata_interceptor/server/main.go b/examples/features/metadata_interceptor/server/main.go
@@ -16,7 +16,7 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to update metadata from interceptors on server.
 package main
 
 import (

diff --git a/examples/features/multiplex/client/main.go b/examples/features/multiplex/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to use a single grpc.ClientConn for multiple
+// service stubs.
 package main
 
 import (

diff --git a/examples/features/multiplex/server/main.go b/examples/features/multiplex/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to use a single grpc.Server instance to
+// register and serve multiple services.
 package main
 
 import (

diff --git a/examples/features/name_resolving/client/main.go b/examples/features/name_resolving/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to use custom name resolvers to resolve
+// server backend addresses.
 package main
 
 import (

diff --git a/examples/features/name_resolving/server/main.go b/examples/features/name_resolving/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to set up a gRPC server that listens on a
+// specified port for name resolution examples.
 package main
 
 import (

diff --git a/examples/features/observability/client/main.go b/examples/features/observability/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Package main implements a client for Greeter service.
+// Binary client demonstrates how to instrument RPCs with logging, metrics,
+// and tracing.
 package main
 
 import (

diff --git a/examples/features/observability/server/main.go b/examples/features/observability/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Package main implements a server for Greeter service.
+// Binary server demonstrates how to instrument RPCs for logging, metrics,
+// and tracing.
 package main
 
 import (

diff --git a/examples/features/orca/client/main.go b/examples/features/orca/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates the use of a custom LB policy that handles ORCA
+// per-call and out-of-band metrics for load reporting.
 package main
 
 import (