From f710d911590f82261e50b50742ddcdf352edb19c Mon Sep 17 00:00:00 2001
From: Yoshi Automation Bot <yoshi-automation@google.com>
Date: Thu, 27 Aug 2026 17:34:09 -0700
Subject: [PATCH] docs(pubsub): Add subscriber shutdown documentation and
 examples

1. Added a **Subscriber Shutdown Options** section to `README.md` demonstrating `:wait_for_processing`, `:nack_immediately`, and `shutdown_timeout: 30`.
2. Added YARD `@example` blocks on `Subscriber#listen` in `subscriber.rb` illustrating immediate nack on shutdown and custom timeout usage.
3. Verified documentation generation via `rake yard` and `rake doctest`.
---
 google-cloud-pubsub/README.md                 | 20 +++++++++++
 .../lib/google/cloud/pubsub/subscriber.rb     | 36 +++++++++++++++++++
 2 files changed, 56 insertions(+)

diff --git a/google-cloud-pubsub/README.md b/google-cloud-pubsub/README.md
index e7217eb456f7..2e6916306dd3 100644
--- a/google-cloud-pubsub/README.md
+++ b/google-cloud-pubsub/README.md
@@ -69,6 +69,26 @@ listener.start
 sleep
 ```
 
+### Subscriber Shutdown Options
+
+You can configure how the subscriber handles unprocessed messages when stopping via the `shutdown_behavior` and `shutdown_timeout` options:
+
+* `:wait_for_processing` (default) – Waits for all received messages to be processed and acknowledged by your callback before completing shutdown.
+* `:nack_immediately` – Immediately nacks all unprocessed messages back to Pub/Sub so other subscribers can pick them up quickly.
+
+```ruby
+# Immediately nack unprocessed messages on shutdown:
+listener = subscriber.listen shutdown_behavior: :nack_immediately do |msg|
+  process_message msg.data
+  msg.ack!
+end
+
+# Gracefully shut down with a 30-second timeout:
+listener = subscriber.listen shutdown_behavior: :wait_for_processing, shutdown_timeout: 30 do |msg|
+  process_message msg.data
+  msg.ack!
+end
+```
 
 ## Enabling Logging
 
diff --git a/google-cloud-pubsub/lib/google/cloud/pubsub/subscriber.rb b/google-cloud-pubsub/lib/google/cloud/pubsub/subscriber.rb
index 64b7d20caa26..e5ba6ed32852 100644
--- a/google-cloud-pubsub/lib/google/cloud/pubsub/subscriber.rb
+++ b/google-cloud-pubsub/lib/google/cloud/pubsub/subscriber.rb
@@ -418,6 +418,42 @@ def wait_for_messages max: 100
         #   # Shut down the subscriber when ready to stop receiving messages.
         #   listener.stop!
         #
+        # @example Immediately release unprocessed messages on shutdown:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   subscriber = pubsub.subscriber "my-topic-sub"
+        #
+        #   listener = subscriber.listen shutdown_behavior: :nack_immediately do |received_message|
+        #     # process message
+        #     puts "Data: #{received_message.message.data}"
+        #     received_message.acknowledge!
+        #   end
+        #
+        #   listener.start
+        #
+        #   # Shut down immediately, releasing (nacking) any unprocessed messages
+        #   listener.stop!
+        #
+        # @example Gracefully shut down with a custom timeout:
+        #   require "google/cloud/pubsub"
+        #
+        #   pubsub = Google::Cloud::PubSub.new
+        #
+        #   subscriber = pubsub.subscriber "my-topic-sub"
+        #
+        #   listener = subscriber.listen shutdown_behavior: :wait_for_processing, shutdown_timeout: 30 do |received_message|
+        #     # process message
+        #     puts "Data: #{received_message.message.data}"
+        #     received_message.acknowledge!
+        #   end
+        #
+        #   listener.start
+        #
+        #   # Wait up to 30 seconds for in-flight callbacks before forcing remaining to nack
+        #   listener.stop!
+        #
         def listen deadline: nil, message_ordering: nil, streams: nil, inventory: nil, threads: {},
                    shutdown_behavior: :wait_for_processing, shutdown_timeout: nil, &block
           ensure_service!