From 5fd98530cf668f5fb2a7c036e3639aa8f28f174e Mon Sep 17 00:00:00 2001
From: eshitachandwani <59800922+eshitachandwani@users.noreply.github.com>
Date: Mon, 7 Oct 2024 22:58:35 +0530
Subject: [PATCH] examples: improve package comments (#7658)

---
 examples/features/authz/client/main.go                | 3 ++-
 examples/features/authz/server/main.go                | 3 ++-
 examples/features/cancellation/client/main.go         | 3 ++-
 examples/features/cancellation/server/main.go         | 3 ++-
 examples/features/compression/client/main.go          | 3 ++-
 examples/features/compression/server/main.go          | 7 +++++--
 examples/features/deadline/client/main.go             | 3 ++-
 examples/features/deadline/server/main.go             | 3 ++-
 examples/features/debugging/client/main.go            | 3 ++-
 examples/features/debugging/server/main.go            | 3 ++-
 examples/features/encryption/ALTS/client/main.go      | 3 ++-
 examples/features/encryption/ALTS/server/main.go      | 3 ++-
 examples/features/encryption/TLS/client/main.go       | 3 ++-
 examples/features/encryption/TLS/server/main.go       | 2 +-
 examples/features/error_details/client/main.go        | 2 +-
 examples/features/error_details/server/main.go        | 2 +-
 examples/features/error_handling/client/main.go       | 2 +-
 examples/features/error_handling/server/main.go       | 3 ++-
 examples/features/flow_control/client/main.go         | 3 ++-
 examples/features/flow_control/server/main.go         | 3 ++-
 examples/features/health/client/main.go               | 3 ++-
 examples/features/health/server/main.go               | 3 ++-
 examples/features/interceptor/client/main.go          | 3 ++-
 examples/features/interceptor/server/main.go          | 3 ++-
 examples/features/keepalive/client/main.go            | 3 ++-
 examples/features/keepalive/server/main.go            | 3 ++-
 examples/features/load_balancing/client/main.go       | 3 ++-
 examples/features/load_balancing/server/main.go       | 3 ++-
 examples/features/metadata/client/main.go             | 2 +-
 examples/features/metadata/server/main.go             | 2 +-
 examples/features/metadata_interceptor/client/main.go | 3 ++-
 examples/features/metadata_interceptor/server/main.go | 2 +-
 examples/features/multiplex/client/main.go            | 3 ++-
 examples/features/multiplex/server/main.go            | 3 ++-
 examples/features/name_resolving/client/main.go       | 3 ++-
 examples/features/name_resolving/server/main.go       | 3 ++-
 examples/features/observability/client/main.go        | 3 ++-
 examples/features/observability/server/main.go        | 3 ++-
 examples/features/orca/client/main.go                 | 3 ++-
 examples/features/orca/server/main.go                 | 3 ++-
 examples/features/reflection/server/main.go           | 3 ++-
 examples/features/retry/client/main.go                | 3 ++-
 examples/features/retry/server/main.go                | 2 +-
 43 files changed, 81 insertions(+), 44 deletions(-)

diff --git a/examples/features/authz/client/main.go b/examples/features/authz/client/main.go
index b4f5fca59..db05ab29f 100644
--- 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
index 55cf26a7e..9e699ca5f 100644
--- 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
index 8473416cc..9ac765be8 100644
--- 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
index 520286bf1..53a3a6130 100644
--- 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
index 0ca447f07..482acfedb 100644
--- 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
index 2dd50a72a..a741aaab3 100644
--- 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
index 8c13eb853..4d16a02d9 100644
--- 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
index a6e7a9b49..a826b3998 100644
--- 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
index 37b120f43..f502ba434 100644
--- 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
index 81939d9cd..5dd31af9c 100644
--- 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
index b0778ec6b..5ac1f9857 100644
--- 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
index 98337f3f3..174e188a4 100644
--- 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
index 27e978065..ff53c7a1e 100644
--- 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
index 2003134da..82162a99b 100644
--- 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
index 7e54135a6..d7fc9cc05 100644
--- 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
index 0ff936ea6..798513b04 100644
--- 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
index 3a15bf146..7eadaad38 100644
--- 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
index 80229e1e2..44c880912 100644
--- 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
index b1296f529..eeba8a243 100644
--- 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
index 5452c3e62..af03f0d50 100644
--- 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
index cf47409c4..dc5382a40 100644
--- 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
index 5cc10bad5..ea94c36a6 100644
--- 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
index 22150c404..feb59bf1a 100644
--- 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
index f5e1333af..40919ec17 100644
--- 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
index b93fcf608..6de00174d 100644
--- 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
index 8236c2efd..f7ab42ef5 100644
--- 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
index 22504d0cc..c970b904e 100644
--- 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
index 9cfa8471f..c88f80cad 100644
--- 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
index a314f3063..861e3eece 100644
--- 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
index d8ef473ae..698924296 100644
--- 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
index 3c950ed7c..cc8754de3 100644
--- 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
index 93125433b..e1525d94e 100644
--- 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
index 3e60c0506..d5a432e16 100644
--- 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
index 475b074f2..edd6ede6c 100644
--- 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
index 72ffd6281..6d5003266 100644
--- 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
index fdf61bb82..6a7297a1e 100644
--- 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
index 22f069eba..ad08c8a30 100644
--- 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
index 184fba881..b8455ef82 100644
--- 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
index 1046bbbe1..60a91f4c0 100644
--- 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 (
diff --git a/examples/features/orca/server/main.go b/examples/features/orca/server/main.go
index e52d5d06e..65c767aaa 100644
--- a/examples/features/orca/server/main.go
+++ b/examples/features/orca/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to use ORCA for reporting out-of-band
+// and per-RPC load metrics.
 package main
 
 import (
diff --git a/examples/features/reflection/server/main.go b/examples/features/reflection/server/main.go
index d7fc36208..a97045545 100644
--- a/examples/features/reflection/server/main.go
+++ b/examples/features/reflection/server/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates how to register multiple services and enable
+// client discovery.
 package main
 
 import (
diff --git a/examples/features/retry/client/main.go b/examples/features/retry/client/main.go
index 00acc5f7b..751a74a9c 100644
--- a/examples/features/retry/client/main.go
+++ b/examples/features/retry/client/main.go
@@ -16,7 +16,8 @@
  *
  */
 
-// Binary client is an example client.
+// Binary client demonstrates how to enable and configure retry policies for
+// gRPC requests.
 package main
 
 import (
diff --git a/examples/features/retry/server/main.go b/examples/features/retry/server/main.go
index 0fdf4ef91..657c682ce 100644
--- a/examples/features/retry/server/main.go
+++ b/examples/features/retry/server/main.go
@@ -16,7 +16,7 @@
  *
  */
 
-// Binary server is an example server.
+// Binary server demonstrates to enforce retries on client side.
 package main
 
 import (