docs(pubsublite): extra examples and documentation clean up

pubsublite/README.md

@@ -27,7 +27,7 @@ To publish messages to a topic:
 const topic = "projects/project-id/locations/us-central1-b/topics/topic1"
 publisher, err := pscompat.NewPublisherClient(ctx, topic)
 if err != nil {
-    log.Fatal(err)
+	log.Fatal(err)
 }
 
 // Publish "hello world".

pubsublite/example_test.go

@@ -22,8 +22,14 @@ import (
 	"google.golang.org/api/iterator"
 )
 
+// This example demonstrates how to create a new topic.
+// See https://cloud.google.com/pubsub/lite/docs/topics for more information
+// about how Pub/Sub Lite topics are configured.
+// See https://cloud.google.com/pubsub/lite/docs/locations for the list of zones
+// where Pub/Sub Lite is available.
 func ExampleAdminClient_CreateTopic() {
 	ctx := context.Background()
+	// NOTE: region must correspond to the zone of the topic.
 	admin, err := pubsublite.NewAdminClient(ctx, "region")
 	if err != nil {
 		// TODO: Handle error.
@@ -47,6 +53,7 @@ func ExampleAdminClient_CreateTopic() {
 
 func ExampleAdminClient_UpdateTopic() {
 	ctx := context.Background()
+	// NOTE: region must correspond to the zone of the topic.
 	admin, err := pubsublite.NewAdminClient(ctx, "region")
 	if err != nil {
 		// TODO: Handle error.
@@ -67,6 +74,7 @@ func ExampleAdminClient_UpdateTopic() {
 
 func ExampleAdminClient_DeleteTopic() {
 	ctx := context.Background()
+	// NOTE: region must correspond to the zone of the topic.
 	admin, err := pubsublite.NewAdminClient(ctx, "region")
 	if err != nil {
 		// TODO: Handle error.
@@ -80,6 +88,7 @@ func ExampleAdminClient_DeleteTopic() {
 
 func ExampleAdminClient_Topics() {
 	ctx := context.Background()
+	// NOTE: region must correspond to the zone below.
 	admin, err := pubsublite.NewAdminClient(ctx, "region")
 	if err != nil {
 		// TODO: Handle error.
@@ -101,6 +110,7 @@ func ExampleAdminClient_Topics() {
 
 func ExampleAdminClient_TopicSubscriptions() {
 	ctx := context.Background()
+	// NOTE: region must correspond to the zone of the topic.
 	admin, err := pubsublite.NewAdminClient(ctx, "region")
 	if err != nil {
 		// TODO: Handle error.
@@ -121,8 +131,12 @@ func ExampleAdminClient_TopicSubscriptions() {
 	}
 }
 
+// This example demonstrates how to create a new subscription for a topic.
+// See https://cloud.google.com/pubsub/lite/docs/subscriptions for more
+// information about how subscriptions are configured.
 func ExampleAdminClient_CreateSubscription() {
 	ctx := context.Background()
+	// NOTE: region must correspond to the zone of the topic and subscription.
 	admin, err := pubsublite.NewAdminClient(ctx, "region")
 	if err != nil {
 		// TODO: Handle error.
@@ -143,6 +157,7 @@ func ExampleAdminClient_CreateSubscription() {
 
 func ExampleAdminClient_UpdateSubscription() {
 	ctx := context.Background()
+	// NOTE: region must correspond to the zone of the subscription.
 	admin, err := pubsublite.NewAdminClient(ctx, "region")
 	if err != nil {
 		// TODO: Handle error.
@@ -162,6 +177,7 @@ func ExampleAdminClient_UpdateSubscription() {
 
 func ExampleAdminClient_DeleteSubscription() {
 	ctx := context.Background()
+	// NOTE: region must correspond to the zone of the subscription.
 	admin, err := pubsublite.NewAdminClient(ctx, "region")
 	if err != nil {
 		// TODO: Handle error.
@@ -175,6 +191,7 @@ func ExampleAdminClient_DeleteSubscription() {
 
 func ExampleAdminClient_Subscriptions() {
 	ctx := context.Background()
+	// NOTE: region must correspond to the zone below.
 	admin, err := pubsublite.NewAdminClient(ctx, "region")
 	if err != nil {
 		// TODO: Handle error.

pubsublite/pscompat/doc.go

@@ -15,9 +15,9 @@
 Package pscompat contains clients for publishing and subscribing using the
 Pub/Sub Lite service.
 
-The clients in this package are designed to compatible with the Cloud Pub/Sub
-library: https://pkg.go.dev/cloud.google.com/go/pubsub. If interfaces are
-defined by the client, PublisherClient and SubscriberClient can be used as
+This package is designed to compatible with the Cloud Pub/Sub library:
+https://pkg.go.dev/cloud.google.com/go/pubsub. If interfaces are defined by the
+client application, PublisherClient and SubscriberClient can be used as
 substitutions for pubsub.Topic.Publish() and pubsub.Subscription.Receive(),
 respectively, from the pubsub package.
 

pubsublite/pscompat/example_test.go

@@ -154,3 +154,31 @@ func ExampleSubscriberClient_Receive_maxOutstanding() {
 	// Call cancel from callback, or another goroutine.
 	cancel()
 }
+
+// This example shows how to manually assign which topic partitions a
+// SubscriberClient should connect to. If not specified, the SubscriberClient
+// will use Pub/Sub Lite's partition assignment service to automatically
+// determine which partitions it should connect to.
+func ExampleSubscriberClient_Receive_manualPartitionAssignment() {
+	ctx := context.Background()
+	const subscription = "projects/my-project/locations/zone/subscriptions/my-subscription"
+	settings := pscompat.DefaultReceiveSettings
+	// NOTE: The corresponding topic must have 2 or more partitions.
+	settings.Partitions = []int{0, 1}
+	subscriber, err := pscompat.NewSubscriberClientWithSettings(ctx, subscription, settings)
+	if err != nil {
+		// TODO: Handle error.
+	}
+	cctx, cancel := context.WithCancel(ctx)
+	err = subscriber.Receive(cctx, func(ctx context.Context, m *pubsub.Message) {
+		// TODO: Handle message.
+		// NOTE: May be called concurrently; synchronize access to shared memory.
+		m.Ack()
+	})
+	if err != nil {
+		// TODO: Handle error.
+	}
+
+	// Call cancel from callback, or another goroutine.
+	cancel()
+}