docs: add additional info on use_legacy_flow_control parameter (#301)

plamut · anguillanneuf · web-flow · commit f47523eda640 · 2021-04-13T10:33:18.000+02:00
* docs: add more details on use_legacy_flow_control

* asdsa

* Update google/cloud/pubsub_v1/subscriber/_protocol/streaming_pull_manager.py

* Update google/cloud/pubsub_v1/subscriber/client.py

* Remove "less accurate" from flow control docs

* Reword parameter description.

Co-authored-by: Tianzi Cai &lt;tianzi@google.com&gt;
diff --git a/google/cloud/pubsub_v1/subscriber/_protocol/streaming_pull_manager.py b/google/cloud/pubsub_v1/subscriber/_protocol/streaming_pull_manager.py
@@ -106,9 +106,10 @@ class StreamingPullManager(object):
             ``projects/{project}/subscriptions/{subscription}``.
         flow_control (~google.cloud.pubsub_v1.types.FlowControl): The flow
             control settings.
-        use_legacy_flow_control (bool): Disables enforcing flow control settings
-            at the Cloud PubSub server and uses the less accurate method of only
-            enforcing flow control at the client side.
+        use_legacy_flow_control (bool):
+            If set to ``True``, flow control at the Cloud Pub/Sub server is disabled,
+            though client-side flow control is still enabled. If set to ``False``
+            (default), both server-side and client-side flow control are enabled.
         scheduler (~google.cloud.pubsub_v1.scheduler.Scheduler): The scheduler
             to use to process messages. If not provided, a thread pool-based
             scheduler will be used.
diff --git a/google/cloud/pubsub_v1/subscriber/client.py b/google/cloud/pubsub_v1/subscriber/client.py
@@ -146,8 +146,8 @@ def subscribe(
         a long time to process.
 
         The ``use_legacy_flow_control`` argument disables enforcing flow control
-        settings at the Cloud PubSub server and uses the less accurate method of
-        only enforcing flow control at the client side.
+        settings at the Cloud Pub/Sub server, and only the client side flow control
+        will be enforced.
 
         This method starts the receiver in the background and returns a
         *Future* representing its execution. Waiting on the future (calling
@@ -200,6 +200,10 @@ def callback(message):
                 *scheduler* to use when executing the callback. This controls
                 how callbacks are executed concurrently. This object must not be shared
                 across multiple SubscriberClients.
+            use_legacy_flow_control (bool):
+                If set to ``True``, flow control at the Cloud Pub/Sub server is disabled,
+                though client-side flow control is still enabled. If set to ``False``
+                (default), both server-side and client-side flow control are enabled.
             await_callbacks_on_shutdown (bool):
                 If ``True``, after canceling the returned future, the latter's
                 ``result()`` method will block until the background stream and its
